OAuth Metadata

The OAuth Authorization Server Metadata Specification, RFC 8414 is supported by the Curity Identity Server.

This means that a metadata endpoint can be enabled so that an OAuth client can obtain the information needed to interact with Curity, including its endpoint locations and authorization server capabilities.

However, the metadata endpoint is disabled by default. To enable it, inside the Token Service configuration, turn on the expose-metadata configuration.

Once enabled, a HTTP client can obtain the OAuth Server Metadata by making a request to https://your-server/.well-known/oauth-authorization-server/<issuer>, where the last path component, <issuer>, is the Token Service’s issuer ID (which is normally the path to the anonymous endpoint, but can be explicitly set by configuring an issuer-override on the Token Service).

Warning

Because of the way the metadata endpoint path must be constructed, there could be conflicts between different Token services, for example, if their anonymous endpoint path happens to be the same. In such case, Curity will log a warning and only one of the endpoints will become available.

This means that an OAuth client can discover everything it needs to self-configure (including the authorization_endpoint, token_endpoint, jwks_uri and many other useful parameters) after being informed of only the OAuth authorization server’s issuer identifier.

Listing 127 Example OAuth Metadata
    {
      "introspection_endpoint_auth_signing_alg_values_supported": [
        "PS384",
        "RS384",
        "ES256",
        "RS256",
        "EdDSA",
        "PS256",
        "PS512",
        "RS512"
      ],
      "request_parameter_supported": true,
      "pushed_authorization_request_endpoint": "https://localhost:8443/dev/oauth/authorize/par",
      "authorization_response_iss_parameter_supported": true,
      "claims_parameter_supported": true,
      "introspection_endpoint": "https://localhost:8443/introspection",
      "scopes_supported": [
        "address",
        "read",
        "admin_read",
        "phone",
        "openid",
        "profile",
        "urn:se:curity:scopes:admin:api",
        "admin_write",
        "write",
        "email"
      ],
      "issuer": "https://localhost:8443/dev/oauth/anonymous",
      "acr_values_supported": [
        "urn:se:curity:authentication:google:google1",
        "urn:se:curity:authentication:totp:totp",
        "urn:se:curity:authentication:html-form:phpass",
        "urn:se:curity:authentication:sms:sms2fa"
      ],
      "service_documentation": "https://localhost/developer-documentation-url",
      "authorization_endpoint": "https://localhost:8443/dev/oauth/authorize",
      "introspection_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic",
        "private_key_jwt"
      ],
      "require_pushed_authorization_requests": false,
      "claim_types_supported": [
        "normal"
      ],
      "token_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic",
        "private_key_jwt"
      ],
      "tls_client_certificate_bound_access_tokens": false,
      "response_modes_supported": [
        "fragment",
        "fragment.jwt",
        "jwt",
        "form_post",
        "query",
        "query.jwt",
        "form_post.jwt"
      ],
      "token_endpoint": "https://localhost:8443/dev/oauth/token",
      "response_types_supported": [
        "code",
        "code id_token",
        "code id_token token",
        "code token",
        "id_token",
        "id_token token",
        "token"
      ],
      "revocation_endpoint_auth_signing_alg_values_supported": [
        "PS384",
        "RS384",
        "ES256",
        "RS256",
        "EdDSA",
        "PS256",
        "PS512",
        "RS512"
      ],
      "revocation_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic",
        "private_key_jwt"
      ],
      "request_uri_parameter_supported": true,
      "grant_types_supported": [
        "refresh_token",
        "implicit",
        "client_credentials",
        "password",
        "authorization_code",
        "urn:ietf:params:oauth:grant-type:pre-authorized_code"
      ],
      "ui_locales_supported": [
        "sv",
        "pt",
        "en"
      ],
      "revocation_endpoint": "https://localhost:8443/revoke",
      "token_endpoint_auth_signing_alg_values_supported": [
        "PS384",
        "RS384",
        "ES256",
        "RS256",
        "EdDSA",
        "PS256",
        "PS512",
        "RS512"
      ],
      "require_request_uri_registration": true,
      "require_signed_request_object": false,
      "code_challenge_methods_supported": [
        "S256",
        "plain"
      ],
      "jwks_uri": "https://localhost:8443/dev/oauth/anonymous/jwks",
      "assisted_token_endpoint": "https://localhost:8443/assisted-token",
      "claims_locales_supported": [
        "sv",
        "pt",
        "en"
      ],
      "authorization_signing_alg_values_supported": [
        "RS256"
      ],
      "request_object_signing_alg_values_supported": [
        "RS256",
        "none"
      ],
      "prefix_scopes_supported": []
    }

