CMiC API and OAuth 2.0 Integration - CMiC App Registration

To register an application in Azure for the OAuth 2.0 Client Credentials Grant Type, in Azure Active Directory (Azure AD),

Obtain the following details:

• Application (Client) ID: The unique identifier for the registered application in Azure. This is the application ID recorded in the step – CMiC API and OAuth 2.0 Integration - Register the Web API App in Azure.

  • Review: CMiC API and OAuth 2.0 Integration - How to Get Application ID

• Token Issuer: The issuer responsible for generating the JWT access token. Typically, this follows the pattern https://sts.windows.net/{azure_tenant_id}/, where {azure_tenant_id} is the tenant ID from the Azure AD portal.

  • Review: CMiC API and OAuth 2.0 Integration - How to Get Issuer and jwks_uri

• JWKS URI: The URI that contains the JSON Web Key Set used to sign the JWT access token. This can usually be found in the openid-configuration endpoint provided by your issuer.

  • Review: CMiC API and OAuth 2.0 Integration - How to Get Issuer and jwks_uri

Access Token Details and Validation

CMiC expects the JWT token to be signed using a secure key and validated against the provided appid, issuer_uri, and jwks_uri. It is important that the token's claims are properly configured for CMiC to recognize the authenticating service account user.

Key aspects of token validation:

• Token Format: Should follow the JWT format, which includes three parts:

  • Header,

  • Payload

  • Signature

• Required Claims: The token must contain the following claims:

  • sub: Subject, typically represents the user.

  • exp: Expiration time, token is still valid for the duration of time granted

  • aud: Audience, represents the target audience, API/Service the token is issued for.

  • iss: Issuer, represents the issuer of the token, which is the Azure Active Directory tenant has been issued for and should match issuer_uri.

• Token Expiration: Tokens have a set expiration (exp claim). Ensure tokens are refreshed before expiration.

Check Point: CMiC Security Expectations

CMiC expects the following security conditions to be met:

1. The token signature will be validated.

2. Token "iss" and "appid" are registered in CMiC.

3. The token is valid (check the Not Before Time and Expiration claims).

4. Token IP matches client IP. The default is enabled. To disable IP check, set the cmic.oauth2.ipcheck.enabled property to "false" in cmicapp.properties.

5. The user of the token is valid in CMiC.

Error Handling and 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.

Update the application manifest and set acceptMappedClaims to "true", as described in Step 4 of CMiC API and OAuth 2.0 Integration - Setting Up a Custom Claim via Azure.

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.

Set the Application ID URI field to have the verified domain not just GUID, as described in Step 7 of CMiC API and OAuth 2.0 Integration - Setting Up a Custom Claim via Azure.

For example, instead of "api://509c4a10-aefa-4faf-8d98-3cb6b0b8c03c", use "api://509c4a10-aefa-4faf-8d98-3cb6b0b8c03c.cmicglobaldev.com" or "api://oauth2-custom-claim.cmicglobaldev.com".