TrainingSupportCommunity

Discovery document

Suggest Edits

Also referred to as the "well-known endpoint," the discovery document 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 claims and grant types that you support.
  • Retrieve the URLs of your introspection server and your JSON web keys.
  • Determine which PKCE challenge methods you support.

Best of all, this can be done automatically, without requiring anyone to configure these values for 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


📘

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/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login",
  "authorization_endpoint": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize",
  "token_endpoint": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token",
  "introspection_endpoint": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token/introspect",
  "revocation_endpoint": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token/revoke",
  "userinfo_endpoint": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/profiles/oidc/userinfo",
  "jwks_uri": "https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/jwk",
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "response_modes_supported": [
    "query",
    "fragment",
    "form_post"
  ],
  "response_types_supported": [
    "code",
    "id_token",
    "token",
    "none",
    "code id_token",
    "code token",
    "id_token token",
    "code id_token token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "implicit",
    "password",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:token-exchange"
  ],
  "acr_values_supported": [
    "0",
    "urn:akamai-ic:nist:800-63-3:aal:1",
    "urn:akamai-ic:nist:800-63-3:aal:2"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "address",
    "phone"
  ],
  "claims_parameter_supported": true,
  "claims_supported": [
    "sub",
    "iss",
    "auth_time",
    "given_name",
    "address",
    "family_name",
    "middle_name",
    "preferred_username",
    "gender",
    "birthdate",
    "updated_at",
    "phone_number",
    "phone_number_verified",
    "email",
    "email_verified"
  ],
  "claim_types_supported": [
    "normal",
    "aggregated"
  ],
  "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.


📘

All 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. A typical issuer URL will look similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login


authorization_endpoint

Endpoint for validating authorization requests. If a request is valid the user is then redirected to the login page. At the login page, the user logs on and, depending on the grant type in use, is given an authorization code that can be exchanged for an access token, a refresh token, and an identity token. That exchange takes place at the token endpoint.

A typical authorization endpoint URL looks similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize


token_endpoint

URL of the token endpoint. When using an authorization code grant (the most-commonly used grant type), the client must visit the token endpoint and exchange an authorization code for an identity token, an access token, and a refresh token. In addition, the token endpoint is also used to redeem refresh tokens for new access tokens.

A typical token endpoint URL looks like the following:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token


introspection_endpoint

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

03v-eeodppPrrHXXIx56pRLyDBaOldDxqEwI59MFCFGVuSkLRapzgmfwmEHyKWle

Although that might look like a random string of characters (or just plain gibberish), an access token actually includes a large amount of metadata that specifies everything from when the token expires to the scopes that the token holder should be given access to. That’s the good news? The bad news? Generally speaking, resource servers typically can’t decipher tokens and retrieve this metadata. Instead, those servers must contact the introspection endpoint to determine whether a token is valid and whether access to a specific resource should be granted. If a token is valid the token metadata is returned. If a token is invalid you’ll be told just that: the token is invalid. (For security reasons, you won’t know why the token is invalid; for example, because the token has expired, because it came from a different issuer, because it was intended for a different user, etc.)

A typical introspection URL looks like this one:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token/introspect


revocation_endpoint

URL of the revocation endpoint, the endpoint used to revoke access tokens or refresh tokens. After a token has been revoked it can no longer be used: access tokens can’t be used to request access to a resource, and refresh tokens can’t be used to request new access tokens.

📘

You can only revoke access and refresh tokens; identity tokens can’t be revoked. In addition, if you revoke an access token you’ll also revoke its corresponding refresh token, and vice-versa.

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.

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 inherent in “abandoned” tokens: tokens that are still valid but that the user has no knowledge of. By deleting tokens at logoff time you reduce the chances of a valid token somehow falling into malicious hands.

A typical revocation URL looks like the following

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token/revoke

user_info_endpoint

URL of the userinfo endpoint, the endpoint that facilitates returning user profile information to a client. The information you can request from the userinfo endpoint depends on the scopes and claims included in your authorization request: for example, if you didn’t request the user’s email address in your authorization request then any attempt to retrieve this information from the userinfo endpoint will come up empty.

A typical userinfo URL looks similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/profiles/oidc/userinfo


jwks_uri

URL of your JSON Web Key Set. The Web Key Set is a collection of JSON Web Keys, a standard method for representing cryptographic keys in a JSON structure. For Hosted Login, that collection consists of the public keys used to verify the signatures of the identity tokens issued by the authorization server.

A typical JSON Web Key URL looks like this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/jwk


Configuration Settings

request_parameter_supported

When true, allows authorization request parameters to be sent as a self-contained JSON Web Token (JWT). Hosted Login does not support sending request parameters in a JWT.


request_uri_parameter_supported

When true, enables you to provide a URL to the request parameter instead of including the parameter's JSON Web Token in your authorization request. Because Hosted Login doesn't support the request parameter this will always be false.


response_modes_supported

Specifies the method used to transmit the response from the authorization server following a successful authentication. Hosted Login supports the following response modes:

  • query. The server response is sent as query parameters in the redirect URI
  • fragment. The server response is sent as URI fragments in the redirect URI. Unlike query parameters, URI fragments are not passed along when the client is redirected.
  • form_post. The server response is encoded as application/x-www-form-urlencoded body parameters and is transmitted to the client by using the HTTP POST method. This is the most-secure type of response.

response_types_supported

