Identity provider integration

To enable Imply Hybrid (formerly Imply Cloud) Auth for your organization, contact your Imply account representative.

Single sign-on (SSO) is an identity verification method that enables you to authenticate to multiple applications using the same set of credentials. Imply Hybrid Auth supports SSO through external identity providers (IdPs) that adhere to the Security Assertion Markup Language (SAML) 2.0 and OpenID Connect (OIDC) 1.0 identity protocols. With IdP-initiated SSO, you don't need to create users or assign them to roles in Imply. User creation and role assignment happens automatically based on the data provided by the IdP upon user login.

After you configure the IdP, a button corresponding to the IdP appears on the Login page. Users can authenticate using either their Imply Hybrid username and password or their IdP credentials.

Prerequisites

To set up an IdP, you need the User Manager role.

Set up an identity provider

The easiest way to get started is by setting up the Imply app in your IdP, exporting the IdP metadata document, and importing the configuration into the Imply Hybrid Auth User management console. The document includes the issuer's name, expiration, and keys to validate responses from the IdP.

For specific setup instructions on using Okta with SAML or OIDC, see Okta SAML integration and Okta OIDC integration. The following steps are the general setup instructions for integrating any type of IdP with Imply Hybrid Auth.

The general flow is as follows:

Authentication

The following steps ensure that users can log in to Imply with an IdP:

1. Set up the Imply app in your IdP for Imply.
2. Export the IdP metadata document. The document includes the issuer's name, expiration, and keys to validate responses from the IdP.
3. Import the configuration into Imply Hybrid Auth.

Authorization

The following steps ensure that users are authorized to access certain assets in Imply:

1. Create groups (if not already present) in your IdP to reflect usage in Imply.
2. Create groups in Imply that map to the groups in your IdP.
3. Configure Imply mappers to accept attributes or claims from the IdP. Mappers associate values of attributes or claims from the IdP with roles or groups in Imply.

Step 1. Generate the identity provider metadata document

Configure the Imply app in the IdP software you use. Most types allow you to export the IdP metadata file, which you can then import into Imply.

For an Okta example, see this knowledge base article.

Step 2. Configure the identity provider in Imply Hybrid Auth

1. In the User management console, click Identity Providers from the left navigation menu.
2. Click Add provider and select the IdP you want to add. Imply Hybrid Auth displays the configuration page for the IdP you selected. The providers are categorized into these groups:
   • Social: Social providers enable social authentication in your realm. With Imply Hybrid Auth, users can log in to your app using a social network account.
   • User-defined: User-defined providers rely on specific protocols to authenticate and authorize users. Using these providers, you can connect to any IdP compliant with a specific protocol. Imply Hybrid Auth provides support for SAML and OIDC protocols. You can configure and broker any IdP based on these open standards.
3. Enter a unique identifier for the IdP into the mandatory Alias field. Imply Hybrid Auth uses the alias to build redirect URIs for protocols that require a redirect URI or a callback URL to communicate with the IdP. Every IdP must have an alias. Alias examples include facebook, google, and idp.acme.com.
4. Click the Use discovery endpoint toggle to the off position.
5. In the Import config from file field, click Browse... and select the metadata file you downloaded.
6. Configure the remaining mandatory settings.

The following fields are required for the OIDC protocol:

• Authorization URL: Authorization endpoint that accepts authentication requests. Through this endpoint, you can interact with the resource owner and obtain an authorization grant.
• Token URL: Token endpoint required to obtain an access token.
• Client ID: Client identifier registered with the IdP.
• Client Secret: Client secret registered with the IdP.

The following fields are required for the SAML protocol:

• Service provider entity ID: Unique identifier used to identify requests from a service provider. By default, this setting is set to the realm's base URL <root>/auth/realms/<realm_name>.
• Single Sign-On service URL: Endpoint that starts the authentication process. The value of this field is specified by your SAML IdP if they publish an entity descriptor.

1. Click Add.

Step 3. Configure source mapping values in the identity provider

After saving the IdP profile, you can create mappers for the profile. Before starting, verify that you have the user claims or attributes in the IdP to map to roles or groups in Imply. You may need to create those properties for the purpose if they don't already exist. For example, to create claims in Okta, see Create Claims. For OIDC, see Create an Authorization Server.

