POST Identity Providers

The POST /IdentityProviders operation creates an identity provider in AnyCAGateway REST. On success, the operation returns HTTP 200 OK with  the details of the identity provider.

Tip:  The Admin role (see Roles and Permissions) is required to use this operation.

Table 1350: POST Identity Providers Input Parameters

Name

In

Description
Authentication Scheme Body Required. A string indicating the authentication scheme (reference name) for the identity provider. This must be a unique value among identity providers.
Display Name Body Required. A string indicating the display name for the identity provider. This must be a unique value among identity providers.
ProviderType Body

Required. A string indicating the AnyCAGateway REST provider type of the identity provider. Possible values are:

  • Generic—select this for Keycloak

  • Auth0

Parameters Body

Required. An object containing information for each parameter set for the identity provider. ClosedShow parameter details.

Table 1351: Identity Provider Parameters

Name Type Example

Description
Auth0 API URL

1 - String

  

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 1 - String https:// keyidp-server .keyexample.com /realms /Keyfactor

The issuer/authority endpoint URL of 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

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.
Authorization Endpoint 1 - String 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

This parameter is required.
Client Id 1 - String Gateway- OIDC- Client

The ID of the client you created in the identity provider to provide the primary authentication from the gateway to the identity provider.

For Keycloak, seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation.

This parameter is required.
Client Secret 2 - Secret  

The client secret of the client you created in the identity provider to provide the primary authentication from the gateway to the identity provider.

This is provided as an object. For example:

Copy 
"ClientSecret":    {
    SecretValue: "SBz79vOPJtj690u8fq1gyhN2lR2lI4q"
}

A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the database.

For Keycloak, seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation.

This parameter is required.
Disable Bearer Token Scope Requirement 3 - Boolean  

A Boolean that turns off checking for a client scope of keyfactor-anyca-gateway configured in the identity provider for this Authentication Scheme (True or False).

Tip:  Set this to True (yes) if your identity provider does not provide a scope. Some identity providers do not offer the option to include a scope value (for example, Azure Active Directory). Other identity providers offer this option but do not include the scope by default (for example, Keycloak).
Important:  If you configure the DisableBearerTokenScopeRequirement option to False (no), you must either configure the client you’re using to connect from Keyfactor Command to the gateway to always include the scope keyfactor-anyca-gateway in the token or you must configure the keyfactor-anyca-gateway scope on the authentication methods tab when configuring the CA record in Keyfactor Command. Your OAuth identity provider needs to be configured to recognize keyfactor-anyca-gateway as a scope.
JSON Web Key Set Uri 1 - String https:// keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs

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

ForKeycloak, 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

This parameter is required.

Name Claim Type

 1 - String preferred_ username

A type of user claim for the identity provider containing a friendly name for the user.

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 to populate the username in the AnyCAGateway REST portal header.
OIDC Audience 1 - String  

The audience value for tokens issued from the identity provider.

Claims are rejected unless they include the audience defined by this parameter, provided that a value has been specified. Only one audience may be specified. This parameter applies to OpenID Connect tokens only.

This parameter is optional.
SignOut URL 1 -String 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 1 - String 60 The number of seconds a request to the OAuth identity provider is allowed to process before timing out with an error.
Token Endpoint 1 - String 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

This parameter is required.
User Info Endpoint 1 - String 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

For example:

Copy 
{
    AuthenticationScheme: "RESTAnyGateway",
    DisplayName: "REST AnyGateway",
    ProviderType: "Generic",
    Parameters: {
        JSONWebKeySetUri: "https://appsrvr18.keyexample.com:4443/realms/Keyexample/protocol/openid-connect/certs",
        TokenEndpoint: "https://appsrvr18.keyexample.com:4443/realms/Keyexample/protocol/openid-connect/token",
        UserInfoEndpoint: "https://appsrvr18.keyexample.com:4443/realms/Keyexample/protocol/openid-connect/userinfo",
        AuthorizationEndpoint: "https://appsrvr18.keyexample.com:4443/realms/Keyexample/protocol/openid-connect/auth",
        Authority: "https://appsrvr18.keyexample.com:4443/realms/Keyexample",
        ClientSecret: {
            "SecretValue": "0SBz79vOPJtj690u8fq1gyhN2lR2lI4q"
        },
        ClientId: "RESTGateway",
        NameClaimType: "preferred_username"
    }
}

Table 1352: POST Identity Providers Response Data

Name

Description
ID A string containing the AnyCAGateway REST reference GUID for the identity provider.
Authentication Scheme A string indicating the authentication scheme (reference name) for the identity provider. This must be a unique value among identity providers.
Display Name A string indicating the display name for the identity provider. This must be a unique value among identity providers.
TypeId

