POST Identity Providers

The POST /IdentityProviders method is used to add an identity provider in the AnyCAGateway REST. This method returns HTTP 200 OK on a success with the details of the identity provider.

Table 974: 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 Keyfactor Command provider type of the identity provider. Possible values are:

  • Generic—select this for Keyfactor Identity Provider

  • Auth0

Parameters Body

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

Table 975: Identity Provider Parameters

Name Type Example

Description
OIDC Audience 1 - String Gateway- OIDC- Client

The audience value for tokens issued from the identity provider.

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

Gateway- OIDC- Client

This parameter is optional.
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:// my-keyidp-server .keyexample.com /realms /Keyfactor

The issuer/authority endpoint URL for the identity provider.

For Keyfactor_IdP, 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 Keyfactor Identity Provider 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:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /auth

The authorization endpoint URL for the identity provider.

For Keyfactor_IdP, 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 Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).

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

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

For Keyfactor_IdP this should be:

Gateway- OIDC- Client

For more information, seeConfiguring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation.

This parameter is required.
Client Secret 2 - Secret  

The secret for the client application created in the identity provider for primary application use. A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the database.

For Keyfactor_IdP, seeConfiguring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation.

This parameter is required.
Disable Bearer Token Scope Requirement 3 - Boolean   A Boolean that disables checking for a client scope of keyfactor-anyca-gateway configured in the identity provider for this Authentication Scheme (true) or not (false).
JSON Web Key Set Uri 1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs

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

For Keyfactor_IdP, 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 Keyfactor Identity Provider 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 Keyfactor_IdP this should be:

preferred_ username

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

This parameter is required.
SignOut URL 1 -String https:// my-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.
Token Endpoint 1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /token

The token endpoint URL for the identity provider.

For Keyfactor_IdP, 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 Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).

This parameter is required.
Token Scope 1 - String  

One or more scopes that should be included in token requests delivered to the identity provider when making a token request where Keyfactor Command is acting as the OAuth client. Multiple scopes should be separated by spaces.

This value is not used for Keyfactor_IdP.
User Info Endpoint 1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs

The user info endpoint URL for the identity provider.

For Keyfactor_IdP, 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 Keyfactor Identity Provider 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 976: 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)
Parameters

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

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

Table 977: Identity Provider Parameters

Name Type Example

Description
OIDC Audience 1 - String Gateway- OIDC- Client

The audience value for tokens issued from the identity provider.

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

Gateway- OIDC- Client

This parameter is optional.
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:// my-keyidp-server .keyexample.com /realms /Keyfactor

The issuer/authority endpoint URL for the identity provider.

For Keyfactor_IdP, 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 Keyfactor Identity Provider 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:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /auth

The authorization endpoint URL for the identity provider.

For Keyfactor_IdP, 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 Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).

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

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

For Keyfactor_IdP this should be:

Gateway- OIDC- Client

For more information, seeConfiguring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation.

This parameter is required.
Client Secret 2 - Secret  

The secret for the client application created in the identity provider for primary application use. A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the database.

For Keyfactor_IdP, seeConfiguring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation.

This parameter is required.
Disable Bearer Token Scope Requirement 3 - Boolean   A Boolean that disables checking for a client scope of keyfactor-anyca-gateway configured in the identity provider for this Authentication Scheme (true) or not (false).
JSON Web Key Set Uri 1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs

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

For Keyfactor_IdP, 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 Keyfactor Identity Provider 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 Keyfactor_IdP this should be:

preferred_ username

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

This parameter is required.
SignOut URL 1 -String https:// my-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.
Token Endpoint 1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /token

The token endpoint URL for the identity provider.

For Keyfactor_IdP, 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 Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).

This parameter is required.
Token Scope 1 - String  

One or more scopes that should be included in token requests delivered to the identity provider when making a token request where Keyfactor Command is acting as the OAuth client. Multiple scopes should be separated by spaces.

This value is not used for Keyfactor_IdP.
User Info Endpoint 1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs

The user info endpoint URL for the identity provider.

For Keyfactor_IdP, 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 Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).

Table 978: 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 (e.g. NameClaimType).
Display Name A string indicating the display name for the parameter (e.g. 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.