Identity Providers

Identity providers in Keyfactor Command control how users authenticate to the Keyfactor Command Management Portal and the Keyfactor APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command..

During installation, you select an identity provider type (Active Directory or OAuth). For OAuth configurations, one or more identity providers may be configured. In most environments, this configuration does not need to change after installation.

If you need to migrate from one identity provider type to another, or add additional OAuth identity providers, you can do so by re-running the Keyfactor Command configuration wizard, using the Management Portal, or through the Keyfactor API.

Authentication with only one identity provider type at a time (Active Directory or OAuth) is supported per Keyfactor Command server. Existing identity providers can be modified, but they cannot be deleted.

Tip:  Where to find this in the Management Portal:
System Settings → Identity Providers

This page supports the standard query format described in Using Search in the Management Portal and includes its own set of query parsers specific to this operation. Use the following parsers to filter and refine results for this page.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Identity Providers > Read

  • AuthenticationScheme

    Complete or partial matches with the authentication scheme for the identity provider.

  • DisplayName

    Complete or partial matches with the display name of the identity provider.

  • ProviderType

    Complete or partial matches with the provider type for the identity provider. Supported provider types include:

    • Active Directory

    • Auth0

    • Generic

  • AuthorizationUrL

    Complete or partial matches with the authorization URL (endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server.) of the identity provider.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

Identity Providers > Read
Identity Providers > Modify

To create an identity provider or modify an existing one:

  1. On the Identity Providers page, choose Add from the toolbar to create a new identity provider, or select an existing identity provider and double-click or choose Edit from the toolbar or right-click menu.

  2. On the Add/Editing Identity Provider page, populate each tab of the dialog with the information desired for the selected identity provider.

    1. On the Details tab, select a Type in the dropdown. Most identity providers can be supported with the Generic type. For Auth0, select the Auth0 type.

      Enter a short name for the provider in the Authentication Scheme and a longer name in the Display Name. The Type and Authentication Scheme cannot be modified on an edit.

      Important:  The value in the Authentication Scheme field must match the provider name referenced in redirect URLs (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation).

      In the Permission Set dropdown, select a permission set to apply to the identity provider. For more information about permission sets, see Permission Sets.

      The Enable option only appears when editing an existing identity provider. Newly added identity providers are always active. Existing identity providers may be deactivated, if desired. Identity providers cannot be deactivated if the provider is used as the default identity provider for login or as the Identity Provider Name selected in the Identity Provider Token Credentials section of the Authentication tab in the configuration wizard. When an identity provider is deactivated, the following will not be available for that identity provider:

      Note:  To view or edit an identity provider in the Keyfactor Command Management Portal or with the Keyfactor API, a user must be assigned a security role that has been granted the Identity Providers > Read and Identity Providers > Modify (for edits) permissions and that has the same permission set applied to it as has been applied to the identity provider.

      Figure 477: Details for an Identity Provider

    2. On the Parameters tab, select each parameterClosed A parameter or argument is a value that is passed into a function in an application. to configure and click Edit to open the Edit <Parameter Name> Parameter dialog, the contents of which will vary depending on the parameter selected. For information about the specific parameters, see Table 71: Identity Provider Parameters.

      Click Import Discovery Document to enter the discovery URL of the identity provider and automatically populate the Authority, AuthorizationEndpoint, TokenEndpoint, JSONWebKeySetUri, and UserInfoEndpoint fields. Click Fetch to retrieve the information and Save to save it to the identity provider form.

      Figure 478: Import Discovery Document for an Identity Provider

      Figure 479: Edit Parameters for an Identity Provider

  3. Click Save to save the identity provider.

Table 71: Identity Provider Parameters

Name Example

Description
OIDCAudience
Command- OIDC- Client

The audience value for tokens issued from the identity provider.

For Keycloak, this should be set to the same value as the Client Id. For example:

Command- OIDC- Client

This parameter is required.
Auth0APIURL
 

The unique identifier defined in Auth0 or a similar identity provider for the API.

