Configure Identity Providers (SAML/OIDC)

Instant ID as a Servicesupports integration with external Identity Providers (IdPs) using SAML 2.0 and OpenID Connect (OIDC) protocols. This enables Single Sign-On (SSO) and claim-based authentication through enterprise IdPs such as Okta or Microsoft Entra.

Supported Protocols

  • SAML 2.0
  • OIDC (OpenID Connect)

Configuration Steps

To configure an Identity Provider in Instant ID as a Service:

  1. Navigate to Administration → Resources → Identity Providers .
  2. Click the "+" icon to add a new Identity Provider.
  3. Select the IdP type from the dropdown:
    • Microsoft (OIDC): Preconfigured for Microsoft Entra (Azure AD).
    • Generic (OIDC): For other OIDC-compliant IdPs such as Okta or Ping Identity.
    • Generic (SAML): For SAML-based IdPs.

Microsoft (OIDC) Configuration

To Pre-Configure Microsoft(OIDC) in Microsoft Entra

  1. Register a new application in Microsoft Entra.
  2. Copy the Redirect URI from Instant ID as a Service and enter it in Microsoft Entra.
  3. Configure token claims to include roles and groups. These can be found at Entra Enterprise Application → Manage → Token configuration. Here any optional claim or group claim can be configured.
  4. Assign user, application roles, and groups to the application.
  5. Copy:
    • Application (Client) ID
    • Tenant ID
    • Client Secret

Instant ID as a Service Configuration

To configure Instant ID as a Service :

  1. Complete the following fields by entering or copy-pasting the information.
    • Name: Enter a name for your identity provider; for example, Microsoft Entra ID.
    • Client ID: This is the Microsoft Entra ID created during the application registration process.
    • Client Secret: This can be retrieved by navigating to Manage → Certificates and Secrets.
    • Issuer URL: Replace the <tenant> with the Directory (tenant) ID from the Entra application.
    • Redirect URI: This is read-only and cannot be changed. The Redirect URI is the tenant endpoint that will accept and evaluate the claims coming from Entra.
    • ID Token Claims: This value is retrieved from the Microsoft Entra application. At Entra Enterprise Application → Manage → Token configuration, you can add ID claims values into Instant ID as a Service.
  2. Select Client Authentication Method:
    • Select either Client Secret Basic or Client Secret Post

      • Client Secret Basic: The client secret and client id are sent in the Authorization header of the HTTP request.

      • Client Secret Post: The client secret and client id are sent as parameters within the request body of the HTTP POST request.

    3. Note: After entering the Issuer URL, click Fetch Configuration to automatically retrieve and prefill most required endpoints. This is the recommended and most efficient approach.
  3. Configure the requested information:
    • Scopes (e.g., openid profile email offline_access). Scopes are requested during the authentication process and determine the information included in the ID token and/or access token.
    • ID Token Claims: Navigate to ID Token Claims → Manage → Token configuration; from this page, you can add ID claims values into Instant ID as a Service.
    • User Information Claims
  4. Complete additional settings:
    • Max Authentication Age (seconds)
    • Auth Context Request Values
  5. Under User Management, enable:
    • Create User (Authentication): Allows Instant ID as a Service to create a user after successful authentication if the user does not exist.
    • Update User (Authentication): Updates user attributes after successful authentication if they differ from existing Instant ID as a Service attributes.
      • Note: User creation or update occurs only after the user successfully authenticates to Instant ID as a Service.
  6. Configure IdP claim mappings for attributes such as:
    • email, userId, phone, first name, last name, groups, roles
  7. Under Branding, define:
    • Login Button Text
    • Login Button Image

    External Group Mapping

    External Group Mapping allows mapping IdP-provided groups to Instant ID as a Service internal groups for role-based access. This option is visible only when a group mapping value exists under User Management.

    Note: Microsoft Entra does not send group display names by default, so users must use the group object ID instead.
    To configure External Group Mapping:
    1. Navigate to the External Group Mapping section in Instant ID as a Service.
    2. Add mappings between IdP group names/IDs and Instant ID as a Service internal group names.
    3. Save the configuration.
  8. User Authentication Section
    • Check Enable for User Authentication before entering attributes.
    • Optionally, select Default Identity Provider.
    • Enter attributes in the provided fields.
    • Click Save.

Generic (OIDC) Configuration

To Pre-Configuration (OIDC) in IdP

  1. Create a new application in your IdP (e.g., Okta, Ping Identity).
  2. Copy the Redirect URI from Instant ID as a Service and enter it in the IdP.
  3. Configure scopes and claims as required. Scopes are requested during the authentication process and determine the information included in the ID token and/or access token.
  4. Copy:
    • Client ID
    • Client Secret
    • Issuer URL

Instant ID as a Service Configuration

