Skip to main content

OAuth2/OIDC Integration

cidaas supports OAuth2 and OpenID Connect (OIDC) for Single Sign-On (SSO) authentication. You can configure cidaas to act as an Identity Provider (IdP) or as a Service Provider (SP).

Understanding IDP vs SP​

  • Identity Provider (IdP): cidaas provides and provisions user identity to other systems (applications)

    • cidaas authenticates users and sends their identity information to applications
    • Applications trust cidaas to verify who the user is
    • Example: Users log in to cidaas, then access multiple OAuth2/OIDC applications without logging in again

  • Service Provider (SP): cidaas receives user identity from other systems (external identity providers)

    • External OAuth2/OIDC systems authenticate users and send identity information to cidaas
    • cidaas trusts the external system to verify who the user is
    • Example: Users log in to an external OAuth2/OIDC provider (like Google, Facebook, or a custom provider), then access cidaas without logging in again

Key Features:

When cidaas acts as Identity Provider (IdP):

  • Provides OAuth2/OIDC authentication endpoints for your applications
  • Issues access tokens and ID tokens (OIDC) to authorized applications
  • Supports Authorization Code Flow with PKCE for secure authentication
  • Centralizes user authentication and authorization for multiple applications
  • Manages user consent and scope permissions

When cidaas acts as Service Provider (SP):

  • Integrates with external OAuth2/OIDC identity providers
  • Supports social login providers (Google, Facebook, Amazon, Microsoft, etc.)
  • Supports custom OAuth2/OIDC provider integration
  • Maps external provider attributes to cidaas user profiles
  • Automatically creates or updates user accounts from provider identity information

OAuth2/OIDC as Service Provider (SP)​

When cidaas acts as a Service Provider (SP), it receives user identity from external OAuth2/OIDC providers. Users authenticate with an external system (like Google, Facebook, or a custom OAuth2/OIDC provider), and that system sends identity information to cidaas.

What this means: cidaas receives user identity from other systems (external OAuth2/OIDC identity providers). Examples include social login providers like Google, Facebook, Microsoft, or custom OAuth2/OIDC providers.

Benefits of cidaas as SP:

  • Integrate with existing OAuth2/OIDC identity systems
  • Support social login providers (Google, Facebook, etc.)
  • Leverage existing user directories
  • Support custom OAuth2/OIDC providers
  • Centralize user management in external systems
  • Support federated identity scenarios

cidaas as Service Provider Flow​

The following diagram illustrates the authentication flow when cidaas acts as a Service Provider:

Detailed Authentication Flow:

  1. User Access Request: The user attempts to access a protected resource in cidaas (acting as SP).

  2. Authorization Request to IdP: cidaas generates an OAuth2 authorization request and redirects the user to the external Identity Provider. The request includes:

    • client_id: cidaas application identifier registered with the IdP
    • redirect_uri: cidaas callback URL
    • response_type: code (Authorization Code Flow)
    • scope: Requested permissions (e.g., openid profile email)
    • state: CSRF protection token
    • code_challenge and code_challenge_method: PKCE parameters (if PKCE is enabled for the custom provider)

  3. External IdP Authentication:

    • If the user has an active SSO session with the IdP, authentication may be automatic
    • If not authenticated, the IdP presents the login page
    • User authenticates with credentials (username/password, MFA, etc.)

  4. User Consent: If the IdP requires consent, it presents a consent screen showing requested permissions.

  5. Authorization Code: After successful authentication and consent, the IdP:

    • Generates an authorization code
    • Redirects the user back to cidaas with the authorization code

  6. Token Exchange: cidaas exchanges the authorization code for tokens:

    • Sends authorization code to IdP token endpoint
    • Includes client_id, redirect_uri
    • Includes client_secret or code_verifier depending on provider configuration:
      • client_secret: For traditional OAuth2 providers
      • code_verifier: For providers with PKCE enabled
    • IdP validates and returns:
      • Access Token: Used to access user information
      • ID Token (OIDC): Contains user identity information (JWT)
      • Refresh Token: Used to obtain new access tokens

  7. User Information Extraction: cidaas extracts user information from one of the following sources, depending on provider configuration:

    • ID Token (JWT): If userinfoSource is set to IDTOKEN, user information is extracted from the ID token claims
    • Access Token (JWT): If userinfoSource is set to ACCESSTOKEN, user information is extracted from the access token claims
    • UserInfo Endpoint: If userinfoSource is not set (default), cidaas calls the IdP userinfo endpoint with the access token to receive user profile information (email, name, etc.)

  8. User Account Management: cidaas processes the received information:

    • Validates ID token (OIDC) signature and claims
    • Extracts user information from ID token or userinfo response
    • Maps OAuth2/OIDC attributes to cidaas user attributes using attribute mapping
    • Creates a new user account or updates an existing one
    • Creates a user session

  9. Access Granted: The user is redirected to the originally requested resource and can now access cidaas.