Note

Not all OpenID Connect parameters are shown in the OAuth Metadata response, even if OpenID has been enabled in the Token Service. To retrieve the full OpenID metadata, use the OpenID Connect-specific endpoint which is discussed in the next section.

Normally, enabling OAuth metadata is as easy as enabling expose-metadata in the configuration. However, if there is more than one endpoint configured for each endpoint kind (e.g. more than one authorization_endpoint), then one must be selected explicit for each ambiguous endpoint kind.

All exposed endpoints may be explicitly selected, and their corresponding base URL may be overridden if necessary (the absolute URLs are normally resolved from the server’s own base URL configuration, or from the request if that’s not configured).

OpenID Connect Metadata

The OpenID Connect configuration can be used to enable the OpenID Connect metadata endpoint.

Enabling this endpoint requires a few conditions to be met in order for the metadata information to be consistent. The configuration will not validate if these conditions are not met:

  • The OAuth profile must have one and only one anonymous endpoint
  • An authorize endpoint must be defined
  • A token endpoint must be defined if the profile supports the client-credentials, code, resource-owner-password-credentials, or token-exchange capabilities
  • If there are more then one of any of the following kinds of endpoints, then which one should be exposed in the metadata must be configured: oauth-authorize, oauth-token, oauth-userinfo, oauth-assisted-token, oauth-revoke, oauth-introspect.

If all of these conditions are met, then the metadata can be obtained by requesting the subroute /.well-known/openid-configuration under the anonymous endpoint. For example, if the anonymous endpoint is configured to be ~, then this would be at /~/.well-known/openid-configuration on the host that is serving the OAuth profile’s anonymous endpoint.

If this endpoint were hosted on a service that used the HTTPS protocol, had a hostname of localhost and was listening on port 8443, then the metadata would be accessible at https://localhost:8443/~/.well-known/openid-configuration.

The metadata in this response is mostly defined by the OpenID Connect and OAuth metadata standards where applicable. The included metadata and its meaning is described in the following table:

OpenID Connect Metadata

OpenID Connect metadata fields that are returned depending on various configuration

