The OpenID Connect Discovery Document

The discovery document (also referred to as the "well-known endpoint") is a set of OpenID Connect values that can be retrieved by OIDC clients; it’s the discovery document that enables OIDC clients to configure themselves in order to be able to access your implementation of Hosted Login. A client that connects to your discovery document can easily do such things as:
  • Identify the claimsand grant types that you support.
  • Retrieve the URLs of your introspection server and your JSON Web Keys.
  • Determine which PKCE(Proof Key for Code Exchange) challenge methods you support.

Best of all, this can be done automatically, without requiring anyone to configure these values into the client.

As if that wasn’t enough, OIDC clients can also find discovery documents on their own. Your well-known endpoint can always be reached by adding the string value /.well-known/openid-configuration to the end of your Hosted Login issuer URI. For example, if your issuer URL is https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login then your well-known endpoint will be found here:
https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/.well-known/openid-configuration
Note: Your issuer URL (as well as the other URLs included on your discovery document) are generated for you by Akamai. By default, that URL includes the default Hosted Login URL (https://v1.api.us.janrain.com) plus your unique customer ID (for example, 00000000-0000-0000-0000-000000000000). If you prefer, however, you can use a custom issuer URL similar to this:
https://documentation.akamai.com/login

For more information on using a custom domain name for Hosted Login, contact your Akamai representative.

You can access the discovery document page simply by entering the URL for the well-known endpoint or by using an API call to return discovery document values in JSON format. For example, here’s a Curl command for returning the discovery document:
curl \
 https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/.well-known/openid-configuration

Regardless of the method you choose, here’s the sort of information you’ll get back in return:

{
    "issuer": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login",
    "authorization_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/
authorize",
    "token_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token",
    "introspection_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/
token/introspect",
    "revocation_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/token/
revoke",
    "userinfo_endpoint": "https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/profiles/oidc/
userinfo",
    "jwks_uri": "https://v1.api.us.janrain.com/00000000-0000-o000-0000-000000000000/login/jwk",
    "response_types_supported": [
        "code"
    ],
    "subject_types_supported": [
        "public"
    ],
   "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "grant_types_supported": [
        "authorization_code",
        "refresh_token"
    ],
   "token_endpoint_auth_methods_supported": [
        "client_secret_basic",
        "client_secret_post"
    ],
    "scopes_supported": [
        "openid",
        "profile",
        "email",
        "address",
        "phone"
    ],
    "claims_supported": [
        "sub",
        "iss",
        "auth_time",
        "acr",
        "name",
        "given_name",
        "address",
        "family_name",
        "middle_name",
        "preferred_username",
        "gender",
        "birthdate",
        "updated_at",
        "phone_number",
        "phone_number_verified",
        "email",
        "email_verified"
    ],
   "code_challenge_methods_supported": [
        "S256"
    ]
}
We thought someone might ask that: what do things like code_challenge_methods_supported and id_token_signing_alg_values_supported actually mean? To help answer those questions, the following is a list of the endpoints and configuration settings included on the typical Hosted Login discovery document.
Note: ll organizations that subscribe to Hosted Login get the same discovery document (except, of course, for their endpoint URLs). This is true even if you specify custom claims in one of your token policies. The discovery document only lists the standard claims supported by Hosted Login; it will not list any custom claims you define elsewhere.

Hosted Login Endpoints

issuer

The base URL for your Hosted Login implementation. And here’s a tip: any time you see the iss claim in a token, the value of that claim will be the issuer URL.

authorization_endpoint

Endpoint that validates all authorization requests. If a request is valid (for example, if it includes an authorized OIDC client, among other requirements) the user is then redirected to the login page. At the login page, the user logs on and, if successfully authenticated, is given an authorization code that can be exchanged for an access token. The latter exchange takes place at the token endpoint.

token_endpoint

URL of the token endpoint. After a client has received an authorization code, that code is presented to the token endpoint and exchanged for an identity token, an access token, and a refresh token.

introspection_endpoint

URL of the authorization server’s introspection endpoint. By default, access tokens and refresh tokens are “opaque” to clients. For example, a typical access token looks like this:
03v-eeodppPrrHXXIx56pRLyDBaOldDxqEwI59MFCFGVuSkLRapzgmfwmEHyKWle

