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 a 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
    • 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( Refer to page 193 for additional details)
    • 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

This section explains how to configure a Generic SAML Identity Provider using Microsoft Entra ID and integrate it with Instant ID as a service (IIDaaS).

Pre Configuration in the Identity Provider (IdP)

Before configuring Instant ID as a service, you must create a SAML application in your Identity Provider.

Supported Identity Providers

  • Microsoft Entra ID
  • Okta

This document describes configuration using Microsoft Entra ID.

Create a SAML Application in Microsoft Entra ID

Navigate to Enterprise Applications

  1. Sign in to the Microsoft Entra ID portal.
  2. In the left navigation pane, select Enterprise applications.
  3. Click All applications.
  4. Click + New application.

Create a Non Gallery Application

  1. Select Create your own application.
  2. Enter a generic application name (for example, Generic SAML App).
  3. Select: Integrate any other application you don’t find in the gallery (Non gallery).
  4. Click Create.

Configure SAML Single Sign On in Microsoft Entra ID

  1. Open the newly created application.
  2. From the left menu, select Single sign on.
  3. Choose SAML.

This opens the SAML Single Sign On configuration page.

Configure Basic SAML Settings in Microsoft Entra ID

  1. In Basic SAML Configuration, click Edit.

Identifier (Entity ID)

  • Click Add identifier
  • Enter the SP Entity ID

The SP Entity ID uniquely identifies IIDaaS as the Service Provider and must match the value configured in IIDaaS.

Reply URL (Assertion Consumer Service URL)

  • Click Add reply URL
  • Enter the Assertion Consumer Service (ACS) URL provided by IIDaaS

Click Save. If prompted, select No, I’ll test later.

Download Federation Metadata from Microsoft Entra ID

  1. On the Single sign on page, scroll to SAML Certificates.
  2. Copy the App Federation Metadata URL.
  3. Download the signing certificate (RAW or Base64).

These values will be used during IIDaaS configuration.

Configure the Identity Provider in Instant ID as a service (IIDaaS)

This section describes how to configure a Generic SAML Identity Provider in Instant ID as a serviceusing metadata obtained from Microsoft Entra ID.

At this stage, the Microsoft Entra ID SAML application has already been created, and the Federation Metadata URL and signing certificate are available.

Navigate to Identity Providers

  1. Sign in to Instant ID as a service (IIDaaS).
  2. Navigate to: Administration → Resources → Identity Providers

Add a Generic SAML Identity Provider

  1. Click the Add (+) icon.
  2. Select Generic (SAML).

The Add Identity Provider configuration screen opens.

Configure Basic Identity Provider Details

Complete the following fields:

Name

  • Enter a descriptive and generic name for the Identity Provider.

This name is used only for identification within IIDaaS.

Example: Microsoft Entra SAML

SP Entity ID

  • Enter the Service Provider (SP) Entity ID.

The SP Entity ID uniquely identifies IIDaaS as the Service Provider and must match the Identifier (Entity ID) configured in Microsoft Entra ID.

Define SAML Endpoints Using Metadata

To simplify configuration, IIDaaS supports importing SAML endpoints directly from the Identity Provider metadata.

Federation Metadata URL

  1. Paste the Federation Metadata URL from Microsoft Entra ID into the Federation Metadata URL field.
  2. Click Fetch Configuration.

IIDaaS automatically populates values such as:

  • Issuer
  • Single Sign On (SSO) Endpoint

A confirmation message indicates that the configuration was fetched successfully.

Configure Signature Verification

  1. Select when IIDaaS should perform signature verification:
    • SAML Assertion (recommended)
    • SAML Response (optional, depending on requirements)
  2. Upload the verification certificate downloaded from Microsoft Entra ID.

After upload, the certificate details are displayed.

Configure Attribute and Claim Mapping

Claim mappings define how user attributes provided by the Identity Provider map to user attributes in IIDaaS.

User System Attribute Claim Mapping

  • Left hand fields represent IIDaaS user attributes.
  • Right hand fields represent claims sent by Microsoft Entra ID.

Map Standard User Attributes

  • Email → Email
  • First Name → Given Name
  • Last Name → Surname

These are standard claims provided by Microsoft Entra ID.

Optional Group and Role Claims

  • Group → Groups
  • Role → Role claim

User Management Configuration

Under the User Management section, configure how IIDaaS handles users authenticated through this Identity Provider.

  • Create User — Creates a new user in IIDaaS after successful authentication if the user does not already exist.
  • Update User — Updates existing user attributes when values received from the Identity Provider differ from existing values.

