OAuth - Microsoft Entra ID Application

Overview

The details below guide you through creating an Entra ID Application and then configuring it for your needs. The key information required is listed below:

  • Application Identifiers

    • Application (Client) ID​

    • OAuth 2.0 authorization endpoint (v2)​

    • OAuth 2.0 token endpoint (v2)​

  • For User Flow​

    • Scope (User Flow)​

    • Platform configurations​

    • Redirect URI​

  • For Userless Flow​

    • Client Secret​

    • Application ID URI (Userless Flow)​

Step 1 - New Registration

  1. Once you have logged into the Entra ID portal, click the menu icon on the top left corner and select "Microsoft Entra ID".

    Screenshot of accessing the Microsoft Entra ID​

  2. Expand the Manage menu section and select "App Registrations".

    Screenshot of the App Registrations menu

    ​

  3. Click on the [+New Registration] button.

    Screenshot of the New Registration button

  4. Under the Name section, enter a name for the application. This can be changed later, if needed.​

  5. Under the Supported Account Types section, there is no change needed unless you want to allow access for any Entra ID tenant. This is specific to interactive flow which the user needs to authenticate.

  6. The Redirect URI section is optional. It depends on the use case with this application.

  7. Click the [Register] button.

    Screenshot of the Register An Application section

Step 2 - Token Configuration

  1. Under the Manage menu, select "Token Configuration".​

  2. Click on Add Optional Claim.

  3. Set the Token Type field to "Access".​

  4. Select "Claim​" and check the following boxes:

    • email

    • ipaddr​

    • upn

  5. Click the [Add] button.

    Screenshot of the Token Configuration screen

  6. If prompted to turn on Microsoft Graph permissions, check the box and click the [Add] button. These are delegated permissions.

    Screenshot of the Add Optional Claim pop-up window

Step 3 - Expose an API

  1. Under the Manage menu, select "Expose an API".​

  2. Click Add to the right of the Application ID URI header.​

  3. Leave the default value in the Application ID URI field

  4. Click the [Save] button.

    Screenshot of the Expose an API screen

  5. In the Expose an API screen, click the [+ Add a Scope] button to add a scope that is used when requesting a token for the authenticated user, and can be consumed by CMiC API.​ This is required for user interactive flow.

    Screenshot of the Add a Scope screen

Step 4 - Manifest

Screenshot of the Manifest screen

  1. Under the Manage section, select "Manifest".

  2. Change requestedAccessTokenVersion from "null" to "2".​ This changes the version and format of the JWT produced independent of the endpoint.​

  3. Click [Save].

Step 5 - Additional Configuration

Now that the base configuration is complete, next is additional setup that’s needed depending on your OAuth flow.​

  • User interactive​ (e.g. Applications)​

  • Userless/non-interactive​ (e.g. Server to server communication)​

CMiC does not support userless tokens prior to Nexus 1, to avoid unexpected results do not use the same application for both flows.

​User Flows

IMPORTANT: Before you can safely use this with CMiC, be aware of how you are creating users in CMiC. Issues will be present if users are not created in a uniform way, which can be mapped to a specific attribute from your Identity provider (IdP) or translated from some attribute. For example, Are you setting the username to email?​

If email attribute does not correlate to a CMiC username, it would require the custom claim “cmicuser” to be configured on your application.

This will require setup for the Platform Redirect URI, such as single-page application, iOS app, or Android app.

CMiC User Configuration

It’s important to know that with federation (Entra ID), the key attributes in a token related to the user are upn and email claims.​ Inside CMiC, it would be expected that you have a CMiC username to match the value.​

We rely on the email claim first, but if it's not present, then we use the upn claim.​ If there happens to be a custom claim “cmicuser”, this will be first, then email, then upn.​

Thus ​, there is no additional setup required, but there are conditions where you may need to do add a custom claim “cmicuser” when email or upn is not what a user would enter during single sign-on (SSO). For example, there is no federated SSO​, or there is a federated SSO, but the user created in CMiC matches the email or upn from the Identity Provider (IdP) user’s identity.​​

This might not be trivial or possible if there is no uniform way to translate a user’s IdP attribute to what’s expected in CMiC.​