Provider Types​

cidaas supports custom OAuth2/OIDC providers when acting as SP:

Custom OAuth2/OIDC Providers​

Integrate any OAuth2 or OpenID Connect compliant provider. This is useful for:

  • Integrating with enterprise identity systems
  • Connecting to custom-built OAuth2/OIDC providers
  • Enabling SSO from external identity providers

Configuration Steps for Custom Providers:

  1. Gather Provider Information:

    • Authorization endpoint URL
    • Token endpoint URL
    • UserInfo endpoint URL (OIDC)
    • Well-known configuration endpoint (OIDC)
    • Client ID (required)
    • Client Secret (required if not using PKCE; optional if using PKCE)
    • Supported scopes
    • PKCE support: Check if the provider supports PKCE (Proof Key for Code Exchange) for enhanced security

  2. Configure in cidaas:

    Using Admin Dashboard:

    • Navigate to Settings > Login Providers > Custom OAuth2 & OpenID Connect
    • Click + Add New Provider
    • Select OPENID_CONNECT or OAUTH2 as the standard type
    • Enter provider details:
      • Provider name
      • Display name
      • Authorization endpoint
      • Token endpoint
      • UserInfo endpoint
      • Client ID (required)
      • Client Secret (required if not using PKCE; optional if using PKCE)
      • PKCE: Enable PKCE (Proof Key for Code Exchange) for enhanced security
        • When enabled, cidaas will add code_challenge and code_challenge_method to authorization requests
        • The code_verifier will be included in token exchange requests
        • Client Secret is optional when PKCE is enabled
      • UserInfo Source: Select the source for user information:
        • IDTOKEN: Extract user information from ID token (JWT) claims
        • ACCESSTOKEN: Extract user information from access token (JWT) claims
        • (Not set): Use UserInfo endpoint (default)
      • AMR Configuration (optional): Configure Authentication Method Reference (AMR) mapping to map external IdP AMR values to cidaas AMR values
        • AMR values indicate the authentication methods used (e.g., password, MFA, biometric)
        • Maps external IdP AMR values (as they appear in tokens) to cidaas AMR values (internal representation)
        • AMR values are extracted from ID Token or Access Token claims (depending on userinfoSource configuration)
        • Example: Map external AMR value "password" to cidaas AMR value "10"
    • Configure scopes
    • Configure user info field mapping (see Attribute Mapping)
    • Save configuration

  3. Enable for Applications:

    • Navigate to Apps > App Settings
    • Select your application
    • Under Login Providers, enable the custom provider

OIDC Provider Requirements:

An OIDC-compliant provider must implement three standard endpoints:

EndpointDescription
Authorization EndpointRedirects users to the provider's login page
Token EndpointExchanges authorization codes for access tokens
UserInfo EndpointReturns user profile information using the access token

Authorization Endpoint:

  • Method: GET
  • Query Parameters:
    • client_id: Application identifier
    • redirect_uri: Callback URL
    • response_type: code (for Authorization Code Flow)
    • scope: Requested scopes
    • state: CSRF protection token
    • login_hint: (Optional) Suggested user identifier
    • code_challenge: (If PKCE enabled) SHA256 hash of the code verifier
    • code_challenge_method: (If PKCE enabled) S256 (SHA256)

Token Endpoint:

  • Method: POST
  • Form Parameters:
    • code: Authorization code received from authorization endpoint
    • grant_type: authorization_code
    • client_id: Application identifier
    • redirect_uri: Must match the redirect_uri used in authorization request
    • client_secret: (If not using PKCE) Application secret for authentication
    • code_verifier: (If PKCE enabled) The original code verifier used to generate the code_challenge
  • Security: Client secret or code_verifier (PKCE), depending on provider configuration

