Issuer

Describes an OAuth 2.0 Authorization Server or an OpenID Provider that PingGateway can use as a OAuth 2.0 client or OpenID Connect relying party.

The Issuer requires OpenID Connect ID Token signature validation. It doesn’t support ID Token encryption.

An Issuer is usually referenced from a ClientRegistration.

Usage

{
  "name": string,
  "type": "Issuer",
  "config": {
    "wellKnownEndpoint": configuration expression<url>,
    "idTokenVerificationSecretId": configuration expression<string>,
    "secretsProvider": SecretsProvider reference,
    "authorizeEndpoint": configuration expression<url>,
    "registrationEndpoint": configuration expression<url>,
    "tokenEndpoint": configuration expression<url>,
    "userInfoEndpoint": configuration expression<url>,
    "endSessionEndpoint": configuration expression<url>,
    "revocationEndpoint": configuration expression<url>,
    "issuer": configuration expression<string>,
    "issuerHandler": Handler reference,
    "issuerRepository": IssuerRepository reference, // deprecated
    "useDeprecatedIssuerRepository": configuration expression<boolean>, // deprecated
    "supportedDomains": [ pattern, … ],
    "idTokenSkewAllowance": configuration expression<duration>
  }
}

Properties

If the provider has a well-known configuration URL as defined for OpenID Connect 1.0 Discovery that returns JSON with at least authorization and token endpoint URLs, you can specify that URL in the provider configuration. Otherwise, you must specify at least the provider authorization and token endpoint URLs, and optionally, the registration endpoint and user info endpoint URLs.

For token signature validation, if you don’t specify the well-known configuration URL, do specify the expected issuer and how to access the secret. For HMAC-based signature validation, PingGateway must have access to the symmetric key, such as the client secret it uses to connect to the OpenID provider. The verification secret ID expects a CryptoKey. The OAuth2 client secret ID to registering the client is a GenericSecret. At present, you can’t reuse the same secrets provider for both the client secret and signature validation.

wellKnownEndpoint

"wellKnownEndpoint": configuration expression<url>, required unless authorizeEndpoint and tokenEndpoint are configured

The URL to the well-known configuration resource described in OpenID Connect 1.0 Discovery.

idTokenVerificationSecretId

"idTokenVerificationSecretId": configuration expression<string>, optional

When OpenID Connect ID token signature validation is enabled on the ClientRegistration and no "wellKnownEndpoint" is set, set this to reference the provider’s public key for asymmetric ID token signature validation.

If the OpenID provider uses a symmetric (HMAC-based) signature algorithm, the symmetric key is the client secret. Configure the client secret ID in the ClientRegistration instead.

This secret ID must point to a CryptoKey in the "secretsProvider".

Default: Use the jwks_uri in the well-known configuration to get the asymmetric signature validation keys and ignore this setting.

secretsProvider

"secretsProvider": SecretsProvider reference, required when idTokenVerificationSecretId is set

The SecretsProvider to query for the signature validation secret.

Default: Use the jwks_uri in the well-known configuration to get the asymmetric signature validation keys and ignore this setting.

authorizeEndpoint

"authorizeEndpoint": configuration expression<url>, required unless obtained through wellKnownEndpoint

The URL to the provider’s OAuth 2.0 authorization endpoint.

registrationEndpoint

"registrationEndpoint": configuration expression<url>, optional

The URL to the provider’s OpenID Connect dynamic registration endpoint.

tokenEndpoint

"tokenEndpoint": configuration expression<url>, required unless obtained through wellKnownEndpoint

The URL to the provider’s OAuth 2.0 token endpoint.

userInfoEndpoint

"userInfoEndpoint": configuration expression<url>, optional

The URL to the provider’s OpenID Connect UserInfo endpoint.

Default: no UserInfo is obtained from the provider.

endSessionEndpoint

"endSessionEndpoint": configuration expression<url>, optional

The URL to the Authorization Server’s end_session_endpoint. In OpenID Connect, when a request accesses this endpoint, PingGateway kills the user session in AM.

Example endpoint: https://am.example.com:8443/openam/oauth2/realms/root/realms/alpha/connect/endSession

Learn more in OpenID Connect Session Management.

Default: No endpoint

revocationEndpoint

