Skip to main content
MindTouch Success Center

Supported OpenID Connect Flows

OpenID Connect single sign-on (SSO) and single logout (SLO) flows supported by MindTouch.

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)

  1. The RP redirects a user to the authorization server or identity provider (IdP) with an authorization code request and RP callback URL.
  2. 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.
  3. The user is returned to the RP with the authorization code.
  4. 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.
    1. The RP can use client_secret_basic, client_secret_post, or client_secret_jwt token endpoint authentication methods (specification). The default token endpoint authentication method is client_secret_basic.
  5. 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.
    1. The RP will attempt to cache the JWKS using the max-age value of the response's Cache-Control HTTP header (specification). If a Cache-Control HTTP header is not provided, the JWKS will be cached for 24 hours.
    2. 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.
  6. 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.
  7. 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.

Claim Description Status
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 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 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.

Claim Description
email 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.

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 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.

  • Was this article helpful?