ClientRegistration

A ClientRegistration holds information about registration with an OAuth 2.0 authorization server or OpenID Provider.

The configuration includes the client credentials that are used to authenticate to the identity provider. The client credentials can be included directly in the configuration, or retrieved in some other way using an expression, described in Expressions.

Usage

{
  "name": string,
  "type": "ClientRegistration",
  "config": {
    "clientId": expression,
    "clientSecretId": configuration expression<secret-id>,
    "issuer": Issuer reference,
    "registrationHandler": Handler reference,
    "scopes": [ expression, ...],
    "secretsProvider": SecretsProvider reference,
    "tokenEndpointAuthMethod": enumeration,
    "tokenEndpointAuthSigningAlg": string,
    "privateKeyJwtSecretId": configuration expression<secret-id>,
    "claims": map or runtime expression<map>,
    "jwtExpirationTimeout": duration
  }
}

Properties

"name": string, required

A name for the client registration.

"clientId": expression, required

The client_id obtained when registering with the authorization server. See also Expressions.

"clientSecretId": _configuration expression<secret-id>, required if tokenEndpointAuthMethod is client_secret_basic or client_secret_post

The secret ID of the client secret required to authenticate the client to the authorization server.

"issuer": Issuer reference, required

The provider configuration to use for this client registration.

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

See also Issuer.

"registrationHandler": 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: IG uses the default ClientHandler.

See also Handlers, ClientHandler.

"scopes": array of expressions, optional

OAuth 2.0 scopes to use with this client registration. See also Expressions.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the client secret. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, see Default Secrets Object.

"tokenEndpointAuthMethod": enumeration, optional

The authentication method with which a client authenticates to the authorization server or OpenID provider at the token endpoint. For information about client authentication methods, see OpenID Client Authentication. The following client authentication methods are allowed:

  • client_secret_basic: Clients that have received a client_secret value from the authorization server authenticate with the authorization server by using the HTTP Basic authentication scheme, as in the following example:

    POST /oauth2/token HTTP/1.1
    Host: as.example.com
    Authorization: Basic ....
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&
    code=...
  • client_secret_post: Clients that have received a client_secret value from the authorization server authenticate with the authorization server by including the client credentials in the request body, as in the following example:

    POST /oauth2/token HTTP/1.1
    Host: as.example.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&;
    client_id=...&
    client_secret=...&
    code=...
  • private_key_jwt: Clients send a signed JSON Web Token (JWT) to the authorization server. IG builds and signs the JWT, and prepares the request as in the following example:

    POST /token HTTP/1.1
    Host: as.example.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&
    code=...&
    client_id=<clientregistration_id>&
    client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
    client_assertion=PHNhbWxwOl ... ZT

    If the authorization server doesn’t support private_key_jwt, a dynamic registration falls back on the method returned by the authorization server, for example, client_secret_basic or client_secret_post.

    If tokenEndpointAuthSigningAlg is not configured, the RS256 signing algorithm is used for private_key_jwt.

    Consider these points for identity providers:

    • Some providers accept more than one authentication method.

    • If a provider strictly enforces how the client must authenticate, align the authentication method with the provider.

    • If a provider doesn’t support the authentication method, the provider sends an HTTP 400 Bad Request response with an invalid_client error message, according to RFC 6749 The OAuth 2.0 Authorization Framework, section 5.2 .

    • If the authentication method is invalid, the provider sends an IllegalArgumentException.

      Default: client_secret_basic

      "tokenEndpointAuthSigningAlg": string, optional

      The JSON Web Algorithm (JWA) used to sign the JWT that is used to authenticate the client at the token endpoint. The property is used when private_key_jwt is used for authentication.

      Use one of the following algorithms:

    • RS256: RSA using SHA-256

    • ES256: ECDSA with SHA-256 and NIST standard P-256 elliptic curve

    • ES384: ECDSA with SHA-384 and NIST standard P-384 elliptic curve

    • ES512: ECDSA with SHA-512 and NIST standard P-521 elliptic curve

      Default: RS256

      "privateKeyJwtSecretId": configuration expression<secret-id>, required when private_key_jwt is used for client authentication

      The secret ID of the key that is used to sign the JWT.

      "claims": map or runtime expression<map>, optional

      When private_key_jwt is used for authentication, this property specifies the claims used in the authentication. If this property is a map, the structure must have the format Map<String, Object>.

      The JWT can contain the following claim value and other optional claims, where claims that are not understood are ignored:

      "aud": string or array of strings, optional

      The URI of the authorization server that is the intended audience of the token.

      Default: URL of the authorization server token endpoint

      In the following example, the claims include the value aud, which is the URI of the authorization server that is the audience of the token:

      "claims": {
        "aud": "https://myapp.authentication.example.com"
      }

      If this property is an expression, its evaluation must yield an object of type Map<String, Object>. In the following example, overrideAudience is declared in the properties and then included in an expression in the claims declaration:

      {
        "properties": {
          "overrideAudience": {
            "aud": "https://myapp.authentication.example.com"
          }
        }
      }
    "claims": "${overrideAudience}"
    "jwtExpirationTimeout": duration, optional

    When private_key_jwt is used for authentication, this property specifies the duration for which the JWT is valid.

    Default: 1 minute

Example

The following example shows a client registration for AM. The client credentials are replaced with ****. In the actual configuration include the credentials and protect the configuration file, or obtain the credentials from the environment in a safe way:

{
    "name": "registration",
    "type": "ClientRegistration",
    "config": {
        "clientId": "****",
        "clientSecretId": "****",
        "issuer": {
            "type": "Issuer",
            "config": {
                "wellKnownEndpoint": "http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration"
            }
        },
        "secretsProvider": "mySystemAndEnvSecretStore",
        "scopes": [
          "openid",
          "profile",
          "email"
        ]
    }
}