This guide walks through the end-to-end setup of the OAuth 2.0 Client Credentials Flow between Arcoro's Integration module and CMiC, using Microsoft Entra ID as the Identity Provider (IdP). 

The flow is server-to-server (userless), meaning no human login is involved. Arcoro's Integration module authenticates as a service account inside CMiC.

CMiC Reference Documentation

This is a simplified, ordered guide to get the integration up and running. For full details, edge cases, and advanced configuration options, always refer to the CMiC documentation links above.

• OAuth Overview with CMiC
• Microsoft Entra ID Application Setup
• Client Credentials Flow with CMiC
• Troubleshooting

How It Works

1. Arcoro's Integration module requests a token from Microsoft Entra ID using its client credentials (App ID + Secret).
2. Entra ID returns a JWT access token that includes a [cmicuser] claim identifying the CMiC service account.
3. Arcoro's Integration module calls the CMiC API, attaching the token in the [Authorization: Bearer <token>] header.
4. CMiC validates the token signature, checks the claims, resolves the cmicuser, and authorizes the call.

Prerequisites

• Admin access to the customer's Microsoft Entra ID tenant (Azure Portal).
• Admin access to CMiC (API Security module).
• The Arcoro's Integration module connector for CMiC has already been created in the Arcoro's Integration module platform.

Phase 1 — Create a Service User in CMiC

A dedicated service account must exist in CMiC before any OAuth configuration is done. This account represents Arcoro's Integration module inside CMiC and is what the [cmicuser] claim maps to. 

1. Log in to CMiC as an administrator. 
2. Create a new user account intended exclusively for this integration (e.g., [Arcoro's Integration module service] ). 
   • Do not reuse an account that a real person uses to log in.
3. Assign the user the permissions required by the integration (e.g., read/write access to the relevant modules).
4. Note the exact username — you will need it in Phase 2 and Phase 3.

Phase 2 — Configure the Microsoft Entra ID Application

This phase is performed by the customer's IT / Azure administrator in their own Entra ID tenant.

Learn more from CMiC – Microsoft Entra ID Application

Step 2.1 — Register a New Application 

1. Go to the Azure Portal and open Microsoft Entra ID. 
2. Navigate to App registrations → + New registration. 
3. Enter a meaningful name (e.g., Arcoro's Integration module – CMiC Integration). 
4. Leave Supported account types at the default (single tenant) unless otherwise required. 
5. No Redirect URI is needed for Client Credentials Flow. 
6. Click Register. 
7. On the app overview page, copy and save: 
   • Application (Client) 
   • ID Directory (Tenant) ID

Step 2.2 — Set the Access Token Version to v2

1. Under Manage, go to Manifest.
2. Find the [requestedAccessTokenVersion] field and change its value from [null] to [2] .
3. Click Save.

This ensures the token is a v2 JWT, which CMiC requires for correct claim validation.

Step 2.3 — Create a Client Secret

1. Under Manage, go to Certificates & Secrets.
2. Click + New client secret.
3. Enter a description (e.g., Arcoro's Integration module CMiC ) and set an expiry.
4. Click Add.
5. Copy the secret value immediately — it is only shown once.

Step 2.4 — Expose an API (Application ID URI)

1. Under Manage, go to Expose an API. 
2. Click Add next to Application ID URI. 
3. Accept the default value (e.g., api://<client-Iid>). 
4. Click Save.

Step 2.5 — Add the [cmicuser] Custom Claim

This is the most critical step. The [cmicuser] claim in the token tells CMiC which service account to use.

1. Under Manage, go to Enterprise applications.
2. Find and open the application registered in Step 2.1.
3. Navigate to Single sign-on → Edit the Attributes & Claims section.
4. Click + Add new claim.
5. Set Claim name to: [cmicuser] 
6. Set the Source attribute to the CMiC service username created in Phase 1.
   • Do not add quotes — just type the value and select it from the dropdown.
   • Enterprise vs. Cloud
     • Enterprise - Use the plain CMiC username (e.g., Arcoro's Integration module service).
     • Cloud - CMiC Cloud requires the value to be prefixed with the tenant identifier: [tenant| username] (e.g., acme corp|Arcoro's Integration module service ). Use this exact concatenated format — CMiC will not do it automatically from the token side.
7. Save the claim.

Step 2.6 — Enable Mapped Claims in the Manifest

1. Go back to App registrations → open the application.
2. Under Manage, go to Manifest. 
3. Set [acceptMappedClaims] to [true]. 
4. Click Save.

What to Share With the Arcoro’s Integration Module/CMiC Admin

At the end of this phase, you must provide:

Phase 3 — Register the Application in CMiC API Security

This phase is performed by a CMiC administrator.

Learn more from Client Credentials Flow with CMiC

1. Log in to CMiC as an administrator. 
2. Navigate to CMiC API Security → Application Registration. 

3. Click to create a new registration and fill in the following minimum required fields:

   Field	Value
   Description	A friendly name for this registration (e.g., Arcoro's Integration module Integration)
   Issuer URL	https://login.microsoftonline.com/<tenant-id>/v2.0
   Application ID	The Application (Client) ID from Phase 2
   Keyset ID (JWKS URI)	https://login.microsoftonline.com/<tenantid>/discovery/v2.0/keys

4. Save the registration.

CMiC will use the Keyset ID to fetch the IdP's public keys and validate the JWT signature on every API call.

Phase 4 — Configure the Connector in Arcoro's Integration Module

This phase is performed by an Arcoro's Integration module administrator.

1. Open the Arcoro's Integration module platform and locate the CMiC connector for
   this customer.
2. In the connector's authentication settings, switch the auth type to OAuth 2.0 – Client
   Credentials.

3. Enter the following values (provided by the customer from Phase 2):

   Field	Value
   Token URL	https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
   Client ID	Application (Client) ID
   Client Secret	Secret value from Step 2.3
   Scope	api://<client-id>/.default

4. Save the connector. Saving will automatically attempt to validate the connection. You can also use the Test Connector button at any time to trigger the same validation.

Phase 5 — Validate the Setup

• In Arcoro's Integration module, click the Test Connector button on the CMiC connector, or simply save it — both will call CMiC and validate the credentials.
• If the call succeeds, the setup is complete.
• If not, follow the troubleshooting steps below.

Troubleshooting

Quick Checklist

• The [Authorization: Bearer <token>] header is present on every request. 
• The application is registered in CMiC API Security with a matching Application ID and Issuer URL. 
• The token contains the [cmicuser] claim with the correct value. 
• The token is not expired ([exp] claim). 
• The [iss] claim in the token matches the Issuer URL in the CMiC registration. 
• The CMiC server can reach the Entra ID JWKS endpoint to fetch public keys. 

Decode the Token

Use either of these tools to inspect the JWT claims: 

• https://jwt.ms 
• https://jwt.io 

Paste the token (starts with [ey...] ) and verify: 

• [iss] matches the registered issuer. 
• [aud] matches the Application ID URI (api://<client-id>). 
• [cmicuser] is present and set to the correct CMiC service account username.

Common Errors

Enable CMiC OAuth Debug Logging

Ask your CMiC DBA to enable dynamic logging for deeper diagnostics:

<logger name='cmic.oauth2.filter' level='FINE'/

Server logs will contain the full bearer token and the specific validation error.