Introduction
This article will walk you through configuring Azure AD as an OIDC identity provider (IdP) for HelloID.
Register HelloID with Azure AD
- Log in to your Azure portal at https://portal.azure.com/.
- Select the Azure Active Directory button.
- Select the App registrations link under the Manage menu.
- Select the New registration button.
- Enter
HelloID
for the Name. - Select your desired option for Who can use this application or access this API.
- Enter the following URL into the Redirect URI field:
https://customer.helloid.com/azureadoidcauthentication/consumeoidc
. Replacecustomer.helloid.com
with your HelloID portal base URL. - Select the Register button to save and open the new app.
- Select the Authentication link under the Manage menu.
- Enter the following URL into the Logout URL field:
https://customer.helloid.com/authentication/signoff
. Replacecustomer.helloid.com
with your HelloID portal base URL. - Select the ID tokens option under the Implicit grant section.
- Select the Save button.
- Select the Certificates & secrets link under the Manage menu.
- Select the New client secret button. Enter an optional description and select your preferred expiration period.
- Select the Add button.
- 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.)
- Select the API permissions link.
- Go to Add a permission > Microsoft Graph > Delegated permissions. Select the following permissions:
AccessReview.Read.All
Directory.AccessAsUser.All
email
openid
profile
User.Read
- Select the Add permissions button to confirm your changes.
- Select the Grant admin consent for Default Directory button to grant admin consent for all users.
- Select the Yes button to confirm.
Configure the Azure AD OIDC IdP in HelloID
- Go to Security > Authentication > Identity providers in your HelloID admin dashboard. Select the Create Provider button.
- Select the Add button for Azure AD OpenID Connect.
- Select the Configuration tab.
- Enter the following information:
- 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 trailingauthorize
on this URL. - Logout URL
Enterhttps://login.microsoftonline.com/common/oauth2/logout
. - 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. - Client Secret
Paste the client secret value you copied into a separate notepad application in step 15 of the previous section.
- Login URL
- The required scopes are already added as defaults under Additional Scopes. Add additional scopes if needed.
- Configure additional options as needed. View a complete reference of IdP options here.
- Select the Save button to confirm.
- 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.
- Go to Directory > Mapping sets.
- Select the Edit link for the IdP Mapping for Azure AD OpenID Connect.
- Select the Change mappings link.
- Select the X button to remove the following mapping:
User HelloID User {{user.oid}}
user.immutableId
- Select the Close button.
- Select the Set Identifier link.
- Set the unique identifier as follows:
OIDC Provided User HelloID User {{user.preferred_username}}
Username
- Select the Close button.
- 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.
- In HelloID, go to Security > Authentication > Identity providers.
- Select the Edit link for the Azure AD OIDC IdP.
- Select the Configuration tab.
- Turn on the Retrieve 'On-behalf-of' token and store to user attributes toggle. This automatically adds and maps
onbehalfoftoken
andonbehalfofrefreshtoken
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. - In a new browser tab, go to Azure Active Directory > App registrations in your Azure portal.
- Select the
HelloID
app that you registered earlier, in the section Register HelloID with Azure AD. - Copy its Application (client) ID to a separate notepad app. You will need it shortly.
- In Azure AD, go back to App registrations.
- Select the target app which users will SSO into from HelloID (the app to which the on-behalf-of tokens will be passed).
- Select the Expose an API link.
- Select the Add a scope link.
- Accept the default Application ID URI. Select the Save & continue button.
- Enter your desired scopes.
- Select the Add scope button to confirm.
- 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
) - In HelloID, paste it into the On Behalf of Scopes field of the Configuration tab.
- Select the Save button.
- In Azure AD, return to the Expose an API page for the target application.
- Select the Add a client application button.
- Paste the
HelloID
app's Application (client) ID value you copied in step 7 into the Client ID field. - Under Authorized scopes, select the check box for the scope you created in step 13.
- Select the Add application button to confirm.
- Select the Certificates & secrets link.
- Select the New client secret link.
- Enter a Description and an expiration period.
- Select the Add button to confirm.
- Copy the client secret that appears under the Value column.
- In HelloID, paste it into the On Behalf of Client Secret field of the Configuration tab.
- Select the Save button to confirm.
- Go to Directory > Mapping sets and select the Edit link for the target application which will require these tokens. For example:
- Select the Change attributes link to add
On behalf of
andOn behalf of Refresh
attributes withonBehalfOf
andonBehalfOfRefresh
for the External Field values, respectively. Learn more about mapping sets here. - Select the Close button when done.
- 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
- Select the Close button when done.
- 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.