Introduction

This article will walk you through configuring Azure AD as an OIDC identity provider (IdP) for HelloID.

Register HelloID with Azure AD

1. Log in to your Azure portal at https://portal.azure.com/.
2. Select the Azure Active Directory button.
3. Select the App registrations link under the Manage menu.
4. Select the New registration button.
5. Enter HelloID for the Name.
6. Select your desired option for Who can use this application or access this API.
7. Enter the following URL into the Redirect URI field: https://customer.helloid.com/azureadoidcauthentication/consumeoidc. Replace customer.helloid.com with your HelloID portal base URL.
8. Select the Register button to save and open the new app.
9. Select the Authentication link under the Manage menu.
10. Enter the following URL into the Logout URL field: https://customer.helloid.com/authentication/signoff. Replace customer.helloid.com with your HelloID portal base URL.
11. Select the ID tokens option under the Implicit grant section.
12. Select the Save button.
13. Select the Certificates & secrets link under the Manage menu.
14. Select the New client secret button. Enter an optional description and select your preferred expiration period.
15. Select the Add button.
16. The client secret appears under the Client secrets section. Copy its Value into a separate notepad app for later use. (Important, because you won't be able to view it again.)
17. Select the API permissions link.
18. Go to Add a permission > Microsoft Graph > Delegated permissions. Select the following permissions:
    1. AccessReview.Read.All
    2. Directory.AccessAsUser.All
    3. email
    4. openid
    5. profile
    6. User.Read
19. Select the Add permissions button to confirm your changes.
20. Select the Grant admin consent for Default Directory button to grant admin consent for all users.
21. Select the Yes button to confirm.

Configure the Azure AD OIDC IdP in HelloID

1. Go to Security > Authentication > Identity providers in your HelloID admin dashboard. Select the Create Provider button.
   
2. Select the Add button for Azure AD OpenID Connect.
   
3. Select the Configuration tab.
   
4. Enter the following information:
   1. Login URL
      In your Azure portal, go to Azure Active Directory > App registrations > HelloID and select the Endpoints button. Copy the OAuth 2.0 authorization endpoint (v2) value and paste it into this field. Remove the trailing authorize on this URL.
   2. Logout URL
      Enter https://login.microsoftonline.com/common/oauth2/logout.
   3. Client Identifier
      In your Azure portal, go to Azure Active Directory > App registrations > HelloID. Copy the Application (client) ID value and paste it into this field.
   4. Client Secret
      Paste the client secret value you copied into a separate notepad application in step 15 of the previous section.
5. The required scopes are already added as defaults under Additional Scopes. Add additional scopes if needed.
6. Configure additional options as needed. View a complete reference of IdP options here.
7. Select the Save button to confirm.
   
8. If integration with Azure Graph API is required, please follow these instructions in the section below, Retrieve the "on-behalf" token.

Modify default attribute mappings (if using Azure AD Connect)

You must modify the default Azure AD mapping set if:

• You are already syncing an on-premise AD environment to HelloID, and;
• You plan to use the Azure AD OIDC IdP as an alternate login method for these users, and;
• Your Azure AD users are created from your on-premise AD environment via Azure AD Connect.

By default, Agent retrieves an on-premise AD user's objectSid value and writes it to the user.immutableId field in the synced HelloID user. It then uses this field its unique identifier. However, the Azure AD mapping set does the same thing, except using the Azure AD oid value (which was previously set by Azure AD Connect to a base64 transformation of the AD objectGUID).

This causes a conflict because the two systems each overwrite the HelloID user.immutableId field with different values, while also attempting to use user.immutableId as their unique identifier. This results in failure to correlate to the correct user accounts, and/or creation of duplicate accounts.

Resolve this by adjusting the mapping set as follows. This solves this problem by using Azure AD's preferred_username (mapped by default to the HelloID user.userName field) as the Azure AD OIDC IdP's unique identifier. Your on-premise AD environment can then safely continue to use AD's objectSid mapped to the HelloID user.immutableId field as its unique identifier.

In this way, both on-premise AD and Azure AD will now correlate to the correct HelloID user without any conflicts.

1. Go to Directory > Mapping sets.
2. Select the Edit link for the IdP Mapping for Azure AD OpenID Connect.
3. Select the Change mappings link.
4. Select the X button to remove the following mapping:
   

   User	HelloID User
   {{user.oid}}	user.immutableId

   

5. Select the Close button.
6. Select the Set Identifier link.
7. Set the unique identifier as follows:
   

   OIDC Provided User	HelloID User
   {{user.preferred_username}}	Username

   

8. Select the Close button.
9. Select the Save button to confirm.

Retrieve the "on-behalf" token (optional)

You can store the on-behalf-of and on-behalf-of-refresh tokens from Azure AD inside HelloID user attributes. In this way, the tokens can be passed through to any SSO applications that users log into from HelloID. The applications can then use these tokens to directly access the Azure Graph API on behalf of the users, without requiring re-authentication.

As prerequisites, you must have already done the following:

• Set up Azure AD as an OIDC IdP in HelloID, as per the above instructions
• Added the target application(s) to which you want to pass the on-behalf-of tokens, to both HelloID (as SSO application(s)) and Azure AD (as registered apps)

It is recommended to use multiple browser tabs while following these instructions. You will be copying and pasting several values between Azure AD and HelloID.

1. In HelloID, go to Security > Authentication > Identity providers.
2. Select the Edit link for the Azure AD OIDC IdP.
   
3. Select the Configuration tab.
4. Turn on the Retrieve 'On-behalf-of' token and store to user attributes toggle. This automatically adds and maps onbehalfoftoken and onbehalfofrefreshtoken attributes to all users who log in via the Azure AD IdP, without requiring you to manually add these attributes to the Azure OIDC IdP's mapping set. Leave this browser tab open, without selecting the Save button yet.
   
5. In a new browser tab, go to Azure Active Directory > App registrations in your Azure portal.
6. Select the HelloID app that you registered earlier, in the section Register HelloID with Azure AD.
7. Copy its Application (client) ID to a separate notepad app. You will need it shortly.
8. In Azure AD, go back to App registrations.
9. Select the target app which users will SSO into from HelloID (the app to which the on-behalf-of tokens will be passed).
10. Select the Expose an API link.
11. Select the Add a scope link.
12. Accept the default Application ID URI. Select the Save & continue button.
13. Enter your desired scopes.
14. Select the Add scope button to confirm.
15. Copy the api:// value which appears under the Scopes column in the Azure AD Expose an API screen. (For example: api://37c086f5-bdc7-4f88-955c-49cb7c3d711d/Files.Read)
16. In HelloID, paste it into the On Behalf of Scopes field of the Configuration tab.
    
17. Select the Save button.
18. In Azure AD, return to the Expose an API page for the target application.
19. Select the Add a client application button.
20. Paste the HelloID app's Application (client) ID value you copied in step 7 into the Client ID field.
21. Under Authorized scopes, select the check box for the scope you created in step 13.
22. Select the Add application button to confirm.
23. Select the Certificates & secrets link.
24. Select the New client secret link.
25. Enter a Description and an expiration period.
26. Select the Add button to confirm.
27. Copy the client secret that appears under the Value column.
28. In HelloID, paste it into the On Behalf of Client Secret field of the Configuration tab.
    
29. Select the Save button to confirm.
30. Go to Directory > Mapping sets and select the Edit link for the target application which will require these tokens. For example:
    
31. Select the Change attributes link to add On behalf of and On behalf of Refresh attributes with onBehalfOf and onBehalfOfRefresh for the External Field values, respectively. Learn more about mapping sets here.
    
    
32. Select the Close button when done.
33. Select the Change mappings link to map the newly-created user attributes as follows:

    User Attribute	HelloID Claim Set Variable
    {{user.attributes.onbehalfoftoken}}	On behalf of
    {{user.attributes.onbehalfofrefreshtoken}}	On behalf of Refresh

    
34. Select the Close button when done.
35. Select the Save button to confirm.

The on-behalf-of and on-behalf-of-refresh tokens will now be passed through to the configured application when an end user selects it in the Applications tab of the HelloID end user dashboard. The application will have access to the Azure Graph API without any additional authentication by the user.