Hub 2022.2 Help

Azure AD Auth Module

The Azure AD authentication module is a pre-configured auth module that lets users log in to Hub and any connected services with their Azure AD accounts.

Custom Tenant Setup

When you follow this setup, logins are restricted to users whose accounts are stored in your Azure AD instance. If you want to accept login requests from any Azure Active Directory (AD) tenant, follow the instructions for a common tenant.

When you create an Azure AD module for a custom tenant, you provide the tenant ID of the custom tenant when you create the auth module. This automatically adds your Azure Tenant ID to the authorization and token endpoints that are used by the auth module.

To learn how to set up a new tenant, please refer to the Microsoft Azure documentation.

To create the Azure AD module:

  1. In the Access Management section of the Administration menu, select Auth Modules.

  2. From the New Module drop-down list, select Azure AD.

    • The New Azure AD Module dialog opens.

      New azure auth custom tenant
  3. Enter a name for the module in the Name field.

  4. Paste the value from the Tenant ID field in Microsoft Azure into the Tenant field.

  5. Click the Create button in the dialog.

    • The Auth Modules page displays the settings for a new Azure AD authentication module.

    • Hub generates a redirect URI for you to use in the authorization service.

      Azure auth custom tenant redirect uri
  6. If the feature is supported by your browser, use the Copy button to copy the redirect URI to your clipboard.

The next step is to register the authorized redirect URI for Hub in the Microsoft Azure portal. This gives you access to the client ID and secret that you need to enable the Azure AD authentication module.

To learn how to perform this setup, please follow the instructions in the product documentation for Microsoft Azure.

The following table lists the key configuration options that are required for this authentication module:

Setting

Description

Supported account types

This determines who can use the application, sometimes called its sign-in audience.

For this setup, choose the Accounts in this organizational directory only (Single tenant) option.

Redirect URI

Paste the redirect URI from Hub into the input field. For the type, select the Web option.

Application (client) ID

his value is automatically generated when you register the application in the Azure portal.

Use the value from this field as the Client ID setting in Hub.

Client secret | Value

This value is generated in the Certificates & secrets section of the App registration experience.

Once you have added a client secret for the application, use the value for the client secret as the Client secret in Hub.

Once you have the values that are required to connect with the authorization service, you can enable the Azure AD auth module.

To enable the Azure AD auth module:

  1. Copy the Application (client) ID from Microsoft Azure and paste it into the Client ID input field in the Hub auth module.

  2. Copy the value for the Client secret from Microsoft Azure and paste it into the Client secret input field in Hub.

  3. Configure the optional settings for the authentication module. For more information, see Additional Settings.

  4. Click the Save button at the bottom of the page.

  5. Click the Enable module button in the header.

    • The Azure AD authentication module is enabled.

    • The icon stored in the Button image setting is added to the login dialog window. Users can click this icon to log in to Hub with their Microsoft accounts.

Common Tenant Setup

An Azure AD module that uses the endpoint for common tenants follows the standard setup for an OAuth 2.0 auth module. This setup accepts login requests from any Azure Active Directory (AD) tenant, including users who are not members of your organization. If you want to restrict logins to users who are registered in your company's Azure AD instance, follow the instructions for a custom tenant.

Your first step is to create an auth module and generate a redirect URI in Hub.

To generate a redirect URI in Hub:

  1. In the Access Management section of the Administration menu, select Auth Modules.

  2. From the New module drop-down list, select Azure AD.

    • The New Azure AD Module dialog opens.

      New azure auth common tenant
  3. Enter a name for the module in the Name field.

  4. Leave the Tenant ID field empty.

  5. Click the Create button in the dialog.

    • The Auth Modules page displays the settings for a new Azure AD authentication module.

    • Hub generates a redirect URI for you to use in the authorization service.

      Azure auth common tenant redirect uri
  6. If the feature is supported by your browser, use the Copy button to copy the redirect URI to your clipboard.

Make sure to update the Redirect URI in the authorization service when you change the base URL of your Hub installation. For example, after migrating data to another Hub service or changing proxy settings.

The next step is to register the authorized redirect URI for Hub in the Microsoft Azure portal. This gives you access to the client ID and secret that you need to enable the Azure AD authentication module.