User Creation and Update Behavior

  • User creation or updates occur only after successful authentication.
  • If Create User is enabled:
    • IIDaaS creates a new user when an authenticated user does not already exist.
  • If Update User is enabled:
    • IIDaaS updates existing user attributes when values from the Identity Provider differ.
  • If both options are disabled:
    • The user must already exist in IIDaaS.
    • All mapped attributes must match existing user data.

Enable User Authentication

To activate the identity provider for login

  1. Locate the User Authentication section.
  2. Enable Enable for User Authentication.

Once enabled

  1. The identity providers available for authentication
  2. Additional authentication-related options are displayed

Configure Domain Based Routing (Optional)

Domains

  • Enter one or more email domains.
  • Multiple domains can be specified, separated by commas.

Behavior:

  • During login, IIDaaS checks the user’s email domain.
  • If the domain matches, authentication is routed to this Identity Provider.

Default Identity Provider (Optional)

  • Enable Default Identity Provider to make this Identity Provider the default for authentication.
  • Only one Identity Provider can be set as the default.
  • Enabling this option disables domain based routing.

Authorization, Roles, and Post Configuration Behavior

This section describes how authorization, roles, and group mappings function after the Generic SAML Identity Provider has been configured in Microsoft Entra ID and enabled in Instant ID as a service

Application Roles, Authorization, and User Authentication

Application Roles and Authorization Overview

Application roles control what an authenticated user is allowed to access after login.

  • Authentication confirms the user’s identity.
  • Authorization determines the user’s permissions.

In a SAML integration:

  • Microsoft Entra ID sends role and group information as claims.
  • IIDaaS uses these claims to enforce access control.

Create Application Roles in Microsoft Entra ID

Application roles must be created in Microsoft Entra ID so that role information can be included in the SAML assertion.

Create an Application Role

  1. In Microsoft Entra ID, navigate to App registrations.
  2. Select the SAML application associated with IIDaaS.
  3. Navigate to Manage → App roles.
  4. Click Create app role.

Configure the role using the following fields:

  • Display name
    Enter a role name that represents the intended permission.
  • Allowed member types
    Select Users/Groups.
  • Value
    Enter the role value. Role names must not contain spaces; use underscores instead.
  • Description
    Enter a short description of the role.
  • Enabled app role
    Leave this option enabled.

Click Apply.

Assign Application Roles to Users or Groups

Once application roles are created, they must be assigned.

  1. In Microsoft Entra ID, navigate to Enterprise applications → Your SAML application.
  2. Select Users and groups.
  3. Click Add user/group.
  4. Select a user or group.
  5. Select the appropriate application role.
  6. Click Assign.

Authorization Behavior

  • Users can authenticate successfully even if no role is assigned.
  • Access to protected resources requires a role assignment.
  • The assigned role is sent to IIDaaS as part of the SAML assertion.

Role-Based Authorization in IIDaaS

Role claims received from Microsoft Entra ID are evaluated by IIDaaS to determine access.

For role-based authorization to function correctly:

  • Role claims must be mapped in the Identity Provider configuration.
  • The role value sent by the Identity Provider must match the role expected by IIDaaS.

If multiple roles are sent, only the first role is applied.

External Group Mapping

External Group Mapping allows groups received from the Identity Provider to be mapped to internal IIDaaS groups.

Important Clarification

  • External Group Mapping is configured from the Identity Providers page.
  • It is independent of resource rules.

Configure External Group Mapping

  1. In IIDaaS, navigate to Administration → Resources → Identity Providers.
  2. Open the configured Generic SAML Identity Provider.
  3. Locate the External Group Mapping section.
  4. Map Identity Provider group names or IDs to IIDaaS internal group names.
  5. Save the configuration.

Notes on Group Mapping

  • Group claims must be sent by the Identity Provider.
  • Microsoft Entra ID does not send group display names by default; group object IDs may be used.
  • Group mapping enables group-based access control in IIDaaS.

User Authentication Flow (SP-Initiated)

After configuration is complete, users can authenticate using SP-initiated SSO.

Login Flow

  1. The user initiates login through IIDaaS.
  2. IIDaaS redirects the user to the Identity Provider.
  3. The user authenticates with the Identity Provider.
  4. The Identity Provider returns a SAML response.
  5. IIDaaS validates the response and applies role and group claims.

If OTP login is available, users may alternatively authenticate using OTP.

Important Notes

  • The Identity Provider must be enabled for user authentication to allow login.
  • Only one Identity Provider can be configured as the default.
  • For Microsoft Entra ID:
    • Role names must not contain spaces.
    • Use underscores (_) instead.

Limitations

  • Single Logout (SLO) is not supported.
  • If multiple roles are sent, only the first role is assigned.
  • Microsoft Entra ID role names cannot contain spaces.
  • Group claims do not remove previously assigned groups in IIDaaS.