For example, the users created in CMiC could have some with firstname.lastname and another set as lastname.firstname. If this is the case, a translation would be difficult to determine.​

Setup Authentication

  1. The Redirect URL will need to be setup, which is parameters for the OAuth User Flows.​ Navigate to Authentication under the Manage section.​

  2. Click [+ Add a Platform].

    Screenshot of adding a platform in the Authentication screen​

  3. Select the option that applies.​

    • For CMiC mobile apps in iOS and Android:

      • iOS Mobile Application

        1. Enter the Bundle ID.

          Screenshot of the Bundle ID field​

        2. Click Configure.

          Screenshot of the iOS Configuration screen​

        3. Click Done.​

        4. Copy the Redirect URI

          Screenshot of the iOS Redirect URIs

      • Android Mobile Application

        1. Enter Package Name.

        2. Enter Signature Hash.​ For CMiC Mobile, enter "2agQWjWsihazT0JvBe/RsDDMU64=​".

          Screenshot of the Package Name and Signature Hash fields​

        3. Click Configure.

          Screenshot of the Android Configuration screen​

        4. Click Done.​

        5. Copy the Redirect URI.

          Screenshot of the Redirect URIs for Android

Userless Flows

To support userless tokens, additional configuration is required with custom claim, where the default custom claim supported is “cmicuser”.​

The value set is for all tokens generated. It cannot be a lookup by attribute or transformation since there is no authenticated user.​​

NOTE: ​​A CMiC Service Account must be created first before attempting this setup. You may not have the permissions to complete all the steps and should reach out to your IT Team if there is a step you are not able to complete.

Create Client Secret

Screenshot of adding a client secret

  1. You will need to create a secret that is required to use the Client Credentials Flow.​ Under the Manage menu section, navigate to "Certificates & Secrets".​

  2. Click [+ New Client Secret].​

  3. Enter a description in the Description field (e.g. userless) and ​set the Expires field to how long the secret is active.​

  4. Click [Add] and ensure you save the value. You only see it once.

Setup Custom Claim

  1. Under the Manage menu section, navigate to Enterprise Applications.

  2. Find the application to update and click Single Sign-on.

  3. Click [Edit] on the Attributes & Claims section.

    Screenshot of the Single Sign On screen​​

  4. Click [Add new claim].

    Screenshot of the Add New Claim button​

  5. Set the Claim Name field to "cmicuser".

    Screenshot of the Manage Claim screen​

  6. For Enterprise, set the Source Attribute field to your CMiC Service Account username.

  7. For Cloud, set the Source Attribute field to your CMiC tenant and Service Account username (e.g. tenant||serviceaccount).

    NOTE: Do not add quotes. Just enter the value and select from the drop-down menu.

  8. Navigate back to the App Registration and select the application.​

  9. Navigate to the Manage menu section and select Manifest.​

  10. Update acceptMappedClaims to "true".​

  11. Click [Save].

    Screenshot of the Manifest screen

After the above setup is completed, getting a token with the Client Credentials Flow should have an additional “cmicuser” claim with your setup.

Screenshot of the token

Analyzing Token

There are different sites available to view the claims in a token:

Troubleshooting

AADSTS50146: This application is required to be configured with an application-specific signing key. It is either not configured with one, or the key has expired or is not yet valid.

Check the Manifest to ensure that you have set acceptMappedClaims to "true". See Setup Custom Claim.

AADSTS501461: AcceptMappedClaims is only supported for a token audience matching the application GUID or an audience within the tenant's verified domains. Either change the resource identifier, or use an application-specific signing key.

Check the Manifest to ensure that you have set requestedAccessTokenVersion to "2". See Step 4 - Manifest.

AADSTS1002012: The provided value for scope api://e9c3994b-04ac-4b42-ad00-77429ba4c425/.defaul is not valid. Client credential flows must have a scope value with /.default suffixed to the resource identifier (application ID URI).

Check that the application using the OAuth Client Credentials Flow is set to the right scope. It must end with "/.default".

AADSTS50196: The server terminated an operation because it encountered a client request loop. Please contact your app vendor.

This is an unknown error that could be due to the change not being live yet, or it's possibly due to how requests are being made.