This solution is custom-configured for each client by MindTouch Professional Services. Elements and labels may differ from what is documented.
This solution became generally available April 5, 2019 and is only implemented by request for each MindTouch site.
OpenID Connect single sign-on (SSO) flows
MindTouch supports the OpenID Connect 1.0 Authorization Code flow (specification). The MindTouch 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 RP uses the
client_secret_basicclient authentication method (specification).
- The RP uses the
- 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 to trade for access and identity tokens. The identity token is expected to be in JWT (JSON Web Token) format.
- 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's
Cache-ControlHTTP header (specification). If a
Cache-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.
MindTouch 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 algorithims
MindTouch supports JSON Web Algorithims (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 algorithims do not require MindTouch to receive the private signing key, thus removing the requirement to transfer the key and the potential leaking of it to untrusted parties.
MindTouch 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. MindTouch 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.
|iss||A unique identifier for the identity provider that issued the identity token. This value is manually provided to MindTouch 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 MindTouch site's user pool. MindTouch expects the
|aud||The intended audience of the identity token, presumed to be the relying party client ID value. This value is manually provided to MindTouch as a configuration requirement of the integration.||Required|
|exp||The expiration of the identity token. The MindTouch site will reject an identity token if it's expiration timestamp is greater than the current system UTC timestamp.||Required|
|nbf||A timestamp value informing the MindTouch 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 MindTouch 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 MindTouch Engineering.||Ignored|
Standard identity token claims
The MindTouch 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.
|The user's preferred email address. The email address is used when MindTouch 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.|
The MindTouch 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
MindTouch supports the OpenID Connect 1.0 Session Management RP-Initiated Logout flow (specification). The MindTouch 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
MindTouch does not connect to the OpenID Connect WebFinger, Provider Metadata, or Client Registration endpoints.