Supported OpenID Connect Flows

OpenID Connect Single Sign-On (SSO) and Single Logout (SLO) flows supported by Expert.

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)

  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.

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
email 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;
claims-authorization-allowed-pattern

Allows users to enter the site.

claims-seat-pattern

Users Expert has created will have a Seated user for the site.

The user will be Seated every time they login as long as that key is applied.

For new sites, new accounts are Viewers instead of Contributors as they used to be set.

Set values for additional claims

Values can include:

  • Single value: foo
  • Email: [email:name@company.com]
  • Regex value: /[regex]@nice.com for all NiCE email users
  • Tenant ID: /tenantId:123-123-123 for all users with that tenant

Use a vertical pipe bar  | to add multiple users or groups to a claim.

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.

Expert does not connect to the OpenID Connect WebFinger, Provider Metadata, or Client Registration endpoints.