OAuth - Overview with CMiC

Introduction

CMiC supports OAuth2 integration by delegating authentication to an external Identity Provider (IdP). After successful authentication, the IdP issues tokens, primarily the access_token, which CMiC expects to receive in order to validate the user’s identity and authorize access.

Token Details

  • access_token: In most IdPs, this is a JSON Web Token (JWT) used to authorize API calls.

  • id_token: A JWT that asserts the authenticated user’s identity (OpenID Connect).

  • Google-specific note: Google’s access_token is proprietary and intended for Google APIs. Use id_token (JWT) with CMiC.

How CMiC Uses Tokens

Include the token in the HTTP Authorization header using the Bearer scheme:

Copy 
Authorization: Bearer <jwt token>

Supported Identity Providers

  1. Microsoft Entra ID (formerly Azure AD)

  2. Google (pass id_token, not access_token)

  3. Okta

OAuth2/OpenID Connect Flow Overview

  1. User initiates logging in from CMiC and is redirected to the IdP authorization endpoint.

  2. User authenticates at the IdP (MFA/SSO as configured).

  3. IdP redirects back to CMiC with an authorization code.

  4. CMiC exchanges the authorization code for tokens at the IdP token endpoint.

  5. CMiC validates the tokens (signature, issuer, audience, expiration) and establishes a session.

Sequence Diagram (simplified):

Screenshot of a simplified sequence diagram

Token Validation Requirements

  • Signature verification: Validate JWT signature against IdP public keys (JWKs).

  • Claims checks: iss (issuer), aud (audience/client_id), exp (expiration), nbf (not before), iat (issued at).

  • Token lifetime & refresh: Honour exp and use refresh_token if supported by configuration.

Configuration – Microsoft Entra ID

  1. Register a new application in Entra ID (App registrations).

  2. Record the Application (client) ID and Directory (tenant) ID.

  3. Set Redirect URIs for web flows (e.g. https://<cmic-host>/oauth/callback).

  4. Expose APIs/Scopes as needed and assign user consent or admin consent.

  5. Use endpoints:

    • Authorization: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize

    • Token: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

    • OpenID config (JWKS): https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration

Configuration – Google

  1. Create an OAuth 2.0 Client ID in Google Cloud Console.

  2. Record the Client ID and Client Secret.

  3. Configure Authorized redirect URIs (e.g. https://<cmic-host>/oauth/callback).

  4. Use OpenID Connect scopes (openid, email, profile).

  5. For CMiC, pass id_token (JWT) in the Authorization header. Do not use Google access_token.

Configuration – Okta

  1. Create an OIDC application (Web) in Okta Admin.

  2. Record Client ID and Client Secret. Keep note of your Okta domain (e.g. https://dev-xxxx.okta.com).

  3. Configure Login redirect URI (e.g. https://<cmic-host>/oauth/callback).

  4. Scopes: openid, profile, email. Add custom scopes if exposing APIs.

  5. Endpoints:

    • Authorization: https://<okta-domain>/oauth2/default/v1/authorize

    • Token: https://<okta-domain>/oauth2/default/v1/token

    • OpenID config (JWKS): https://<okta-domain>/oauth2/default/.well-known/openid-configuration

Request Examples

The following is an HTTP header example:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Error Handling & Troubleshooting

  • 401 Unauthorized: Token missing/invalid/expired

    • Verify header format and token validity.

  • 403 Forbidden: Authenticated but not authorized

    • Check API Security in CMiC.

  • jwks fetch/validation failures

    • Ensure that the value in the CMiC app registration is correct and it is possible it can reach IdP well-known.

  • Clock skew

    • Align CMiC server time (NTP) to avoid iat/nbf/exp issues.

Security Best Practices

  • Prefer Authorization Code Flow with PKCE for browser-based clients.

  • Rotate client secrets and use certificates where possible.

  • Limit token lifetimes. Use refresh tokens judiciously.

  • Validate audiences and issuers. Restrict accepted IdPs in CMiC configuration.

  • Use TLS across all endpoints. Never log sensitive token contents.

Glossary

  • OAuth2: Authorization framework for delegated access.

  • OpenID Connect (OIDC): Identity layer on top of OAuth2 providing id_token.

  • JWT: Compact, signed token format carrying claims.

  • JWK/JWKS: JSON Web Key (Set) published by IdP for signature validation.

Disclaimer

These integrations are based on CMiC testing; behavior may vary with specific IdP configurations.