How-tos

7 mins read

Set Up Azure AD for Authentication with OIDC

Instructions on how to connect applications registered in Azure Active Directory as Cloudentity's (Cloudentity's) Identity Providers so that you can connect a user pool from Azure to Cloudentity in accordance with the Bring Your Own Identity (BYOID) principle.

About Azure AD as IDP

Azure AD is natively supported by Cloudentity as an OIDC Identity Provider, which means that it has a dedicated connection template in Cloudentity for your convenience. Azure AD applications implement the OIDC protocol, providing the proof of user authentication to Cloudentity within an ID Token and Access Token.

Azure AD and SAML

Azure AD applications can also use the SAML protocol, but this integration is not natively supported by Cloudentity yet. If necessary, you can use the generic SAML connector to bind Azure AD apps via SAML.

The client authorization flow with Cloudentity connected to Azure AD looks as follows:

[mermaid-begin]
sequenceDiagram participant Client app participant Cloudentity participant Azure IDP Client app->>Cloudentity: Request authorization code Cloudentity->>Azure IDP: Request authorization code Azure IDP-->>Azure IDP: Authenticate user Azure IDP-->>Azure IDP: Ask user for consent to share data with Cloudentity Azure IDP-->>Cloudentity: Issue authorization code Cloudentity->>Azure IDP: Request tokens using the code Azure IDP-->>Cloudentity: Issue tokens Cloudentity->>Azure IDP: Pull user/group information using Graph API Azure IDP-->>Cloudentity: Return data from Graph API Cloudentity-->>Cloudentity: Ask user for consent to share data with client app Cloudentity-->>Client app: Issue authorization code Client app->>Cloudentity: Request tokens using the code Cloudentity-->>Client app: Issue tokens requested by the app

The following steps in the flow are optional:

  • Cloudentity only pulls user and group information if this option is explicitly enabled in the Azure connector configuration, as explained later in this document.
  • Cloudentity only asks for consent if the client application is not marked as trusted and requests scopes which were not granted previously (or scopes for which the user’s consent has been withdrawn).

Prerequisites

You need to configure an application in Azure Active Directory that Cloudentity can connect with. Follow the Azure getting started guide to do so.

If you want Cloudentity to fetch user attributes or groups from Azure Graph, make sure that your application has the necessary permissions to do so. For more information, read the following Graph API documentation:

Connect Azure IDP to Cloudentity

When your application in the Azure portal is ready (apart from the Redirect URI which it needs from Cloudentity), you can proceed to connecting it to Cloudentity.

Basic Configuration

  1. In your workspace landing page, select Authentication » Providers » Create Connection to add a new connection.

  2. In the Create Connection page, select Microsoft Azure AD from the list of the predefined IDP templates and click Next.

  3. Copy the Redirect URL from the form and add it as your app’s Redirect URI in Azure.

  4. Fill in the form.

    Parameter Description
    Name Name for your Cloudentity’s Azure connection. This name allows users to identify the IDP they need to authenticate with.
    Tenant ID Azure Tenant ID where your application is registered
    Client ID Client ID of the OAuth application registered in Azure
    Client secret Secret Value of the OAuth application registered in Azure

    Copy The Azure Client Secret Value

    The client secret is needed in the Client Secret Field from Azure. Copy it immediately. You will lose access to it after navigating away.

  5. Optionally, enable Authentication context caching.

    Tip

    You can enable the authentication context caching if you wish to store the user’s authentication context locally. If you do, specify the cache Time To Live as well. Learn more by reading Stateful authorization with Cloudentity.

  6. Save your changes. You can now configure the advanced settings for your IDP or try it out right away.

Configure Advanced Settings