To configure Instant ID as a Service:

  1. Complete the following fields by entering or copy-pasting the information.
    • Name: Enter a name.
    • Client ID: This can be retrieved from General → Client Credentials → Client ID (Okta).
    • Client Secret: This can be retrieved from General → Client Secrets (Okta).
    • Issuer URL: This can be retrieved by navigating to Sign On → OpenID Connect ID Token → Issuer (Okta).
    • Redirect URI: This is read-only and cannot be changed. The Redirect URI is the tenant endpoint that will accept and evaluate the claims coming from the identity provider.
    • ID Token Claims: Included in all user attributes; doesn't need to be specified for Okta accounts. This value is retrieved from the Microsoft Entra application. At Entra Enterprise Application -> Manage -> Token configuration, you can add ID claims values into Instant ID as a Service.
  2. Select Client Authentication Method:
    • Select either Client Secret Basic or Client Secret Post.

      • Client Secret Basic: The client secret and client id are sent in the Authorization header of the HTTP request.

      • Client Secret Post: The client secret and client id are sent as parameters within the request body of the HTTP POST request.

    3. Note: After entering the Issuer URL, click Fetch Configuration to prefill endpoints automatically. This is the recommended approach.
  3. Define OIDC endpoints: OIDC endpoints can be fetched and prefilled using the Fetch Configuration button.
    • Authorization Endpoint
    • Token Endpoint
    • User Info Endpoint
    • Revocation Endpoint
    • JWKS URI
  4. Configure the requested information:
    • Scopes: (e.g., openid profile email offline_access). Scopes are requested during the authentication process and determine the information included in the ID token and/or access token.
    • ID Token Claims: Navigate to ID Token Claims → Manage → Token configuration; from this page, you can add ID claims values into Instant ID as a Service
    • User Information Claims.
  5. Complete additional settings:
    • Max Authentication Age (seconds)
    • Auth Context Request Values
    • Auth Method Request Values
  6. Under User Management, enable:
    • Create User (Authentication): Allows Instant ID as a Service to create a user after successful authentication if the user does not exist.
    • Update User (Authentication): Updates user attributes after successful authentication if they differ from existing Instant ID as a Service attributes.
    7. Note: User creation or update occurs only after the user successfully authenticates to Instant ID as a Service.
  7. Configure IdP claim mappings for attributes such as:
    • email, userId, phone, first name, last name, groups, roles
  8. Under Branding, define:
    • Login Button Text
    • Login Button Image

    9. External Group Mapping

    External Group Mapping allows mapping IdP-provided groups to Instant ID as a Service internal groups for role-based access. This option is visible only when a group mapping value exists under User Management.

    Note: Microsoft Entra does not send group display names by default, so users must use the group object ID instead.
    To configure External Group Mapping:
    1. Navigate to the External Group Mapping section in Instant ID as a Service.
    2. Add mappings between IdP group names/IDs and Instant ID as a Service internal group names.
    3. Save the configuration.
  9. User Authentication Section
    • Check Enabled for User Authentication before entering attributes.
    • Optionally, select Default Identity Provider.
    • Enter attributes in the provided fields (similar to User Management fields).
    • Click Save.

Generic (SAML) Configuration

Pre-Configuration in IdP

  1. Create a new SAML application in your IdP (e.g., Okta, Ping Identity).
  2. Copy the Assertion Consumer Service URL and SP Entity ID from Instant ID as a Service and enter them in the IdP.
  3. Configure NameID format and claims as required.
  4. Download IdP metadata or copy the Federation Metadata URL.

Instant ID as a Service Configuration

To configure Instant ID as a Service, complete the steps below.