Although that looks fairly simple (albeit extremely unreadable), an access is actually accompanied by a large amount of metadata that specifies everything from when the token expires to the scopes that the token holder should have access to. That’s good, except that resource servers are typically not equipped to decipher tokens and to retrieve this metadata; instead, resource servers usually contact the introspection endpoint to determine whether a token is valid and whether access to a specific resource should be granted.

revocation_endpoint

URL of the revocation endpoint, the endpoint used to revoke access or refresh tokens issued by the authorization server. After a token has been revoked it can no longer be used: access tokens can no longer be presented when a user requests access to a resource, and refresh tokens can no longer be used to request new access tokens.

The revocation endpoint enables clients to do such things as invalidate tokens any time a user logs out or any time a user uninstalls the application that requested the token. Invalidating tokens helps minimize the problems that surround “abandoned” tokens: tokens that are still valid but that the user is unaware of. If tokens are deleted at logoff time you reduce the chances of a valid token somehow falling into malicious hands.

userinfo_endpoint

URL of the user info endpoint, which returns user profile information to a client. Keep in mind that the user info endpoint returns only the information that has been requested: if you only request the user’s email address you will not get back their telephone number as well. In addition, and depending on how your system has been configured, the endpoint will only return information that the user has given consent to make available to specific requests.

Currently the user info endpoint is the only protected resource managed by Hosted Login.

Configuration Settings

response_types_supported

Specifies the way the authorization server responds after a user successfully authenticates. For its initial release, Hosted Login only supports the code response type: after a successful login, the user is given an authorization code. That code can then be exchanged for an access token, a refresh token, and an identity token.

subject_types_supported

JSON array containing a list of the supported Subject Identifier types. Currently Hosted Login only supports the public type, in which a user (subject) is issued a single unique identifier (the Akamai Identity Cloud UUID). The user then employs this identity on all of your clients; among other things, this enables you to easily keep track of users regardless of which client they might be using.

id_token_signing_alg_values_supported

JSON array consisting of all the JSON Web Signature algorithms that can be used for signing JSON Web Tokens. Hosted Login supports currently one signing algorithm: RS256.

grant_types_supported

Specifies the different ways that a client can be granted an access token and, as a result, can be given access to specific resources. Hosted Login supports two grant types:
  • authorization_code – After authentication, the client is given an authorization code. That code can then be exchanged for an access token.
  • refresh_token – Before an access token expires (by default, access tokens are only valid for one hour), a refresh token can be used to obtain a new access token.

token_endpoint_auth_methods_supported

JSON array containing a list of client authentication methods supported by the token endpoint. Hosted Login supports the following authentication methods:
  • client_secret_post – Authentication method in which the client sends authentication information as part of the request body in an HTTP POST.
  • client_secret_basic – Authentication method which employs the HTTP Basic Authentication Scheme. In this scheme (which should only be used on a secure connection), the client passes a user ID and password to the server as part of an Authorization header.

scopes_supported

JSON array containing a list of the scopes that the authorization server supports. Scopes are a collection of claims (for Hosted Login, each claim typically represents one piece of user information, such as the user’s first name or cell phone number). For example, you could request the following individual claims from a user profile:
  • name
  • given_name
  • family_name
  • middle_name
  • preferred_username
  • gender
  • birthdate
  • updated_at

Alternatively, you could request the profile scope, which includes each of the preceding claims.

Hosted Login does not support the ability to create custom scopes.

claims_supported

A list of the claims supported by this authorization server. For Hosted Login, each claim represents one piece of user information, such as the user’s first name or cell phone number. In addition to the default claims, Hosted Login supports the ability to collect custom claims; see OpenID Connect Scopes and Claims for more information.

code_challenge_methods_supported

JSON array containing a list of Proof Key for Code Exchange (PKCE) code challenge methods supported by this authorization server. With PKCE, a client cannot request authentication until it creates a unique string value (the code_verifier), which is hashed to create a code_challenge. The code_challenge and hashing algorithm are then sent to the authorization server along with the request for authentication.

Assuming the user authenticates successfully, the server sends an authorization code to the client and retains the code_challenge and hashing method associated with that code. When the client tries to exchange the authorization code for an access token, that client must also present the code_verifier. The server then uses the verifier and the hashing method to recreate the code_challenge. If the recreated value does not match the value of the code_challenge sent as part of the authorization request the request for an access token will be denied.
Note: Note. Got all that? If not see, the article Authorization Code + PKCE for Mobile Apps for more information.

Hosted Login only supports the S256 code challenge method (also referred to as the SHA-256 or Secure Hash Algorithm).