UserInfo Endpoint:

  • Method: GET
  • Headers: Authorization: Bearer {access_token}
  • Response: JSON object containing user profile information
  • Security: OAuth2 Bearer token

API Security:

EndpointSecurity MethodNotes
Authorization EndpointPublicly AccessibleCannot be secured as it's accessed from user's browser
Token EndpointClient Secret or OAuth TokenCan be secured with client secret or Bearer token for offline introspection
UserInfo EndpointBearer TokenValidated using the access token received from token endpoint

Additional Security Configuration:

To add OAuth2-based security for Token and UserInfo endpoints:

  1. Get Client Credentials:

    • Client ID and Client Secret can be found under Apps > App Settings > Edit App

  2. Create Security Application:

    • Create a Non-Interactive App in cidaas
    • Assign appropriate scopes (e.g., custom_oauth2_integration)
    • Use this app's credentials to secure your Token and UserInfo endpoints

Attribute Mapping​

When cidaas acts as a Service Provider, attribute mapping defines how OAuth2/OIDC attributes received from the external IdP are mapped to cidaas user attributes:

  • External Key: The attribute name as it appears in the ID token or userinfo response from the IdP
  • Inner Key: The corresponding cidaas user attribute name
  • User ID Attribute: Specifies which OAuth2/OIDC attribute should be used as the unique identifier for user matching (typically sub for OIDC)

Example Attribute Mapping:

The userinfo_fields object maps external IdP attributes to cidaas user attributes. Each cidaas attribute (key) contains an object with:

  • ext: The external IdP attribute name
  • default: (Optional) Default value to use if the attribute is not present in the IdP response

To map custom fields (non-standard attributes), prefix the cidaas custom field name with customFields.:

{
  "userinfo_fields": {
    "email": {
      "extFieldKey": "emailAddress"
    },
    "given_name": {
      "extFieldKey": "firstName"
    },
    "family_name": {
      "extFieldKey": "lastName"
    },
    "sub": {
      "extFieldKey": "subject"
    },
    "customFields.department": {
      "extFieldKey": "departmentName"
    },
    "customFields.employee_id": {
      "extFieldKey": "employeeNumber",
      "default": "N/A"
    }
  }
}

In this example:

  • External IdP attribute emailAddress → maps to cidaas email
  • External IdP attribute firstName → maps to cidaas given_name
  • External IdP attribute lastName → maps to cidaas family_name
  • External IdP attribute subject → maps to cidaas sub (user identifier)
  • External IdP attribute departmentName → maps to cidaas custom field department
  • External IdP attribute employeeNumber → maps to cidaas custom field employee_id with default value "N/A" if not present

Note: Custom fields must be defined in your cidaas field settings before they can be used in attribute mapping.

Common OIDC Claims:

  • sub: Subject identifier (unique user ID)
  • email: User email address
  • name: Full name
  • given_name: First name
  • family_name: Last name
  • picture: Profile picture URL
  • locale: User locale

OAuth2/OIDC as Identity Provider (IdP)​

When cidaas acts as an Identity Provider (IdP), it provides SSO authentication for your OAuth2/OIDC applications. Users authenticate once with cidaas and can access multiple applications without re-entering credentials.

What this means: cidaas provides and provisions user identity to other systems (your OAuth2/OIDC applications).

cidaas as Identity Provider Flow​

The following diagram illustrates the authentication flow when cidaas acts as an Identity Provider:

Detailed Authentication Flow:

  1. User Access Request: The user attempts to access a protected resource in an OAuth2/OIDC application.

  2. Authorization Request: The application redirects the user to cidaas authorization endpoint with:

    • client_id: Application identifier
    • redirect_uri: Callback URL
    • response_type: code (Authorization Code Flow)
    • scope: Requested permissions (e.g., openid profile email)
    • state: CSRF protection token
    • code_challenge and code_challenge_method: PKCE parameters (if used)

  3. cidaas Authentication:

    • If the user has an active SSO session with cidaas, authentication may be automatic
    • If not authenticated, cidaas presents the login page
    • User authenticates with credentials (username/password, MFA, etc.)
    • cidaas may apply additional security checks (MFA, risk-based authentication)

  4. User Consent: If the application requests scopes that require consent, cidaas presents a consent screen showing:

    • Application name and logo
    • Requested permissions/scopes
    • User can grant or deny access

  5. Authorization Code Generation: After successful authentication and consent, cidaas:

    • Generates a short-lived authorization code
    • Associates the code with the user session and requested scopes
    • Redirects the user back to the application with the authorization code

  6. Token Exchange: The application exchanges the authorization code for tokens:

    • Sends authorization code to cidaas token endpoint
    • Includes client_id, redirect_uri
    • Includes client_secret or code_verifier depending on the flow:
      • client_secret: For traditional Authorization Code Flow
      • code_verifier: For Authorization Code Flow with PKCE
    • cidaas validates the code and returns:
      • Access Token: Used to access protected resources
      • ID Token (OIDC): Contains user identity information (JWT)
      • Refresh Token: Used to obtain new access tokens

  7. User Info Request (OIDC): The application can request additional user information:

    • Calls cidaas userinfo endpoint with access token
    • Receives user profile information (email, name, etc.)

  8. Access Granted: The application validates the ID token, extracts user information, and grants access to the resource.

Configuration Steps​

To configure cidaas as an OAuth2/OIDC Identity Provider:

  1. Create Application in cidaas:

    • Log in to cidaas Admin Dashboard
    • Navigate to Apps > App Settings
    • Create a new application or select an existing one
    • Configure OAuth2/OIDC settings:
      • Redirect URIs: Valid callback URLs for your application
      • Scopes: Define what permissions your application can request (e.g., openid, profile, email)
      • Response Type: code (for Authorization Code Flow)
      • Grant Type: authorization_code (Authorization Code Flow)
      • PKCE: Enable PKCE (Proof Key for Code Exchange) for enhanced security, especially for public clients

  2. Configure Your Application: After creating the application in cidaas, you'll receive:

    • Client ID: Public identifier for your application (required)
    • Client Secret: Confidential credential (optional - not required when using PKCE for public clients)
    • Authorization Endpoint: https://{your-domain}/authz-srv/authz
    • Token Endpoint: https://{your-domain}/token-srv/token
    • UserInfo Endpoint (OIDC): https://{your-domain}/users-srv/userinfo
    • JWKS URI (OIDC): https://{your-domain}/.well-known/jwks.json

    Use these credentials and endpoints to:

    • Implement OAuth2 Authorization Code Flow (with or without PKCE)
    • Handle token exchange and user info requests
    • Validate ID tokens (OIDC)

Supported OAuth2 Flows​

cidaas as IdP supports:

  • Authorization Code Flow: Recommended for web applications
  • Authorization Code Flow with PKCE: Enhanced security for public clients (mobile apps, SPAs)

OIDC Support​

When using OpenID Connect:

  • ID Token: JWT containing user identity information
  • Standard Claims: sub, email, name, given_name, family_name, etc.
  • Custom Claims: Additional user attributes
  • Token Validation: Applications should validate ID token signature and claims

OAuth2/OIDC Standards​

cidaas supports the following standards:

  • OAuth2 2.0: RFC 6749
  • OpenID Connect 1.0: OIDC Core specification
  • PKCE: RFC 7636 (Proof Key for Code Exchange)
  • JWT: RFC 7519 (JSON Web Tokens)
  • JWKS: RFC 7517 (JSON Web Key Set)

Security Best Practices​

  • Use PKCE: Always use PKCE for public clients
  • HTTPS Only: Always use HTTPS for all OAuth2/OIDC endpoints
  • Token Validation: Always validate ID tokens (OIDC) and access tokens
  • State Parameter: Always use state parameter for CSRF protection
  • Secure Storage: Store client secrets securely, never expose in client-side code
  • Token Expiration: Respect token expiration times
  • Scope Limitation: Request only necessary scopes

Need Support?​

Please contact us on our support page.

Technical Integration​

Custom OAuth2/OIDC Provider APIs​

Manage custom OAuth2/OIDC providers programmatically using the following APIs:

OperationMethodEndpointAPI Reference
Create ProviderPOST/providers-srv/customView API
Update ProviderPUT/providers-srv/custom/{provider_name}View API
Get ProviderGET/providers-srv/custom/{provider_name}View API
List ProvidersGET/providers-srv/customView API