Configuration Parameters to Add IdPs Using OIDC Protocol

This article provides you a brief understanding of the OIDC protocol and all the common configurations available to add an identity provider using the OIDC protocol.

Overview

OpenID Connect (OIDC), a widely adopted open industry standard, is an authentication protocol that allows for secure and standardized communication between identity providers (IdPs) and relying parties (RPs)/service providers(SPs) such as web applications or services. It builds upon OAuth 2.0, providing an additional layer of authentication on top of the authorization framework. It provides a standardized way for RPs to integrate with different IdPs, promoting interoperability and ease of implementation.

OIDC enables the issuance of identity tokens (JSON Web Tokens (JWTs)), which contain claims about the authenticated user. These tokens allow RPs to verify the user's identity and access relevant information, such as name, email address, and profile picture. Learn more about the common configurations that are available to integrate identity providers over OIDC protocol.

Refer to the below how-to guides to learn how to integrate the supported IdPs using the OIDC protocol.

Common Configurations - OIDC Protocol

The following are the common settings to integrate an IdP using the OIDC Protocol.

Settings Term Description
General Redirect URL The redirect URL to use when configuring the identity provider.
Alias The alias uniquely identifies an identity provider. Ensure to provide a distinct name for each provider as it will also be used to build the sign-in redirect URL.
Domain Name The domain name of the organization.
OpenID Connect Settings Use Discovery Endpoint Enabled: If this setting is enabled, the discovery endpoint will be used to fetch the provider configurations. Use this setting to load the configuration from the endpoint and automatically update the configuration if the source has any updates. This setting is visible only once while adding a new IdP in the Unifyia platform. Once the endpoints are discovered, this option is hidden on the platform UI.
Disabled: If disabled, you need to enter the Authorization URL, Token URL, Logout URL, User Infor URL, and JWKS URL.
Discovery Endpoint If you have enabled the Use Discovery Endpoint option, you need to provide the discovery endpoint URL. This endpoint is a remote IdP discovery descriptor, which contains all necessary configuration information (metadata) for the OpenID Connect protocol, such as endpoints and supported capabilities. This setting will fetch the Authorization URL, Token URL, Logout URL, User Infor URL, and JWKS URL.
Authorization URL This is the endpoint where the authentication request is sent to the IdP. Users are redirected to this URL to log in and grant permissions to the client application.
Token URL This is the endpoint where the application exchanges the authorization code for tokens. After the user has authenticated and granted permissions, the application sends a request to this URL to obtain an access token, ID token, and optionally a refresh token.
Logout URL An endpoint for terminating the user session and logging out users from the external IdP.
User Info URL This is the endpoint for retrieving user profile information. This is optional. Once the application has an access token, it can use this URL to get user details such as name, email, and other profile attributes from the IdP.
Issuer The issuer identifier for the entity that issues the response. The authentication server validates issuer claims in responses from the IdP against this value. If the issuer identifier is not provided, the authentication server will not perform issuer validation.
Use JWKS URL The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the Authorization Server and signed using the RS256 signing algorithm.
Enabled: Identity provider public keys will be downloaded from the given JWKS URL. This allows great flexibility because new keys will be always re-downloaded again when the identity provider generates a new key pair.
Disabled: A public key (or certificate) from the identity provider database is used, so when the identity provider keypair changes, you always need to import the new key to the identity provider database as well.
JWKS URL URL where identity provider keys in JWK format are stored.
Validate Signatures Initially, if the Use Discovery Endpoint option is enabled, you cannot enable this option as all the relevant values to validate signatures are added based on the Discovery endpoint (the IdP metadata URL). You can view the values in the edit mode. Always enable this option.
Enabled: Indicates whether the authentication server verifies the signatures on the external ID Token signed by a specific Identity Provider (IdP). Requires the public key of the external OpenID Connect (OIDC) IdP. For performance optimization, this public key is cached.
Disabled: Signature validation is not required. Not recommended as the login will fail.
Client Configuration Client Assertion Signature Algorithm Specifies the signature algorithm used to create a JWT assertion as client authentication. This is necessary when using a private key or a client secret as JWT. If no algorithm is specified, the following defaults are used:
RS256 - JWTs signed with a private key
HS256 - When client secret as JWT.
Client Authentication Defines the Client Authentication method the platform authentication server uses with the Authorization Code Flow. In the case of JWT signed with a private key, the platform authentication server uses the realm private key. In other cases, define a client secret.
Client ID The client identifier registered with the identity provider. The client must have an OIDC client ID if you use the Authorization Code Flow to interact with the external IdP.
Client Secret This is the client's secret registered with the identity provider. This secret is necessary if you are using the Authorization Code Flow.
Scopes A list of OIDC scopes is included in the authentication request when seeking authorization. The default value is "openid," and each scope is separated by a space.
Sync Mode This is the strategy to update user information from the identity provider through mappers.
Import: This option enables the import of the entire data since the user was first created and logged in to the platform with a particular identity.
Force: Select this option to update user data at each user login.
Inherit: Select this option to use the sync mode set in the identity provider. All other options will override this sync mode.
Pass Login Hint This is a way of identifying the end-user for whom authentication is being requested. Select this option to pass a hint to the identity provider (IdP) about the identity of the user (e.g., username) in the authorization request sent to the IdP.
Enabled: Pass login hint to IdP.
Disabled: Do not pass the login hint to the IdP.