Specifies the items returned by the authorization server following a successful authentication. Hosted Login supports following response types:

  • code. The authorization server returns an authorization code that be exchanged at the token endpoint for an access token, a refresh token, and an identity token.
  • id_token. The authorization server returns an identity token. The token endpoint is not part of this transaction.
  • token. The authorization server returns an access token. The token endpoint is not part of this transaction.
  • code id_token. The authorization server returns both an authorization code and an identity token. The token endpoint is not part of this transaction.
  • code token. The authorization server returns an authorization code and an access token. The authorization code can be exchanged at the token endpoint for a second access token, an identity token, and a refresh token.
  • id_token token. The authorization server returns an identity token and an access token (but no refresh token). The token endpoint is not part of this transaction.
  • code id_token token. The authorization server returns an authorization code, an identity token, and an access token. The authorization code can be exchanged at the token endpoint for a second access token, a second identity token, and a refresh token.

subject_types_supported

JSON array containing the supported Subject Identifier types. A Subject Identifier is a unique (and never-reassigned) value that identifies a user. Hosted Login employs the user’s UUID (Universally Unique Identifier) as the Subject Identifier. The Subject Identifier is referenced in the access and identity tokens (and the userinfo endpoint) as the value of the sub claim.

Hosted Login supports the following subject types:

  • public. A user is issued a single unique identifier (an Identity Cloud UUID), then employs this same identity on all your Identity Cloud clients.

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 (JWTs). Hosted Login supports the following signing algorithms:

  • RS256 (RSA Signature with SHA-256). An asymmetric algorithm that utilizes a private key/public key approach to a signing JWTS: the private key is used to sign the tokens and the public key is used to validate those signatures.

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 the following grant types:

  • authorization_code. After authentication, the client is given an authorization code that code can be exchanged at the token endpoint for an access token, a refresh token, and an identity token.

  • client_credentials. Enables a user to obtain an access token by supplying the credentials of a confidential client rather than their individual user credentials. In Hosted Login this grant type is used to obtain the configuration tokens that provide access to the OpenID Connect Configuration APIs.

  • implicit. Enables the authorization server to return access tokens and/or identity token, and without requiring the client to visit the token endpoint.

  • refresh_token– Before an access token expires (by default, access tokens are only valid for one hour), a refresh token can be presented to the token point and a new access token can be issued.


acr_values_supported

JSON array containing the “levels of authentication assurance” supported by Hosted Login. These levels measure how confident you are that the user is the person they claim to be and, as a result, whether that user should have access to the requested resources.

Hosted Login supports the following acr (Authentication Context Class Reference) values; these values correspond to different levels (and types) of assurance. Note that the following values are all modeled on the National Institute for Standard and Technology’s (NIST) digital identity design guidelines:

  • 0. Indicates that the user was not actively authenticated. For example, instead of logging on with an email address and password, the user might have resumed an existing Hosted Login session.
  • urn:akamai-ic:nist:800-63-3:aal:1. Corresponds to NIST Authenticator Assurance Level 1.
  • urn:akamai-ic:nist:800-63-3:aal:2. Corresponds to NIST Authenticator Assurance Level 2.

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.


claims_parameter_supported

If set to true, indicates that the claims parameter can be included in an authorization request. Hosted Login supports the claims parameter.


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 supports the following scopes:

  • openid. Indicates that you’re making an OpenID Connect request. This scope must appear in all your authorization requests.
  • profile. Includes the name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at claims.
  • email. Includes the email and email_verified claims.
  • address. Includes the address claim.
  • phone. Includes the phone_number and phone_number_verified claims.

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


claims_supported

OpenID Connect claims supported by the 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 Scopes and claims for more information.

Hosted Login supports the following OpenID Connect claims:

  • sub. Unique identifier for the user. For Hosted Login, the sub is the user’s Hosted Login UUID (Universally Unique Identifier).
  • iss. URL of your Hosted Login login page.
  • auth_time. Date and time that the user was last authenticated.
  • given_name. User’s first name.
  • address. User’s mailing address.
  • family_name. User’s last name.
  • middle_name. User’s middle name.
  • preferred_username. Name by which the user prefers to be referred.
  • gender. User’s gender.
  • birthdate. User’s date of birth.
  • updated_at. Date and time that the user’s user profile was last updated.
  • phone_number. User’s mobile device number.
  • phone_number_verified. Date and time that the user’s mobile device number was verified.
  • email. User’s email address.
  • email_verified. Date and time that the user’s email address was verified.

claim_types_supported

Specifies how claims can be formatted and referenced in an authorization request. Hosted Login supports two claim types:

  • normal. Claims are individually referenced by using JSON.
  • aggregated. Claims from different sources can be combined into a JSON Web Token. That JWT is then referenced by the claims parameter.

code_challenge_methods_supported

JSON array containing the Proof Key for Code Exchange (PKCE) code challenge methods supported by the authorization server. With PKCE, a client cannot request authentication until it creates a unique string value (the code_verifier); that code_verifier is then 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 exchanges the authorization code for an access token, the 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 then the request for an access token is denied.

📘

Note. Got all that? If not see, the article Authorization code + PKCE grant type for more information.

Hosted Login supports the following code challenge method:

  • S256 (SHA-256 of Secure Hash Algorithm). The S256 algorithm creates a fixed-size, 32-byte hash for each code challenge.

Updated 8 months ago