Step 4. Configure mappers

To configure mappers, follow these steps:

1. In the User management console, click Identity Providers from the left navigation menu.
2. Click the name of the IdP for which you want to configure mappers.
3. Click the Mappers tab and then click Add mapper.
4. Enter information for the mapper:
   • Name: Name of the mapper. This name is used to identify the mapper in the Imply Hybrid Auth console.
   • Sync Mode Override: Specifies how to update user information at login. Choose from the following values:
     • Inherit: Use the sync mode defined in the IdP. All other options override this sync mode.
     • Import: Import user data from when the user was created during the first login.
     • Force: Update user data at each user login.
     • Legacy: Keep the behavior before this option was introduced.
   • Mapper type: Specifies how user data is mapped between the IdP and Imply Hybrid. For more information, see Mapper types.
5. Click Save.

The following screenshot shows a sample configuration that maps the groups claim to the Cloud Admin role in Imply Hybrid:

Advanced topics

The following sections list all the fields on the IdP configuration page. Many of the fields are optional and some are set to mandatory details. They are listed here for completeness.

Common settings

Although each type of provider has its own specific configuration options, all share several common configurations. The following sections list and describe the protocol-specific settings:

• SAML v2.0
• OpenID Connect

The following are the common configuration options:

Configuration	Description
Redirect URI	Endpoint hosted by Imply Hybrid Auth where the IdP sends information upon user sign in. This field is populated by default.
Alias	Unique identifier for the IdP. Imply Hybrid Auth uses the alias to build redirect URIs for protocols that require a redirect URI or a callback URL to communicate with the IdP. Every IdP must have an alias. Alias examples include facebook, google, and idp.acme.com.
Display name	Friendly name for the IdP that will appear in the Imply Hybrid Auth interface.
Display order	Number defining the order of the providers in the Imply Hybrid Auth interface (for example, on the Login page). The lowest number is applied first.

SAML v2.0

Imply Hybrid Auth can broker IdPs based on the SAML v2.0 protocol.

To add a SAML 2.0 IdP, select SAML v2.0 from the Add provider list.

For common IdP settings, see Set up an identity provider. This section lists the SAML-specific settings.

Configuration	Description
Service Provider Entity ID	The SAML Entity ID that the IdP uses to identify requests from this Service Provider. By default, this setting is set to the realms base URL <root>/auth/realms/{realm-name}.
Single Sign-On Service URL	The SAML endpoint that starts the authentication process. If your SAML IdP publishes an IdP entity descriptor, the value of this field is specified there.
Single Logout Service URL	The SAML logout endpoint. If your SAML IdP publishes an IdP entity descriptor, the value of this field is specified there.
Backchannel Logout	Toggle this switch to ON if your SAML IdP supports back channel logout.
NameID Policy Format	The URI reference corresponding to a name identifier format. By default, Imply Hybrid Auth sets it to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.
Principal Type	Specifies which part of the SAML assertion will be used to identify and track external user identities. Can be either Subject NameID or SAML attribute (either by name or by friendly name). Subject NameID value can not be set together with urn:oasis:names:tc:SAML:2.0:nameid-format:transient NameID Policy Format value.
Principal Attribute	If Principal type is not empty, this field specifies the name ("Attribute [Name]") or the friendly name ("Attribute [Friendly Name]") of the identifying attribute.
Allow create	Allow the external IdP to create a new identifier to represent the principal.
HTTP-POST Binding Response	Controls the SAML binding in response to any SAML requests sent by an external IdP. When OFF, Imply Hybrid Auth uses Redirect Binding.
HTTP-POST Binding for AuthnRequest	Controls the SAML binding when requesting authentication from an external IdP. When OFF, Imply Hybrid Auth uses Redirect Binding.
HTTP-POST Binding Logout	When ON, Imply Hybrid Auth responds to requests using HTTP-POST. Otherwise, HTTP-REDIRECT binding is used.
Want AuthnRequests Signed	When ON, Imply Hybrid Auth uses the realm's key pair to sign requests sent to the external SAML IdP.
Signature Algorithm	If Want AuthnRequests Signed is ON, the signature algorithm to use.
SAML Signature Key Name	Signed SAML documents sent using POST binding contain the identification of signing key in KeyName element, which, by default, contains the Imply Hybrid Auth key ID. External SAML IdPs can expect a different key name. This switch controls whether KeyName contains: • KEY_ID: The key ID. • CERT_SUBJECT: The subject from the certificate corresponding to the realm key. Microsoft Active Directory Federation Services expect CERT_SUBJECT. • NONE: Imply Hybrid Auth omits the key name hint from the SAML message.
Want Assertions Signed	Indicates whether this IdP expects a signed assertion.
Want Assertions Encrypted	Indicates whether this IdP expects an encrypted assertion.
Force Authentication	The user must enter their credentials at the external IdP even when the user is already logged in.
Validate Signature	When ON, the realm expects SAML requests and responses from the external IdP to be digitally signed.
Validating X509 Certificate	The public certificate Imply Hybrid Auth uses to validate the signatures of SAML requests and responses from the external IdP.
Sign Service Provider Metadata	When ON, Imply Hybrid Auth uses the realm's key pair to sign the SAML Service Provider Metadata descriptor.
Pass subject	Controls if Imply Hybrid Auth forwards a login_hint query parameter to the IdP. Imply Hybrid Auth adds this field's value to the login_hint parameter in the AuthnRequest Subject so destination providers can prefill their login form.
Allowed clock skew	Tolerated clock skew in seconds when validating IdP tokens. Default is 0.
Allowed clock skew	Clock skew in seconds that is tolerated when validating IdP tokens. Default value is zero.

