PingGateway 2024.6

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": Issuer repository reference,
    "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, then 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.

The provider configuration object properties are as follows:

"name": string, required

A name for the provider configuration.

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

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

"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 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": configuration expression<url>, required unless obtained through wellKnownEndpoint

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

"registrationEndpoint": configuration expression<url>, optional

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

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

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

"userInfoEndpoint": configuration expression<url>, optional

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

Default: no UserInfo is obtained from the provider.

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

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

For more information, refer to OpenID Connect Session Management.

Default: No endpoint

"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 to the current user session in AM.

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

Default: No endpoint

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

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

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

"issuerHandler": Handler reference, optional

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

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

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

See also Handlers, ClientHandler.

"issuerRepository": Issuer repository reference, optional

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

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, then a default one named IssuerRepository is created in the current route.

See also IssuerRepository.

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

In summary when the OpenID Provider is not known in advance, it might be possible to 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 supported domains lists 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. Do not 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": 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" ]
    }
}

More information