Advanced settings contain optional features which may be necessary to use in specific cases. To configure your new IDP advanced settings

  1. From the Authentication » Providers » YOUR_IDENTITY_PROVIDER » Configuration page, select Advanced settings at the bottom.

  2. In the Scopes field, add additional scopes to be requested when authenticating to the IDP (by default openid, email, and profile scopes are requested).

    Note

    Since multiple clients can use the same IDP for user authentication, you may need to further restrict specific client’s ability to request a given scope. For more information, read about Configuring applications in Cloudentity.

  3. In the Authentication Method Reference you can select an authentication method to be written into the amr object returned by the IDP. The amr object is written if it doesn’t exist. If it exists, its values are replaced with the selected item.

    Tip

    You can also use an extension script to modify amr values. If you do, keep in mind that the script is executed after the amr injection from this field, so the values injected by the script are final.

  4. Enable the Fetch user attributes option to fetch additional user information via the Azure Graph API.

  5. Enable the Fetch groups options to get the user’s group membership information

    • Select Only security groups to send the request with the securityEnabledOnly flag, which limits the groups returned by the Graph API to security groups only. All groups are returned otherwise.

    • Select ID or Name from Group name format to decide how the groups are returned (either by their name or ID).

  6. Select Save.

Add Custom IDP Attributes

If your IDP returns custom claims outside of the standard Azure scope, make sure to add them to the IDP connector so that they can be recognized and mapped to the authentication context.

  1. Go to Authentication » Providers and select an IDP from the list.

  2. Open the Attributes page. A standard list of attributes returned by this IDP appears. In most cases, these attributes conform either to the OIDC or SAML specification.

  3. Select Add attribute.

  4. In Source, select the data source for the custom attribute

    Source Description
    Access token Get data from the access token received from the IDP
    ID token Get data from the ID token received from the IDP
    Azure graph Get data data returned by the Azure Graph API
  5. Fill in the rest of the form.

    Option Description
    Claim name Name of your custom attribute
    Display name User-friendly name for the custom attribute
    Data type Data type matching that of the incoming IDP claim
  6. Save your changes and proceed to mapping the attributes to the authentication context.

Map IDP Attributes to Authentication Context

If you’ve added custom attributes for an IDP, you need to make sure they are mapped to the {{< product-name acp >}} authentication context. You can do it either from the IDP configuration page (as explained here) or use Data Lineage instead.

Default OIDC/SAML attributes are mapped out of the box.

  1. Go to {{% nav-paths/idps %}} and select an IDP from the list.

  2. Open the Mappings page. A standard attribute mapping for this IDP appears.

  3. Select Add mapping and map any custom IDP attributes to an existing authentication context attribute.

    Note

    If you need to create new authentication context attributes, read the Managing Authentication Context.

  4. Optionally, you can enrich authentication context before issuing the token to the client. Attributes returned by the script do not need to be separately mapped to the authentication context.

  5. Save your changes. Your mapped custom attributes should now be shared in the ID token issued to your client application, given that the target application requests them (you can check this in Data Lineage).

Connect Extensions to your IDP

  1. Go to {{% nav-paths/idps %}} » YOUR_IDP » Extensions.

  2. Assign a Post Authentication script to the IDP. This script will be executed upon user authentication via this IDP.

  3. Connect your application to the IDP in the Post Authentication application field. Users will be redirected to this application upon authentication via this IDP.

    Feature flag

    Post Authentication applications must be explicitly enabled in your tenant using the custom_apps feature flag.

Test IDP

Prerequisites

  • Your IDP is enabled for user authentication.
  • Demo workspace is created with the Demo Portal connected.

Test

  1. Open the Demo Portal (Data lineage -> Demo Portal -> Launch).

  2. Select LOGIN TO DEMO APP.

  3. Select your configured IDP and, next, authenticate in IDP.

Result

Cloudentity displays the consent page that lists data scopes to be shared with the application. When you proceed to the application (ALLOW ACCESS), the PII data coming from Azure AD is delivered through the access token and the ID token generated by Cloudentity.

Read More

For information on granting and managing Cloudentity consents, see Cloudentity OAuth consents.

Having connected and tried out your Azure AD IDP, check the following resources:

Updated: Nov 2, 2023