OpenID Connect

Imply Hybrid Auth can broker IdPs based on OpenID Connect v1.0 and Keycloak OpenID Connect.

To add an OpenID Connect IdP, select OpenID Connect v1.0 or Keycloak OpenID Connect from the Add provider list.

For common IdP settings, see Set up an identity provider. This section lists the OIDC-specific settings.

Configuration	Description
Authorization URL	The authorization URL endpoint the OIDC protocol requires.
Pass login_hint	Passes a login hint to the IdP.
Pass current locale	Pass the current locale to the provider as a ui_locales parameter.
Token URL	The token URL endpoint the OIDC protocol requires.
Logout URL	The logout URL endpoint in the OIDC protocol. This value is optional.
Backchannel Logout	A background, out-of-band, REST request to the IdP to log out the user. Some IdPs perform logout through browser redirects only, as they may identify sessions using a browser cookie.
Disable User Info	Whether to use a user information service to get additional information about the user.
User Info URL	An endpoint the OIDC protocol defines. This endpoint points to user profile information.
Issuer	Imply Hybrid Auth validates issuer claims, in responses from the IdP, against this value.
Client Authentication	Defines the client authentication method Imply Hybrid Auth uses with the Authorization Code Flow. In the case of JWT signed with a private key, Imply Hybrid Auth uses the realm private key. In the other cases, define a client secret. See Client Authentication specifications for more information.
Environment ID	Client identifier registered with the IdP.
Environment Secret	Client secret from an external vault. This secret is necessary if you are using the Authorization Code Flow.
Client Assertion Signature Algorithm	Signature algorithm to create JWT assertion as client authentication. In the case of JWT signed with private key or client secret as jwt, it is required. If no algorithm is specified, the following algorithm is adapted. RS256 is adapted in the case of JWT signed with private key. HS256 is adapted in the case of environment secret as jwt.
Default Scopes	A list of OIDC scopes Imply Hybrid Auth sends with the authentication request. The default value is openid. A space separates each scope.
Prompt	The prompt parameter in the OIDC specification. Through this parameter, you can force re-authentication and other options. See the specification for more details.
Accepts prompt=none forward from client	Specifies if the IdP accepts forwarded authentication requests containing the prompt=none query parameter. If a realm receives an auth request with prompt=none, the realm checks if the user is currently authenticated and returns a login_required error if the user has not logged in. When Imply Hybrid Auth determines a default IdP for the auth request (using the kc_idp_hint query parameter or having a default IdP for the realm), you can forward the auth request with prompt=none to the default IdP. The default IdP checks the authentication of the user there. Because not all IdPs support requests with prompt=none, Imply Hybrid Auth uses this switch to indicate that the default IdP supports the parameter before redirecting the authentication request. If the user is unauthenticated in the IdP, the client still receives a login_required error. If the user is authentic in the IdP, the client can still receive an interaction_required error if Imply Hybrid Auth must display authentication pages that require user interaction. This authentication includes required actions (for example, password change), consent screens, and screens set to display by the first broker login flow or post broker login flow.
Validate Signatures	Specifies if Imply Hybrid Auth verifies signatures on the external ID Token signed by this IdP. If ON, Imply Hybrid Auth must know the public key of the external OIDC IdP. For performance purposes, Imply Hybrid Auth caches the public key of the external OIDC IdP. If your private key is compromised, update your keys and clear the keys cache.
Use JWKS URL	This switch is applicable if Validate Signatures is ON. If Use JWKS URL is ON, Imply Hybrid Auth downloads the IdP public keys from the JWKS URL. New keys download when the IdP generates a new key pair. If OFF, Imply Hybrid Auth uses the public key (or certificate) from its database, so when the IdP key pair changes, import the new key to the Imply Hybrid Auth database as well.
JWKS URL	The URL pointing to the location of the IdP JWK keys. For more information, see JWK specification. If you use an external Imply Hybrid Auth as an IdP, you can use a URL such as http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs if your brokered Imply Hybrid Auth is running on http://broker-keycloak:8180 and its realm is test.
Use PKCE	Use PKCE (Proof of Key-code exchange) for IdP Brokering.
PKCE Method	PKCE Method to use.
Forwarded Query Parameters	Non OpenID Connect/OAuth standard query parameters to be forwarded to external IdP from the initial app request to Authorization Endpoint. Enter multiple parameters separated by comma (,).