Note that the information in step 1 varies depending on whether MS Entra accounts or Okta accounts are being used. Refer to the appropriate section below for details
  1. Complete the following fields by entering or copy-pasting the information:
    • For MS Entra:
      • Name: Enter a name.
      • SP Entity ID: Enter the ID.
      • Issuer: This can be retrieved by navigating to Manage → Single Sign-On → Set Up → Application → Microsoft Entra Identifier .
      • SSO Endpoint: This can be retrieved by navigating to Manage → Single Sign-On → Set Up (Application) → Login URL.
      • Federation Metadata URL: This can be retrieved by navigating to Manage → Single Sign-On → SAML Certificates → App Federation Metadata Url.
      • Verification Certs: This can be retrieved by navigating to Manage → Single Sign-On → SAML Certificates .
      • IdP Claim Mappings: This can be retrieved by navigating to Manage → Single Sign-On → Attributes and Claims
      • Assertion Consumer Service URL: Enter the URL.
      • Name ID Policy Format: Enter the format.
      For Okta :
      • SP Entity ID: Enter the ID.
      • Issuer: This can be retrieved by navigating to General → SAML Settings → SAML Issuer ID
      • SSO Endpoint: This can be retrieved by navigating to General → App Embed Link
      • Federation Metadata Url: This can be retrieved by navigating to Sign On → Settings → Metadata URL.
      • Verification Certs: This can be retrieved by navigating to Sign On → SAML Signing Certificates.
      • IdP Claim Mappings: This can be retrieved by navigating to General → SAML Settings → Attribute Statements and Group Attribute Statements.
      • Assertion Consumer Service (ACS) URL: Enter the ACS URL for your Instant ID as a Service provider. Recommended to leave this value unchanged as it could lead to unwanted behavior.
      • Name ID Policy Format: Enter the policy format.
  2. Define SAML endpoints:
    • SSO Endpoint (can be retrieved from your IdP)

    • Federation Metadata URL: Optional; used when fetching configuration information.

      • Note: After entering the Federation Metadata URL, click Fetch Configuration to automatically import and prefill SAML endpoint details. This simplifies setup and reduces manual errors.
  3. Configure signature verification: Configure when Instant ID as a Service performs signature verification.
    • SAML Response
    • SAML Assertion
    • Upload Verification Certificates
  4. Complete the requested information:
    • User Name (Login Hint) Parameter
    • Force Authentication
    • Auth Context Request (ACR) Values : Additional values presented in the request to the IdP. Your IdP should return these values to pass authentication.
    5. After saving the Identity Provider configuration in Instant ID as a Service, you can download the SP metadata from the IdP list page. This option is available only for SAML IdPs.
  5. Under User Management, enable:
    • Create User (Authentication): Creates a new user in Instant ID as a Service after successful authentication if the user does not already exist.
    • Update User (Authentication): Updates existing user attributes after successful authentication if they differ from the IdP-provided values.
      • Note: User creation or update occurs only after the user successfully authenticates to Instant ID as a Service.
  6. Configure IdP claim mappings for attributes such as:
    • email, userId, phone, first name, last name, groups, roles
  7. Under Branding, define:
    • Login Button Text
    • Login Button Image

    8. External Group Mapping

    External Group Mapping allows mapping IdP-provided groups to Instant ID as a Service internal groups for role-based access. This option is visible only when a group mapping value exists under User Management.

    Note: Microsoft Entra does not send group display names by default, so users must use the group object ID instead.
    To configure External Group Mapping:
    1. Navigate to the External Group Mapping section in Instant ID as a Service.
    2. Add mappings between IdP group names/IDs and Instant ID as a Service internal group names.
    3. Save the configuration.
  8. User Authentication Section
    • Check Enable for User Authentication before entering attributes.
    • Optionally, select Default Identity Provider .
    • Enter attributes in the provided fields (similar to User Management fields).
    • Click Save.

Onboarding External IdPs

  • For SAML configurations, users can:
    • Download SP metadata from Instant ID as a Service and upload it to the IdP.
    • Copy the Federation Metadata URL from the IdP and paste it into Instant ID as a Service to upload IdP metadata.

Additional Features

  • Export Configuration: Use the Export Configuration option to download the current IdP settings for backup or reuse.
  • External Group Mapping: Allows mapping IdP-provided groups to Instant ID as a Service internal groups for role-based access. This option is visible when group mapping is enabled under User Management.
  • SP-Initiated SSO Verification: After clicking Next, users can log in via IdP or OTP. If IdP login is selected, users are redirected to IdP for authentication. After successful authentication, users are redirected back to Instant ID as a Service and logged in automatically.
  • Role-Based Authorization: Ensure that role and group claims from IdP are correctly mapped to Instant ID as a Service roles and groups for proper access control.

User Authentication Section

When Enable for User Authentication is checked:

  • The IdP becomes active for login.
  • Additional fields appear:
    • Default Identity Provider: Sets this IdP as the tenant’s default (only one allowed; disables domain-based login).
    • Domains: Optional domain-based routing for user IDs.
    • User Attribute used to identify user: Select the Instant ID as a Service attribute for primary identification.
    • Claim used to identify user: Enter the IdP claim that maps to the selected Instant ID as a Service attribute.
    • System User Match Attributes: Map additional IdP claims (Email, First Name, Last Name, Locale, Mobile, Phone, Security ID, User Principal Name).
  • All mappings must match an existing Instant ID as a Service user unless Create User or Update User is enabled under User Management.

Important Notes

  • Use Enable for User Authentication to allow the IdP for login.
  • Default Identity Provider checkbox sets the IdP as the default.
  • Claim Mapping should include attributes like email, userId, phone, first name, last name, groups, roles.
  • For Microsoft Entra, role names cannot contain spaces; use underscores instead.

Limitations

  • Single Logout (SLO) is not functional in this release.
  • Only the first role claim is assigned if multiple roles are sent.
  • Role names in Microsoft Entra cannot contain spaces.
  • Group claims do not remove old groups in Instant ID as a Service.