To learn how to perform this setup, please follow the instructions in the product documentation for Microsoft Azure.

The following table lists the key configuration options that are required for this authentication module:

Setting

Description

Supported account types

This determines who can use the application, sometimes called its sign-in audience.

Choose whichever option best matches your intended audience for Hub.

Redirect URI

Paste the redirect URI from Hub into the input field. For the type, select the Web option.

Application (client) ID

his value is automatically generated when you register the application in the Azure portal.

Use the value from this field as the Client ID setting in Hub.

Client secret | Value

This value is generated in the Certificates & secrets section of the App registration experience.

Once you have added a client secret for the application, use the value for the client secret as the Client secret in Hub.

Once you have the values that are required to connect with the authorization service, you can enable the Azure AD auth module.

To enable the Azure AD auth module:

  1. Copy the Application (client) ID from Microsoft Azure and paste it into the Client ID input field in Hub.

  2. Copy the value for the Client secret from Microsoft Azure and paste it into the Client secret input field in Hub.

  3. Configure the optional settings for the authentication module. For more information, see Additional Settings.

  4. Click the Save button at the bottom of the page.

  5. Click the Enable module button in the header.

    • The Azure AD authentication module is enabled.

    • The icon stored in the Button image setting is added to the login dialog window. Users can click this icon to log in to Hub with their Microsoft accounts.

Settings

The first section of the settings page displays the general settings for the authentication module. Here, you also find the redirect URI that you use to register Hub in the authorization service and the input fields that store the Client ID and Client Secret that are generated in the authorization service.

Setting

Description

Type

Displays the type of authorization service that is enabled for third-party authentication in Hub.

Name

Stores the name of the authentication module. Use this setting to distinguish this module from other authentication modules in the Auth Modules list.

Button image

Displays the image used for the button that a user clicks to log in to Hub with a their account in the connected authorization service. You can upload a JPG, GIF or PNG file. The image is resized to 48 x 48 pixels automatically.

Redirect URI

Displays the authorized redirect URI that is used to register the connection to Hub in the authorization service.

Client ID

Stores the identifier that the authorization service uses to validate a login request. You generate this value in the authorization service when you configure the authorization settings for a web application and enter an authorized redirect URI.

Client Secret

Stores the secret or password used to validate the client ID. You generate this value in the authorization service together with the client ID.

Tenant ID

Stores the ID of the custom tenant in the Azure AD service. For auth modules that are connected to a common tenant, this field is empty.

Field Mapping

If you have added custom attributes to user profiles, these attributes can also be mapped to attributes that are stored in the authorization service. Each custom attribute is listed by name with an input field for storing the name of corresponding field in the authorization service.

Field mapping settings for an Azure AD authentication module

To learn more about custom attributes in user profiles, see Manage Custom Attributes.

When a user profile response object is returned by Azure AD, values from the specified field paths are copied to the user profile in Hub. Use the following settings to define the endpoint that locates profile data for the authenticated user and map fields that are stored in the authorization service to user accounts in Hub.

  • To specify paths to fields inside nested objects, enter a sequence of segments separated by the slash character (/).

  • To reference values that may be stored in more than one location, use the "Elvis operator" (?:) as a delimiter for multiple paths. With this option, Hub uses the first non-empty value it encounters in the specified field.

Additional Settings

The following options are located at the bottom of the page. These settings let you define the request scope and choose how to authenticate with the service.

Other options in this section let you manage Hub account creation and group membership and reduce the loss of processing resources consumed by idle connections.

Option

Description

User creation

Enables creation of Hub accounts for unregistered users who log in with an account that is stored in the connected authorization service. Hub uses the email address to determine whether the user has an existing account.

Auto-join groups

Adds users to a group when they log in with an account that is stored in the connected authorization service. You can select one or more groups. New users that auto-join a group inherit all of the permissions assigned to this group.

We recommend that you add users to at least one group. Otherwise, a new user is only granted the permissions that are currently assigned to the All Users group.

Connection timeout

Sets the period of time to wait to establish a connection to the authorization service. The default setting is 5000 milliseconds (5 seconds).

