Discovery document

Read OneiD's OpenID Connect discovery document field by field and know which advertised options to use.

View as Markdown

OneiD publishes an OpenID Connect discovery document at https://YOUR_ONEID/.well-known/openid-configuration. Point your library at your OneiD address and it reads the endpoints, keys and supported features from this document. This page explains each field and the few values you should not rely on.

The document

GET /.well-known/openid-configuration HTTP/1.1
Host: YOUR_ONEID
{
  "issuer": "https://YOUR_ONEID/",
  "authorization_endpoint": "https://YOUR_ONEID/connect/authorize",
  "token_endpoint": "https://YOUR_ONEID/connect/token",
  "introspection_endpoint": "https://YOUR_ONEID/connect/introspect",
  "end_session_endpoint": "https://YOUR_ONEID/connect/logout",
  "revocation_endpoint": "https://YOUR_ONEID/connect/revoke",
  "userinfo_endpoint": "https://YOUR_ONEID/connect/userinfo",
  "jwks_uri": "https://YOUR_ONEID/.well-known/jwks",
  "grant_types_supported": ["authorization_code", "client_credentials", "refresh_token"],
  "response_types_supported": ["code"],
  "response_modes_supported": ["form_post", "fragment", "query"],
  "scopes_supported": [
    "openid", "offline_access", "profile", "email", "phone", "roles",
    "admin_api", "admin_api_readonly", "admin_console_webhooks"
  ],
  "claims_supported": [
    "aud", "exp", "iat", "iss", "sub", "name", "given_name", "family_name",
    "preferred_username", "email", "email_verified", "phone_number",
    "phone_number_verified", "updated_at", "auth_time", "amr", "acr", "role", "idp"
  ],
  "id_token_signing_alg_values_supported": ["RS256"],
  "code_challenge_methods_supported": ["plain", "S256"],
  "subject_types_supported": ["public"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "private_key_jwt", "client_secret_basic"],
  "introspection_endpoint_auth_methods_supported": ["client_secret_post", "private_key_jwt", "client_secret_basic"],
  "revocation_endpoint_auth_methods_supported": ["client_secret_post", "private_key_jwt", "client_secret_basic"],
  "claims_parameter_supported": true,
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "authorization_response_iss_parameter_supported": true,
  "acr_values_supported": ["urn:oltin:ac:pwd", "urn:oltin:ac:mfa", "urn:oltin:ac:external"]
}

Fields

Issuer and endpoints

Field Value on OneiD Meaning
issuer https://YOUR_ONEID/ The issuer identifier. It ends with a slash. The iss claim in every token and the iss parameter in authorisation responses carry the same value.
authorization_endpoint https://YOUR_ONEID/connect/authorize Where the browser starts a sign-in.
token_endpoint https://YOUR_ONEID/connect/token Where clients exchange codes, refresh tokens and client credentials for tokens.
userinfo_endpoint https://YOUR_ONEID/connect/userinfo Returns claims about the user for a user access token.
introspection_endpoint https://YOUR_ONEID/connect/introspect Token introspection for confidential clients.
revocation_endpoint https://YOUR_ONEID/connect/revoke Revokes refresh tokens and access tokens.
end_session_endpoint https://YOUR_ONEID/connect/logout RP-initiated sign-out.
jwks_uri https://YOUR_ONEID/.well-known/jwks The public signing keys.

Details of each endpoint are in Endpoints.

Warning If your library compares the issuer exactly, use the issuer value from discovery, including the trailing slash. https://YOUR_ONEID without the slash does not match.

Flows

Field Value on OneiD Meaning
grant_types_supported authorization_code, client_credentials, refresh_token The grants OneiD issues tokens for. Each client is allowed only the grants an administrator set for it.
response_types_supported code Only the authorization code flow. No implicit or hybrid flow.
response_modes_supported form_post, fragment, query How the authorisation response is returned. Use query (the default) or form_post.
code_challenge_methods_supported plain, S256 PKCE methods. Always use S256.
authorization_response_iss_parameter_supported true Authorisation responses include an iss parameter (RFC 9207). Check that it equals the issuer.

Note fragment is listed but is not recommended or tested with OneiD. Use query or form_post.

Warning plain is listed in code_challenge_methods_supported. Do not use it. Send code_challenge_method=S256.

Scopes and claims

Field Value on OneiD Meaning
scopes_supported openid, offline_access, profile, email, phone, roles, admin_api, admin_api_readonly, admin_console_webhooks The identity scopes and OneiD’s own administration scopes. Do not use the administration scopes in your applications. API scopes that your administrator creates, such as orders.read, may not appear here; ask your OneiD administrator which API scopes exist.
claims_supported aud, exp, iat, iss, sub, name, given_name, family_name, preferred_username, email, email_verified, phone_number, phone_number_verified, updated_at, auth_time, amr, acr, role, idp Claims OneiD can issue. Which ones you receive depends on the scopes granted. See Claims.
claims_parameter_supported true The claims request parameter is read for the id_token and userinfo members.
subject_types_supported public Each user has the same sub for every client.
acr_values_supported urn:oltin:ac:pwd, urn:oltin:ac:mfa, urn:oltin:ac:external The values the acr claim in the ID token can take. Sending acr_values in a request has no effect.

Signing and client authentication

Field Value on OneiD Meaning
id_token_signing_alg_values_supported RS256 ID tokens are signed with RS256. Access tokens use the same algorithm.
token_endpoint_auth_methods_supported client_secret_post, private_key_jwt, client_secret_basic How confidential clients authenticate at the token endpoint. Use client_secret_basic; client_secret_post is also accepted.
introspection_endpoint_auth_methods_supported Same as above Client authentication at the introspection endpoint.
revocation_endpoint_auth_methods_supported Same as above Client authentication at the revocation endpoint.

Not supported private_key_jwt is listed, but there is no way to register a client’s public key, so it cannot be used. Clients authenticate with a client secret. Mutual TLS client authentication is not supported.

Request objects

Field Value on OneiD Meaning
request_parameter_supported false Signed request objects in a request parameter are not accepted. OneiD answers with request_not_supported.
request_uri_parameter_supported false request_uri is not accepted. OneiD answers with request_uri_not_supported.

Fields that are absent

The document has no registration_endpoint, device_authorization_endpoint, pushed_authorization_request_endpoint, check_session_iframe, frontchannel_logout_supported or backchannel_logout_supported. OneiD does not offer these features. See Standards support.

Caching

  • Fetch the document once when your application starts, and keep it in memory. Do not fetch it on every request.
  • Refresh it from time to time, for example once a day, and when calls start failing in a way that suggests a changed configuration.
  • Fetch the JWKS separately and refresh it when a token carries a kid you do not know. Mainstream OpenID Connect libraries do both for you.
  • Discovery and JWKS answer requests from any origin, so a browser application can fetch them directly.

Learn more