Supported OpenID Connect Flows
- Applies to:
- MindTouch (current)
This solution is custom-configured for each client by MindTouch Professional Services. Elements and labels may differ from what is documented.
OpenID Connect Single Sign-On (SSO) Flows
Expert supports the OpenID Connect 1.0 Authorization Code flow (specification). The Expert site performs the role of the relying party (RP) in this flow. The endpoints leveraged in this flow are Authorization, Token, UserInfo (Optional), and JSON Web Key Set (Optional)
- The RP redirects a user to the authorization server or identity provider (IdP) with an authorization code request and RP callback URL.
- The user authorizes the request and consents to the transfer of their data by entering their credentials or authenticating in whatever manner the server requires.
- The user is returned to the RP with the authorization code.
- The authorization code is sent by the RP to the IdP token endpoint to trade for access and identity tokens. The identity token is expected to be in JWT (JSON Web Token) format.
- The RP can use
client_secret_basic, client_secret_post, or client_secret_jwttoken endpoint authentication methods (specification). The default token endpoint authentication method isclient_secret_basic.
- The RP can use
- If an IdP JSON Web Key Set (JWKS) endpoint URL has been configured, the RP will request the latest JWKS for decoding and verifying the identity token. If a JWKS endpoint URL is not configured, the RP will use an optionally configured static JWKS.
- The RP will attempt to cache the JWKS using the
max-agevalue of the response'sCache-ControlHTTP header (specification). If aCache-ControlHTTP header is not provided, the JWKS will be cached for 24 hours. - If a cached JWKS fails to verify an identity token, the potentially stale JWKS will be discarded and the RP will request the latest JWKS from the JWKS endpoint URL. The RP will attempt a second verification with the new JWKS. If the second verification attempt fails, the user will not be provisioned and/or authenticated.
- The RP will attempt to cache the JWKS using the
- If the identity token does not contain all the claims required by the integration, and an IdP UserInfo endpoint URL has been configured, the RP will use the access token to request additional user identity data from the IdP UserInfo endpoint.
- If all required claims are satisfied, the user is provisioned and/or authenticated.
Expert allows a static JSON Web Key Set (JWKS) to be configured for an OpenID Connect integration. However, security best practices strongly recommend that a JWKS is rotated regularly, and published at an OpenID Connect JWKS endpoint URL (specification).
Supported Identity Token Verification Algorithms
Expert supports JSON Web Algorithms (specification) to decode and verify signed JWT identity tokens (JWS). The following asymmetric algorithms are supported: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, and PS512. These algorithms do not require Expert to receive the private signing key, thus removing the requirement to transfer the key and the potential leaking of it to untrusted parties.
Expert supports signed JWT identity tokens (JWS), but does not support encrypted JWT identity tokens (JWE).
Registered Identity Token Claims
Seven (7) JWT claims are defined as registered claims (specification). These claims are used to validate that the identity token is being used appropriately in the context of a single authentication session. Expert requires four (4) of these claims are present in all identity tokens received from identity providers, and highly recommends the presence of the others. Identity tokens that are missing any of the required claims will be rejected, and the user will not successfully authenticate.
| Claim | Description | Status |
|---|---|---|
| iss | A unique identifier for the identity provider that issued the identity token. This value is manually provided to Expert as a configuration requirement of the integration. | Required |
| sub | The subject of the identity token. This value is presumed to be the user's username, and is used to match any existing identity record in the Expert site's user pool. Expert expects the sub claim to correspond to an OpenID Connect public subject identifier type (specification). |
Required |
| aud | The intended audience of the identity token, presumed to be the relying party client ID value. This value is manually provided to Expert as a configuration requirement of the integration. | Required |
| exp | The expiration of the identity token. The Expert site will reject an identity token if its expiration timestamp is greater than the current system UTC timestamp. | Required |
| nbf | A timestamp value informing the Expert site to not to accept the identity token if the current system UTC timestamp is later than the claim value. To mitigate system clock skew, a grace period of 3 minutes is used when processing this claim. | Recommended |
| iat | A timestamp value informing the Expert site not the accept the identity token if the current system UTC timestamp is earlier than the claim value. To mitigate system clock skew, a grace period of 3 minutes is used when processing this claim. | Recommended |
| jti | A unique identifier for the identity token. This claim can be used to prevent replay attacks. The usage of this claim is currently under evaluation by Expert Engineering. | Ignored |
Standard Identity Token Claims
The Expert site looks for standard claims (specification) in the identity token or UserInfo endpoint response to build a profile of the authenticated user. These claims are all optional, however their inclusion improves the user experience.
| Claim | Description |
|---|---|
| The user's preferred email address. The email address is used when Expert site notifications are sent to the user. | |
| family_name | The user's last name. If the name claim is not present, this claim will be combined with the given_name claim to generate the user's display name. |
| given_name | The user's first name. If the name claim is not present, this claim will be combined with the family_name claim to generate the user's display name. |
| name | The user's full name to be used as the user's display name. |
Groups
If set, the user's group membership will be synchronized with the value of the claim. If a user is a member of any groups not listed in the attribute value, the user will be removed from those groups. The claim name is configurable and can be set to any incoming claim name. The claim value must be provided in a JSON array format:
{
"groups": ["foo", "bar", "baz"]
}
Additional Claims
The Expert site allows additional claims (specification) in the identity token of UserInfo endpoint response. These claims are stored as a JSON string and can be accessed programmatically using DekiScript.
// fetch the identity token claims as JSON text let json = user.properties["mindtouch.auth#claims"].text;
OpenID Connect Single Logout (SLO) Flows
Expert supports the OpenID Connect 1.0 Session Management RP-Initiated Logout flow (specification). The Expert site performs the role of the relying party (RP) in this flow. The endpoint leveraged in this flow is Session Management.
- The RP sends a user to the identity provider (IdP) with a logout request and RP callback URL
Expert does not connect to the OpenID Connect WebFinger, Provider Metadata, or Client Registration endpoints.