Read timeout

Sets the period of time to wait to read and retrieve user profile data from the authorization service. The default setting is 5000 milliseconds (5 seconds).

Audit

Links to the Audit Events page in Hub. There, you can view a list of changes that were applied to this authentication module.

Group Mappings

On the Group Mappings tab, you can map existing groups in the authorization service to the groups in Hub.

Group mappings for Azure AD accounts.

The Azure AD module automatically maps the attribute that stores Azure AD group memberships to the field that stores membership records in the Hub database. All you need to do is map the groups in the Azure AD service to their counterparts in Hub.

When group mappings are configured, Hub checks for Azure AD group memberships when users log in with accounts that are managed in the directory service. Hub performs the following operations for each Azure AD group that is mapped to a Hub group:

  • Users who are members of a mapped Azure AD group and are not members of the mapped Hub group are added to the group in Hub.

  • Users who are not members of a mapped Azure AD group and are members of the mapped Hub group are removed from the group in Hub.

Changes to group memberships in the authorization service are only applied in Hub when users log in using their Azure AD accounts.

You can map multiple Azure AD groups to a single target group in Hub. You can't map Azure AD groups to more than one Hub group.

To map group from Azure AD to a group in Hub:

  1. Open your Azure AD auth module.

  2. Select the Group Mappings tab.

  3. Click the Add mapping button.

    • The Add Mapping dialog opens.

    Dialog for adding group mappings.
  4. Enter the name of the Azure AD group in the OAuth group name field.

  5. Select a group from the Target group list.

  6. Click the Add button.

    • The mapping is added to the list.

Migration from the Azure AD 2.0 Auth Module

During migration to Hub versions 2022.2 and later, older Azure AD 2.0 authentication modules are deactivated automatically. To continue to let users sign in to Hub and the services that are connected to it with their Azure AD accounts, you need to migrate to the updated version of the authentication module.

  • One option is to delete the deactivated module and set up a new Azure AD authentication module from scratch.

  • You also have the option to copy the existing client ID and client secret that are stored in the deactivated module to the new authentication module and register the redirect URI for the new module in Microsoft Azure.

To register the redirect URI for the new module:

  1. From the Administration menu, select Access Management > Auth Modules.

  2. Select the deactivated Azure AD 2.0 authentication module from the list.

  3. Open the Auth Modules page in a separate window or browser tab.

  4. From the New module drop-down list, select Azure AD.

    • The New Azure AD Module dialog opens.

      New azure auth common tenant
  5. Enter a name for the module in the Name field.

  6. If you're working with a custom tenant setup, copy the value for the Tenant ID from the deactivated module and paste it into the intput field for the new module. If working with a common tenant setup, leave the Tenant ID field empty.

  7. Click the Create button in the dialog.

    • The Auth Modules page displays the settings for a new Azure AD authentication module.

    • Hub generates a redirect URI for you to use in the authorization service.

      Azure auth common tenant redirect uri
  8. If the feature is supported by your browser, use the Copy button to copy the new redirect URI to your clipboard.

  9. Navigate to your existing application in Microsoft Azure portal.

  10. Add the new redirect URI to the list of redirect URIs that are registered for the application. If you want to remove the redirect URI for the deactivated module, it's safe to do so now as well.

  11. Switch back to the deactivated Azure AD 2.0 auth module in Hub.

  12. Copy the value that is stored as the Client ID, switch to the new authentication module, then paste this value in to the Client ID field there.

  13. Switch back to the deactivated module and copy the value that is stored as the Client secret. Switch back to the new authentication module and paste this value in to the Client field field there.

  14. Click the Save button at the bottom of the page.

  15. Click the Enable module button in the header.

    • The new Azure AD authentication module is enabled.

    • The icon stored in the Button image setting is added to the login dialog window. Users can click this icon to log in to Hub with their Microsoft accounts.

  16. Click the Auth Modules link to return to the list of authentication modules.

  17. Select the deactivated Azure AD 2.0 module from the list.

  18. Click the Delete button in the toolbar.

    Option to delete the selected authentication module.
  19. Click the Delete button in the confirmation dialog.

Last modified: 28 June 2022