Identity provider integration

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

When you enable Imply Hybrid Auth, you can control access to Imply Manager, Pivot, and Clarity, across all of your Imply Hybrid environments. Users can sign in with their Imply Hybrid username and password. You can also connect an identity provider (IdP) that supports Security Assertion Markup Language 2.0 (SAML) or OpenID Connect 1.0 (OIDC) identity protocols, and authenticate users with the IdP credentials. Once you have configured the IdP, a button corresponding to the IdP appears at login. Users can choose from any of the configured IdPs to sign in.

Set up an identity provider

When you connect an external IdP, it is not necessary to create users or assign roles in Imply. User creation and role assignment happens just-in-time based on the data in the IdP upon user login.

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 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.

The general flow is as follows:

Authentication

The following steps ensure that users can login to Imply with a third party provider:

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 example, for Okta, see this knowledge base article.

Step 2. Configure the identity provider in Imply Hybrid Auth

1. In the Imply Hybrid Auth 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 Auth provides support for SAML and OIDC protocols. You can configure and broker any IdP based on these open standards.
3. Scroll to the bottom of the page and expand the Import External IDP Config section.
4. Click Select File, locate and select the metadata file you downloaded, and click Import.
5. Configure a few remaining settings, including:
   • Name: A friendly name for this provider that will appear in the Imply Hybrid Auth interface.
   • Sync mode: The strategy for updating user information from the identity provider through mappers. Choose from the following options:
     • legacy to use the current behavior
     • import to keep the existing user data
     • force to update user data when possible
6. Click Save.

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. After you have verified or created the IdP attributes or claims, you can configure the mapping in Imply as follows.

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 Create.
4. In the Name field, enter a name for the mapper. This name is used only to identify the mapper in the Imply console; it has no other purpose.
5. For Sync Mode Override, select from these options:
   • import: Import user data only from when the user was created at first login.
   • force: Update user data at each user login.
   • inherit: Use the sync mode configured in the IdP; all other options override this sync mode.
   • legacy: Keep the behavior before this option was introduced.
6. For Mapper Type, choose from these options:
   • 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.
   • (OIDC) 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.
   • (SAML) 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.
   • 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.
   • 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.
   • Hardcoded Role: A role to assign to users imported from the IdP.
   • 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.
   • Username Template Importer: Allows template-style value substitutions in the mapping. Configuration options are:
     • 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.

The following screenshot shows a configuration for a mapper that assigns users with the Engineering Team value for the groups claim to the Client Admin role in Imply:

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. However, they are listed here for completeness.

Common settings

Although each type of provider has its own, specific configuration options, all share several common configuration options. 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	The Redirect URI is the endpoint hosted by Imply Hybrid Auth that the IdP sends information to when a user signs in. This field is populated for you by default.
Alias	The alias is a unique identifier for an IdP and references an internal IdP. Imply Auth uses the alias to build redirect URIs for OpenID Connect protocols that require a redirect URI or callback URL to communicate with an IdP. All IdPs must have an alias. Alias examples include facebook, google, and idp.acme.com.
Display Name	A friendly name for this provider that will appear in the Imply Hybrid Auth interface.
Enabled	Toggles the provider ON or OFF.
Store Tokens	When ON, Imply Auth stores tokens from the IdP.
Stored Tokens Readable	When ON, users can retrieve the stored IdP token. This action also applies to the broker client-level role read token.
Trust Email	When ON, Imply Auth trusts email addresses from the IdP. If the realm requires email validation, users that log in from this IdP do not need to perform the email verification process.
Account Linking Only	When ON, Imply Auth links existing accounts with this provider. This provider cannot log users in, and Imply Auth does not display this provider as an option on the login page.
GUI Order	The sort order of the available IdPs on the login page.
Hide on Login Page	When ON, Imply Auth does not display this provider as a login option on the login page. Clients can request this provider by using the kc_idp_hint parameter in the URL to request a login.
GUI order	The order in which this provider appears relative to the providers on the login page.
First Login Flow	The authentication flow Imply Auth triggers when users use this IdP to log into Imply Auth for the first time.
Post Login Flow	The authentication flow Imply Auth triggers when a user finishes logging in with the external IdP.
Sync Mode	Strategy to update user information from the IdP through mappers. When choosing legacy, Imply Auth uses the current behavior. Import does not update user data and force updates user data when possible.

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.

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.
Environment Authentication	Defines the environment 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	A realm acting as an OIDC client to the external IdP. The realm must have an OIDC environment ID if you use the Authorization Code Flow to interact with the external IdP.
Environment Secret	Environment secret from an external vault. This secret is necessary if you are using the Authorization Code Flow.
Environment Assertion Signature Algorithm	Signature algorithm to create JWT assertion as client authentication. In the case of JWT signed with private key or environment 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.
Issuer	Imply Hybrid Auth validates issuer claims, in responses from the IdP, against this value.
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.
Allowed clock skew	Clock skew in seconds that is tolerated when validating IdP tokens. Default value is zero.
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 (,).