"revocationEndpoint": configuration expression<url>, optional

The URL to the Authorization Server’s revocation_endpoint. When a request accesses this endpoint, PingGateway revokes access tokens or refresh tokens associated with the current user session in AM.

Example endpoint: https://am.example.com:8443/openam/oauth2/realms/root/realms/alpha/token/revoke

Default: No endpoint

issuer

"issuer": configuration expression<string>, required for OIDC unless obtained through the wellKnownEndpoint

The identifier of the issuer for OpenID Connect ID tokens. This must match the iss claim value in the ID tokens.

Default: Use the issuer in the well-known configuration.

issuerHandler

"issuerHandler": Handler reference, optional

Invoke this HTTP client Handler to communicate with the Authorization Server.

Provide the name of a Handler object defined in the heap or an inline handler configuration object.

Set this to the name of a ClientHandler configured in the heap or a Chain that ends in a ClientHandler.

Default: PingGateway uses the default ClientHandler.

issuerRepository (deprecated)

"issuerRepository": Issuer repository reference, optional

A repository of OAuth 2.0 issuers, built from discovered issuers and the PingGateway configuration.

The IssuerRepository (deprecated) is deprecated.

For issuers known in advance, add their settings to the ClientRegistration.

For discovery, if the IssuerRepository had an "issueHandler", configure an AuthorizationCodeOAuth2ClientFilter "discoveryHandler" instead.

Provide the name of an IssuerRepository object defined in the heap.

Default: Look up an issuer repository named IssuerRepository in the heap. If none is explicitly defined, PingGateway creates a default one named IssuerRepository in the current route.

useDeprecatedIssuerRepository (deprecated)

"useDeprecatedIssuerRepository": configuration expression<boolean>, optional

Whether to use the deprecated default "IssuerRepository" from the heap.

This property is deprecated.

true: When the "issuerRepository" isn’t set, use the deprecated default "IssuerRepository" from the heap.
false: When the "issuerRepository" isn’t set, don’t add this issuer to any IssuerRepository.

Default: true

supportedDomains

"supportedDomains": array of patterns, optional

One or more domain patterns to match domain names that are handled by this issuer used as a shortcut for OpenID Connect discovery before performing OpenID Connect dynamic registration.

When the OpenID Provider isn’t known in advance, PingGateway can discover the OpenID Provider Issuer based on information provided by the user, such as an email address. The OpenID Connect discovery specification explains how to use WebFinger to discover the issuer. PingGateway can discover the issuer in this way. As a shortcut, PingGateway can also use the supported domains to find issuers already described in the PingGateway configuration.

To use this shortcut, PingGateway extracts the domain from the user input and looks for an issuer whose supported domains list contains a match.

Supported domains patterns match host names with optional port numbers. Don’t specify a URI scheme such as HTTP. PingGateway adds the scheme. For instance, *.example.com matches any host in the example.com domain. You can specify the port number as well as in host.example.com:8443. Patterns must be valid regular expression patterns according to the rules for the Java Pattern class.

idTokenSkewAllowance

"idTokenSkewAllowance": configuration expression<duration>, optional

Acceptable clock skew when validating OpenID Connect ID Tokens.

Default: zero

Examples

The following example shows an AM issuer configuration for AM. AM exposes a well-known endpoint for the provider configuration, but this example demonstrates use of the other fields:

{
    "name": "openam",
    "type": "Issuer",
    "config": {
        "authorizeEndpoint":
          "https://am.example.com:8443/openam/oauth2/authorize",
        "registration_endpoint":
          "https://am.example.com:8443/openam/oauth2/connect/register",
        "tokenEndpoint":
          "https://am.example.com:8443/openam/oauth2/access_token",
        "userInfoEndpoint":
          "https://am.example.com:8443/openam/oauth2/userinfo",
        "supportedDomains": [ "mail.example.*", "docs.example.com:8443" ]
    }
}

The following example shows an issuer configuration for Google:

{
    "name": "google",
    "type": "Issuer",
    "config": {
        "wellKnownEndpoint":
          "https://accounts.google.com/.well-known/openid-configuration",
        "supportedDomains": [ "gmail.*", "googlemail.com:8052" ]
    }
}

PingGateway 2024.11