Mapper types

A mapper type defines how user attributes and claims are mapped between an IdP and Imply Hybrid Auth.

OIDC mapper types

The following is a list of OIDC IdP mapper settings based on the mapper type:

• Advanced Claim to Group: Map an OIDC IdP group to a group in Imply. For this mapper, configure:
  • Claims: The claim name and the claim value to search for in the ID token of the IdP. You can reference nested claims using .—for example, address.locality. To use a dot (.) literally, escape it with a backslash (\.).
  • Regex Claim Values: The setting that specifies how to interpret claim values. If enabled, Imply interprets claim values as regular expressions.
  • Group: The Imply group to assign the user to if the claim is present. Click Select Group to open the Group Selector dialog.
• Advanced Claim to Role: Grant the user the specified realm or client role. For this mapper, configure:
  • Claims: The claim value to search for in the token as a name/value pair. You can reference nested claims using dot notation as described in Attribute Importer.
  • Regex Claim Values: If enabled, claim values are interpreted as regular expressions.
  • Role: The Imply role to map the claim to. Click Select Role to browse roles or type in the field. To reference an environment role, use the syntax clientname.clientrole, for example, myclient.myrole.
• Attribute Importer: Import declared claim into the specified user property or attribute. For this mapper, configure:
  • Claim: The name of the claim to search for in the token. You can reference nested claims using a .—for example, address.locality. Escape literal dots (.) with a backslash (\.).
  • User Attribute Name: The name of the user attribute to store the claim. Use email, lastName, and firstName to map to the respective predefined user properties.
• Claim to Role: Grant the user the specified realm or client role. For an OIDC mapper, configure:
  • Claim: The name of the claim to search for in the token. You can reference nested claims using dot notation as described in Attribute Importer.
  • Claim Value: The value of the claim. If the claim is an array, then the value must be contained in the array.
  • Role: The Imply role to map the claim to. Click Select Role to browse roles or type in the field. To reference an environment role, use the syntax clientname.clientrole, for example, myclient.myrole.
• Hardcoded Attribute: Hardcode a value to a specific user attribute. For this mapper, configure:
  • User Attribute: The name of the user attribute to hardcode.
  • User Attribute Value: The value of the attribute to be hardcoded.
• Hardcoded Role: A role to assign to users imported from the IdP.
• Hardcoded User Session Attribute: Hardcode a value to a specific user session attribute. For this mapper, configure:
  • User Session Attribute: The name of the hardcoded user session attribute.
  • User Session Attribute Value: The value of the hardcoded user session attribute to be mapped to the configured role.