A string indicating the reference GUID for the type of identity provider. Possible values include:

  • F96B6464-11B7-4499- BEA7-B5AA6BA1571D (Generic)

  • 5AA04122-CD7C-48BA- AC11-F39E30AE8720 (Auth0)
AuthenticationEnabled

Optional, but set to True by default if not explicitly set through POST. A Boolean that allows users to turn on and off identity providers in the AnyCAGateway REST.

Note:  Identity providers cannot be False if the provider is used as the default identity provider for login in the appsettings.json file. Users cannot authenticate with identity providers that are False. Internally defined identity providers cannot be set to False (for example, Active Directory, client certificates, unknown, internal use).
Parameters

An array of objects containing information for each parameter set for the identity provider. ClosedShow parameter details.

Each parameter (Table 1351: Identity Provider Parameters) contains the data shown in Table 1354: Identity Provider Response Parameter Structure.

Table 1353: Identity Provider Parameters

Name Type Example

Description
Auth0 API URL

1 - String

  

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 1 - String https:// keyidp-server .keyexample.com /realms /Keyfactor

The issuer/authority endpoint URL of 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

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.
Authorization Endpoint 1 - String 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

This parameter is required.
Client Id 1 - String Gateway- OIDC- Client

The ID of the client you created in the identity provider to provide the primary authentication from the gateway to the identity provider.

For Keycloak, seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation.

This parameter is required.
Client Secret 2 - Secret  

The client secret of the client you created in the identity provider to provide the primary authentication from the gateway to the identity provider.

This is provided as an object. For example:

Copy 
"ClientSecret":    {
    SecretValue: "SBz79vOPJtj690u8fq1gyhN2lR2lI4q"
}

A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the database.

For Keycloak, seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation.

This parameter is required.
Disable Bearer Token Scope Requirement 3 - Boolean  

A Boolean that turns off checking for a client scope of keyfactor-anyca-gateway configured in the identity provider for this Authentication Scheme (True or False).

Tip:  Set this to True (yes) if your identity provider does not provide a scope. Some identity providers do not offer the option to include a scope value (for example, Azure Active Directory). Other identity providers offer this option but do not include the scope by default (for example, Keycloak).
Important:  If you configure the DisableBearerTokenScopeRequirement option to False (no), you must either configure the client you’re using to connect from Keyfactor Command to the gateway to always include the scope keyfactor-anyca-gateway in the token or you must configure the keyfactor-anyca-gateway scope on the authentication methods tab when configuring the CA record in Keyfactor Command. Your OAuth identity provider needs to be configured to recognize keyfactor-anyca-gateway as a scope.
JSON Web Key Set Uri 1 - String https:// keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs

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

ForKeycloak, 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

This parameter is required.

Name Claim Type

 1 - String preferred_ username

A type of user claim for the identity provider containing a friendly name for the user.

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 to populate the username in the AnyCAGateway REST portal header.
OIDC Audience 1 - String  

The audience value for tokens issued from the identity provider.

Claims are rejected unless they include the audience defined by this parameter, provided that a value has been specified. Only one audience may be specified. This parameter applies to OpenID Connect tokens only.

This parameter is optional.
SignOut URL 1 -String 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 1 - String 60 The number of seconds a request to the OAuth identity provider is allowed to process before timing out with an error.
Token Endpoint 1 - String 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

This parameter is required.
User Info Endpoint 1 - String 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 (seeConfiguring Keycloak and Collecting Data for the Keyfactor Command Installation).

Table 1354: Identity Provider Response Parameter Structure

Parameter Description
Id An integer indicating the Keyfactor Command reference ID for the parameter.
Name A string indicating the short reference name for the parameter (for example, NameClaimType).
Display Name A string indicating the display name for the parameter (for example, Name Claim Type).
Required A Boolean indicating whether the parameter is required (True) or not (False).
Data Type

An integer indicating the data type for the parameter. Possible values are:

  • 1: String

  • 2: Secret

  • 3: Boolean
Value A string indicating the value set for the parameter, for parameters of type 1 or 3.
Secret Value

A string indicating the value set for the parameter, for parameters of type 2.

Due to its sensitive nature, this value is not returned in responses.
Tip:  Use the AnyGatewayClosed The Keyfactor AnyGateway is a generic third-party CA gateway framework that allows existing CA gateways and custom CA integrations to share a common product architecture. AnyGateway is available in two formats: a DCOM-based gateway and a REST-based gateway. The REST-based AnyGateway is the newer implementation and is recommended for new deployments. The DCOM-based AnyGateway is provided for compatibility with existing environments and is planned for eventual retirement. REST 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. Reference and Utility to explore and test AnyCAGateway REST API operations. This tool allows you to submit requests, view responses, and verify API request and response behavior. It is intended primarily for testing and development and also serves as reference documentation for the API.

You can access the API Reference and Utility from the Help icon () in the AnyCAGateway REST portal, located next to the Logout button.