Object Properties:
 
  • issuer (string) – The issuer ID. This will be the URL of the anonymous endpoint unless issuer-override has been set to some non-URL value.
  • introspection_endpoint (url) – If there is only one introspection endpoint defined in the profile, then the URL of this endpoint. If there are multiple, the URL of the one that is configured to be exposed. If no introspection endpoint is defined in the profile, this value will not be included in the response.
  • authorization_endpoint (url) – If there is only one authorization endpoint defined in the profile, then the URL of this endpoint. If there are multiple, the URL of the one that is configured to be exposed.
  • token_endpoint (url) – If there is only one token endpoint defined in the profile, then the URL of this endpoint. If there are multiple, the URL of the one that is configured to be exposed. If there is no token endpoint defined in the profile and the profile does not support the client-credentials, code, resource-owner-password-credentials, nor the token-exchange capabilities, then this value will be not be included in the response.
  • jwks_uri (url) – The URL of the JSON Web Key Set (JWKS). This will be the URL of the OAuth profile’s anonymous endpoint with jwks appended.
  • revocation_endpoint (url) – If there is only one revocation endpoint defined in the profile, then the URL of this endpoint. If there are multiple, the URL of the one that is configured to be exposed. If there is no revocation endpoint defined in the profile, then this value will be not be included in the response.
  • assisted_token_endpoint (url) – If there is only one assisted endpoint defined in the profile, then the URL of this endpoint. If there are multiple, the URL of the one that is configured to be exposed. If there is no assisted token endpoint defined in the profile and the profile does not support the assisted-token capabilities, then this value will be not be included in the response.
  • scopes_supported (string[]) – The scopes that the OAuth profile supports which always includes openid.
  • response_types_supported (string[]) –

    The response types that the OAuth profile supports. The elements of the array will be as summarized in the following table:

    Capability Enabled in the OAuth Profile JSON Array Values
    code
    • code
    • code id_token
    • code id_token token
    • id_token
    implicit
    • id_token
    • id_token token
    • token
    code and implicit
    • code token
    • code token id_token
    client-credentials token
    resource-owner-password-credentials token
  • response_modes_supported (string[]) – The response modes that the OAuth profile supports. If the code capability is enabled, the array will include query, and if the implicit capability is enabled, the array will also include fragment. If both of these capabilities are supported in the profile, this array will contain both of the associated values.
  • grant_types_supported (string[]) –

    The grant types or “flows” that are supported by the OAuth profile. The elements of the array will be as summarized in the following table:

    Capability Enabled in the OAuth Profile JSON Array Values
    code
    • authorization_code
    • refresh_token
    implicit
    • implicit
    resource-owner-password-credentials
    • password
    • refresh_token
    client-credentials client_credentials
    token-exchange https://curity.se/grant/accesstoken
    assisted-token https://curity.se/grant/assisted-token
    backchannel-authentication urn:openid:params:grant-type:ciba
  • acr_values_supported (string[]) – The ACRs of all authenticators in the authentication profile associated with the profile.
  • subject_types_supported (string[]) – An array containing the string value pairwise, and when pairwise subject identifiers are not required, will also contain the string value public.
  • id_token_signing_alg_values_supported (string[]) – A singleton array containing the string RS256.
  • token_endpoint_auth_methods_supported (string[]) – An array containing the strings client_secret_post and client_secret_basic which represents the authentication methods supported by the token endpoint.
  • revocation_endpoint_auth_methods_supported (string[]) – An array containing the strings client_secret_post and client_secret_basic which represents the authentication methods supported by the revocation endpoint.
  • claim_types_supported (string[]) – An array containing the single string value normal, meaning that only normal claims, as opposed to distributed claims, are supported. Distributed claims can be supported using token issuance procedures, but the Curity Security Token Server does not advertise support for this in the metadata.
  • ui_locales_supported (string[]) – An array containing the BCP47 formatted names of the locals installed in the the Curity Identity Server. If a new locale is added to the $IDSVR_HOME/usr/share/messages/overrides directory, this new locale will be added to the published metadata.
  • claims_locales_supported (string[]) – The same as ui_locales_supported. Claims may be localized into other languages using token issuance procedures, but these are not included in the metadata.
  • code_challenge_methods_supported (string[]) – If the code capability is configured for the OAuth profile, then the array will contain the elements S256 and plain; otherwise, this property will be excluded from the metadata. These values are defined by Proof Key for Code Exchange by OAuth Public Clients (PKCE).
  • service_documentation (url) – The URL where developers can find the documentation describing how to integrate with the service. This URL is the one set by the developer-documentation-url configuration setting.
  • registration_endpoint (url) – The URL where dynamic clients can submit their registration information to obtain a new client ID and secret. If dynamic client registration is not enabled for the profile, this value will not be included in the response.
  • registration_endpoint_auth_methods_supported (string[]) – The authentication methods that are supported by the dynamic client registration endpoint. The value will always be a singleton array containing the value Bearer, meaning a bearer access token that represents the user or client’s authorization of the caller. If dynamic client registration is not enabled for the profile, this value will not be included in the response.
  • op_policy_uri (url) – The policy URL where developers of dynamically registered clients can obtain the policy by which registration is governed.
  • op_tos_uri (url) – The URL of the terms of service that dynamic clients can show to users, so they are aware of the conditions under which they may use the OAuth server.
  • end_session_endpoint (url) – the URL that the RP can redirect the user to to request Logout
  • check_session_endpoint (url) – the URL that the RP can load in an IFrame to check the user’s SSO status with the OP, see Session Endpoint
  • frontchannel_logout_supported (boolean) – indicates whether front channel logout notification is supported
  • frontchannel_logout_session_supported (boolean) – indicates whether front channel logout notification from Curity can include the logged out sid as parameter to the logout uri
  • backchannel_logout_supported (boolean) – indicates whether back channel logout notification is supported
  • backchannel_logout_session_supported (boolean) – indicates whether back channel logout notification from Curity can include the logged out sid as claim in the Logout Token
  • backchannel_authentication_endpoint (url) – the URL used for initiating backchannel authentication
  • backchannel_token_delivery_modes_supported (string[]) – An array containing the string value poll
  • backchannel_authentication_request_signing_alg_values_supported (string[]) – A singleton array containing the string RS256.
  • id_token_encryption_alg_values_supported (string[]) – The key management algorithms for ID token encryption allowed by the OAuth profile. If encrypted ID tokens are not enabled this value will not be included in the response.
  • id_token_encryption_enc_values_supported (string[]) – The content encryption algorithms for ID token encryption allowed by the OAuth profile. If encrypted ID tokens are not enabled this value will not be included in the response.