• Username Template Importer: Allows template-style value substitutions in the mapping. For this mapper, configure:
  • Template: The template to use to format the username to import. Enclose substitutions in ${}. For example: ${ALIAS}.${CLAIM.sub}, where
    • ALIAS is the provider alias.
    • CLAIM.<NAME> references an ID or access token claim. The substitution can be converted to upper or lower case by appending |uppercase or |lowercase to the substituted value, such as ${CLAIM.sub | lowercase}.
    • Target: The destination field for the mapper. LOCAL, the default option, means that the changes are applied to the username stored in the local database upon user import. BROKER_ID and BROKER_USERNAME means that the changes are stored into the ID or username used for federation user lookup, respectively.

SAML mapper types

The following is a list of SAML IdP mapper settings based on the mapper type:

• Advanced Attribute to Group: Map a SAML IdP group to a group in Imply. For this mapper, configure:
  • Attributes: The attribute name and the attribute value to search for in the ID token of the IdP. You can reference nested attributes using .—for example, address.locality. To use a dot (.) literally, escape it with a backslash (\.).
  • Regex Attribute Values: Specifies how to interpret attribute values. If enabled, Imply interprets attribute values as regular expressions.
  • Group: The Imply group to assign the user to if the attribute is present. Click Select group to open the Group Selector dialog.
• Advanced Attribute to Role: Grant the user the specified realm or client role. For this mapper, configure:
  • Attributes: The attribute value to search for in the token as a name/value pair. You can reference nested attributes using a .—for example, address.locality. Escape literal dots (.) with a backslash (\.).
  • Regex Attribute Values: If enabled, attribute values are interpreted as regular expressions.
  • Role: The Imply role to map the attribute to. Click Select Role to browse roles or type in the field. To reference an environment role, use the syntax clientname.clientrole, for example, myclient.myrole.
• Attribute Importer: Import the declared attribute into the specified user property or attribute. For this mapper, configure:
  • Attribute Name: The name of the attribute to search for in assertion. You can reference nested attributes using a .—for example, address.locality. Escape literal dots (.) with a backslash (\.).
  • Friendly Name: Friendly name of the attribute to search for in assertion.
  • Name Format: Name format of the attribute.
  • User Attribute Name: The name of the user attribute to store the SAML attribute. Use email, lastName, and firstName to map to the respective predefined user properties.
• SAML Attribute to Group: Map a SAML IdP group to a group in Imply. For this mapper, configure:
  • Attribute Name: The name of the attribute to search for in the assertion. You can leave this field blank and specify Friendly Name only.
  • Friendly Name: The friendly name of the attribute to search for in the assertion. You can leave this field blank and specify Attribute Name only.
  • Attribute Value: The value of the SAML attribute as it appears in the assertion.
  • Group: The Imply group to assign the user to if the claim is present. Click Select group to open the Group Selector dialog.
• SAML Attribute to Role: Grant the user the specified realm or client role. For this mapper, configure:
  • Attribute Name: The name of the attribute to search for in the token.
  • Attribute Value: The value of the attribute. If the attribute is an array, then the value must be contained in the array.
  • Role: The Imply role to map the attribute to. Click Select Role to browse roles or type in the field. To reference an environment role, use the syntax clientname.clientrole, for example, myclient.myrole.
• Hardcoded Attribute: Hardcode a value to a specific user attribute. For this mapper, configure:
  • User Attribute: The name of the user attribute to hardcode.
  • User Attribute Value: The value of the attribute to be hardcoded.
• Hardcoded Role: A role to assign to users imported from the IdP.
• Hardcoded User Session Attribute: Hardcode a value to a specific user session attribute. For this mapper, configure:
  • User Session Attribute: The name of the hardcoded user session attribute.
  • User Session Attribute Value: The value of the hardcoded user session attribute to be mapped to the configured role.
• Username Template Importer: Allows template-style value substitutions in the mapping. For this mapper, configure:
  • Template: The template to use to format the username to import. Enclose substitutions in ${}. For example: ${ALIAS}.${NAMEID}, where
    • ALIAS is the provider alias.
    • NAMEID references an ID or access token attribute.
  • Target: The destination field for the mapper. LOCAL, the default option, means that the changes are applied to the username stored in the local database upon user import. BROKER_ID and BROKER_USERNAME means that the changes are stored into the ID or username used for federation user lookup, respectively.