This parameter only appears if Auth0 is selected as the type and is required in that case.
Authority
 https:// keyidp-server .keyexample.com /realms /Keyfactor

The issuer/authority endpoint URL for the identity provider.

For Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.

This parameter is required.

Tip:  When you add or update an identity provider, the provider’s discovery document is validated based on this authority URL. The discovery document is also validated periodically in the background. The following are validated:

  • That the discovery document is reachable using the Authority value provided and can be parsed into a valid discovery document.

  • That the Authority URL matches the Issuer returned in the discovery document.

  • That all the URLs on the discovery document are using HTTPS.

  • That the JSONWebKeySetUri value is included on the discovery document.

  • That any endpoint configuration values (Authorization Endpoint, Token Endpoint, UserInfo Endpoint, JSONWebKeySetUri) that have been saved or are being saved match—including case—the values returned in the discovery document. The UserInfo Endpoint is not a required configuration field, but if a value is provided, it must match what’s in the discovery document.

If any of these validation tests fail, any identity provider changes in process will not be saved and an error will be displayed or logged.
AuthorizationEndpoint
https:// keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /auth

The authorization endpoint URL for the identity provider.

For Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.

This parameter is required.
ClientId
Command- OIDC- Client

The ID of the client application created in the identity provider for primary application use.

For Keycloak, this should be:

Command- OIDC- Client

For more information, see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation).

This parameter is required.
ClientSecret
  

The client secret for the client you created in the identity provider to provide the primary authentication from Keyfactor Command to the identity provider.

For Keycloak, see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation for help locating the client secret.

Select the Load From Keyfactor Secrets radio button if you want Keyfactor Command to encrypt and store the secret value in the Keyfactor Command database as a secret. Enter and confirm the value in the Secret Value field.

Important:  Keyfactor highly recommends that you use strong passwords for any accounts or certificates related to Keyfactor Command and associated products, especially when these have elevated or administrative access. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.
Tip:  A Keyfactor secret is a user-defined password or other information that is encrypted and stored securely in the Keyfactor Command database. Although Keyfactor recommends using Privileged Access Management (see Privileged Access Management (PAM)) as a more secure solution to secure information, Keyfactor Secret has historically been an option for customers that don’t already have a relationship with a PAM provider such as CyberArk or Delinea/Thycotic. More recent versions of Keyfactor Command offer Keyfactor Command local PAM databases, allowing you to store secrets in the Keyfactor Command database using PAM.

Select the Load from PAM Provider radio button to store the secret value in a Keyfactor Command local or supported third-party PAM solution (see Privileged Access Management (PAM)). Select a PAM provider from the Providers dropdown. The remaining fields displayed depend on the selected provider. The following examples illustrate common PAM provider configurations and are not an exhaustive list of supported PAM provider extensions.

Keyfactor Command Local Database

Select Keyfactor Command Local Database from the Providers dropdown. The dialog displays the following field:

CyberArk

Select your CyberArk provider from the Providers dropdown (see Adding or Modifying a PAM Provider). The dialog displays the following field:

  • PrivateArk Folder Name: The path and name of the folder that stores the secret (for example, Root or Root\MyDir).
  • PrivateArk Protected Password Name: The name of the username or password to use for this instance.

Delinea/Thycotic

Select your Delinea/Thycotic provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The dialog displays the following field:

  • Thycotic Secret ID: The numeric ID of the secret to retrieve from provider server.

Hashicorp

Select your Hashicorp Vault provider in the Providers dropdown (see Adding or Modifying a PAM Provider). The dialog displays the following field:

  • KV Secret Key: The key of the secret to retrieve from the Hashicorp Vault.
  • KV Secret Name: The name of the secret to retrieve from the Hashicorp Vault.

This parameter is required.
FallbackUniqueClaimType
cid

A type of user claim for the identity provider containing a backup unique name for the user. This is provided in case the primary referenced name (see Unique Claim Type) does not contain a value. Some OAuth providers may provide one type of claim for users/clients of one type and another type of claim for users/clients of another type. For Keycloak, this should be:

cid

The cid (client ID) user claim type is also commonly used by other OAuth providers.

This parameter is required.
JSONWebKeySetUri
https:// keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs

The JWKS (JSON Web Key Set) URL for the identity provider.

For Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.

This parameter is required.
NameClaimType
preferred_ username

A type of user claim for the identity provider containing a friendly name for the user. Although the value for this field may not necessarily be unique within your identity provider (so might resolve to John Smith and the organization might have two users called John Smith), this can be confusing in Keyfactor Command, since the value is used as the user’s display name in areas such as the requester of a certificate, actors in audit logs, and users referenced in workflow instances. It is best to avoid duplicates.

For Keycloak, this should be:

preferred_ username

For Okta, this might be preferred_names (for example, john.smith@keyexample.com) or just name (for example, John Smith). For Auth0 this might be name (for example, johnsmith@keyexample.com).

This parameter is required.

Tip:  The value in this field is used as the first choice to populate the username in the Keyfactor Command Management Portal header, if available. This is not the value to use when logging into Keyfactor Command. For that, see Unique Claim Type.
RequestHeaders
groups

Custom OIDC request headers for the identity provider provided as name/value pairs.

Parameters configured in this value are added to the headers when Keyfactor Command sends an OIDC request to the OAuth server for the following request types:

  • Discovery Document

  • JSON Web Key Set

  • Token

If this parameter is added, the Name is required.
RequestURLParameters
groups

Custom OIDC request URL parameters for the identity provider provided as name/value pairs.

Parameters configured in this value are added to the URL queryString parameter when Keyfactor Command sends an OIDC request to the OAuth server for the following request types:

  • SignIn

  • SignOut

If this parameter is added, the Name is required.
RoleClaimType
groups

The value used to reference the type of group claim for the identity provider.

For Keycloak, this should be:

groups

This parameter is required.
OIDCScope
 

One or more scopes that are requested during the OIDC protocol when Keyfactor Command is the relying party. Multiple scopes should be separated by spaces.

This value is not typically used for Keycloak.
SignOutURL
https:// auth0-instance .us.auth0.com /oidc/logout

The signout URL for the identity provider.

This parameter only appears if Auth0 is selected as the type and is required in that case.
Timeout
 60 The number of seconds a request to the identity provider is allowed to process before timing out with an error.

TokenEndpoint

https:// keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /token

The token endpoint URL for the identity provider.

For Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.

This parameter is required.
UniqueClaimType
sub

A type of user claim for the identity provider containing a unique name for the user. For Keycloak, this should be:

sub

In Keycloak, this is a GUID uniquely identifying the user.

The sub (subject) user claim type is also commonly used by other OAuth providers.

See also FallbackUniqueClaimType.

This parameter is required.

Tip:  The value in this field is used as the second choice to populate the username in the Keyfactor Command Management Portal header if the Name Claim Type does not contain a value in the token.

The value in this field is the one to use when logging into Keyfactor Command.
UserInfoEndpoint
https:// keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs

The user info endpoint URL for the identity provider.

For Keycloak, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keycloak and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.
Tip:  Click the help icon () next to the Identity Providers page title to open the Keyfactor Software & Documentation Portal to this section. You will receive a prompt indicating:

You are being redirected to an external website ‘software.keyfactor.com'. Would you like to proceed?

You can also find Help in the NavigatorClosed The Navigator is the Keyfactor Command left-hand (newer versions) or top (older versions) navigation menu. Certificate collections and reports can be configured to be added to the menu using user-defined Show in Navigator settings.. From here you can choose to open either the Keyfactor Software & Documentation Portal at the home page or the Keyfactor API Endpoint Utility.

Keyfactor provides two sets of documentation: the On-Premises Documentation Suite and the Managed Services Documentation Suite. Which documentation set is accessed is determined by the Application Settings: On-Prem Documentation setting (see Application Settings: Console Tab).