An example of the OpenID Connect metadata is shown in Listing 128.

Listing 128 Example OpenID Connect Metadata
    {
      "introspection_endpoint": "https://localhost:8443/introspection",
      "scopes_supported": [
        "read",
        "admin_read",
        "openid",
        "profile",
        "admin_write",
        "write",
        "email"
      ],
      "issuer": "https://spruce:8443/dev/oauth/anonymous",
      "acr_values_supported": [
        "urn:se:curity:authentication:google:google1",
        "urn:se:curity:authentication:sms:sms2fa",
        "urn:se:curity:authentication:sms:sms1",
        "urn:se:curity:authentication:html-form:html2fa",
        "loa1"
      ],
      "authorization_endpoint": "https://localhost:8443/dev/oauth/authorize",
      "introspection_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic"
      ],
      "service_documentation": "https://localhost/developer-documentation-url",
      "claim_types_supported": [
        "normal"
      ],
      "token_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic"
      ],
      "response_modes_supported": [
        "fragment",
        "query"
      ],
      "token_endpoint": "https://localhost:8443/dev/oauth/token",
      "response_types_supported": [
        "code",
        "id_token",
        "token"
      ],
      "revocation_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic"
      ],
      "grant_types_supported": [
        "refresh_token",
        "implicit",
        "client_credentials",
        "password",
        "https://curity.se/grant/accesstoken",
        "authorization_code",
        "urn:openid:params:grant-type:ciba",
        "https://curity.se/grant/assisted-token"
      ],
      "backchannel_authentication_endpoint": "https://localhost:8443/bc-auth",
      "backchannel_token_delivery_modes_supported": [
        "poll"
      ],
      "backchannel_authentication_request_signing_alg_values_supported": [
        "RS256"
      ],
      "ui_locales_supported": [
        "sv",
        "en"
      ],
      "revocation_endpoint": "https://localhost:8443/revoke",
      "userinfo_endpoint": "https://localhost:8443/dev/oauth/userinfo",
      "code_challenge_methods_supported": [
        "S256",
        "plain"
      ],
      "jwks_uri": "https://localhost:8443/dev/oauth/anonymous/jwks",
      "subject_types_supported": [
        "public"
      ],
      "id_token_signing_alg_values_supported": [
        "S256"
      ],
      "assisted_token_endpoint": "https://localhost:8443/assisted-token",
      "claims_locales_supported": [
        "sv",
        "en"
      ]
    }

OpenID Connect Metadata contains all of the parameters included in the OAuth metadata, but with several more parameters added, such as userinfo_endpoint and backchannel_authentication_endpoint which are OpenID-specific features.

Warning

It is not possible to configure both OAuth metadata’s and OpenID metadata’s jwks-uri-override at the same time. Only one of them must be configured because only one JWKS URI should exist - whichever was configured, or <oidc-metadata-endpoint>/jwks by default. Trying to configure both results in a configuration validation error.