Mappers

Mappers are commonly used to translate and configure user attributes, roles, and group memberships between the Unifyia platform and identity providers (IdPs) during integration. They offer flexibility in accommodating different user data structures and requirements when integrating multiple IdPs. The following are the supported mapper types for the IdPs being integrated using the OIDC protocol:

NOTE
  • You can add multiple hardcoded role mappers if you want the users to be given multiple roles. For each role mapper that you add, you need to select a different role.
  • For users from the integrated IdP, you can assign groups in two ways - by using the Hardcoded Group Mapper or the Advanced Claim to Group Mapper.
  • You can add as many Hardcoded Group or Advanced Claim to Group mappers as you need but each time ensure that you are mapping it to a different Unifyia group.
  • Once a Unifyia group is assigned to a group mapper, the same cannot be assigned to another group mapper.
  • There are 3 possible combinations of the group mapping using theAdvanced Claim to Group
    • Map specific group of IdP to a specific group on the Unifyia platform
    • Map multiple groups of IdP to a single group on the Unifyia Platform
    • Map multiple groups of IdP to multiple groups on the Unifyia Platform
  • If there is no group or role mapping, all the IdP users will be assigned to the default workflow present in the Unifyia platform and the policies defined in the workflow will apply to all the IdP users. The default workflow also needs to be defined by the organization before adding the IdP.
  • The mappings also rely on the mappers supported by the identity providers. For instance, Okta does not support the Advanced Claim to Group mapper, so you would need to use a hardcoded group for group mappings in this scenario.
Mapper Type AVailable Configurations Description
Hardcoded Role
  • Name: Display name for the mapper.
  • Role: Select the role that must be automatically assigned to the user imported fromthe IdP to the Unifyia platform.
 A hardcoded role mapper allows you to define which hardcoded role must be automatically assigned to the user imported to the Unifyia platform fromthe IdP rather than being dynamically mapped from user attributes or claims provided by the IdP. It means that any user will automatically receive this role regardless of their actual identity or attributes from the IdP. For example, all users may be given the User role by default, regardless of their role attribute in the IdP. This can be useful for creating a baseline level of access for all users.
Hardcoded Group
  • Name: Display name for the mapper.
  • Sync Mode Override: Overrides the default sync mode of the IdP for this mapper. Available values are:
    • Legacy: To keep the behaviour before this option was introduced.
    • Import: To only import the user once during first login of the user with this identity provide.
    • Force: To always update the user during every login with this identity provider.
    • Inherit: To use the sync mode defined in the identity provider for this mapper.
 A hardcoded group refers to a group that is statically assigned to users without any dynamic mapping or condition based on the IdP’s claims. The group is predetermined on the Unifyia platform and doesn't change based on the user’s actual attributes. For example, a group like Admins might be hardcoded for all users who are part of an administrative team, regardless of the user's attributes provided by the IdP.
Advanced Claim to Group
  • Name: Display name for the mapper.
  • Sync Mode Override: Overrides the default sync mode of the IdP for this mapper. Available values are:
    • Legacy: To keep the behaviour before this option was introduced.
    • Import: To only import the user once during first login of the user with this identity provide.
    • Force: To always update the user during every login with this identity provider.
    • Inherit: To use the sync mode defined in the identity provider for this mapper.
  • Claims: Key and value of the claim to search for in the token. You can reference nested claims using a '.', i.e. 'address.locality'. To use dot (.) literally, escape it with backslash (\.). You have the option to add multiple key and value of the claims to search for in the token.
    • Key: The key to search in the token.
    • Value: The assigned value (ID) for the Key in the IdP system.
  • Regex Claim Values: To apply regular expressions (regex) to validate and filter claim values received from an external identity provider (IdP).
  • Group: Group to assign the user to in the Unifyia platform if claim is present.
An advanced claim to group mapping involves mapping a claim (such as a user attribute or identity provider-specific information) to a specific group or groups in the Unifyia platform. This may include custom logic for transforming claims, combining multiple claims, or using conditions to assign a user to a particular group based on certain attributes.
Claims (Key and Value) Example: For example,
  • if you provide the key as group and provide the ID of the group for the value parameter, then it means that the group with the given ID (claim) must be searched for in the token sent from the IdP and must be assigned to the selected Group in the Unifyia platform.
  • if you provide the key as 'address.locality' and provide the value as Santa Cruz for the value parameter, then it means that the users with the locality in the address as Santa Cruz must be searched for in the token sent from the IdP and must be assigned to the selected Group (for example group_admins) in the Unifyia platform.
Hardcoded Attribute
  • Name: Display name for the mapper.
  • User Attribute: User attribute you want to hardcode
  • User Attribute Value: User attribute value you want to hardcode.
A hardcoded attribute mapper type allows you to map a single user attribute from the IdP to User Model attribute in the Unifyia platform’s database. This attribute is fixed and manually configured (default/static value), without being dynamically derived from the user's identity or claims from the IdP. It ensures that a specific attribute is always assigned the same value regardless of the data in the IdP. For example, every user might be assigned a specific department code (e.g., HR) even though the IdP doesn't provide this information in the user’s attributes.
Attribute Importer
  • Name: Display name for the mapper.
  • Sync Mode Override: Overrides the default sync mode of the IdP for this mapper. Available values are:
    • Legacy: To keep the behaviour before this option was introduced.
    • Import: To only import the user once during first login of the user with this identity provide.
    • Force: To always update the user during every login with this identity provider.
    • Inherit: To use the sync mode defined in the identity provider for this mapper.
  • Claim: Name of claim (attribute) to search for in the assertion (token). You can reference nested claims using a '.', i.e. 'address.locality'. To use dot (.) literally, escape it with backslash (\.)
  • User Attribute Name: User attribute name to store claim. Use username, email, lastName, and firstName to map to those predefined user properties.
 An attribute importer is a configuration that allows for the importing and mapping of attributes from the IdP into the Unifyia platform. This could involve mapping a claim (like email or lastName) from the IdP to a field in the Unifyia’s user profile. For example, if the IdP provides a claim like email=user@abc.com, an attribute importer might map this claim to a field like email in the platform. You can add a single attribute at a time. If you need to import more attributes, add a new attribute importer mapper for each attribute that you wish to import.
Username Template Importer
  • Name: Display name for the mapper.
  • Sync Mode Override: Overrides the default sync mode of the IdP for this mapper. Available values are:
    • Legacy: To keep the behaviour before this option was introduced.
    • Import: To only import the user once during first login of the user with this identity provide.
    • Force: To always update the user during every login with this identity provider.
    • Inherit: To use the sync mode defined in the identity provider for this mapper.
  • Template: Provide a template or pattern to use to format the username being imported from the IdP in the token and store it on the Unifyia platform. This particularly is useful when the users with the similar username are being imported. Substitutions are enclosed in ${}.
  • Target: Destination field for the mapper.
    • LOCAL: Means that the changes are applied to the username stored in local database upon user import.
    • BROKER_ID: This means the changes are stored into the ID used for federation user lookup.
    • BROKER_USERNAME: This means that the changes are stored into the username used for federation user lookup.
 A username template importer allows for the creation or transformation of a user’s username based on data sent in the token from the IdP. It often involves using predefined templates or patterns to generate the username in the Unifyia platform. The template can use information such as first name, last name, email, or other attributes from the IdP. For example, '${ALIAS}.${CLAIM.sub}'. ALIAS is the provider alias. CLAIM.sub references a subject ID or Access token claim. The substitution can be converted to upper or lower case by appending |uppercase or |lowercase to the substituted value, e.g. '${CLAIM.sub | lowercase}

Back Next
On this page
Related Links
How-To-Guides