Standard SSO Integration (OIDC)

Outlining Webassessor Single-Sign-On (SSO) integration using OpenID Connect (OIDC), as an alternative to SAML.

This document outlines Webassessor Single-Sign-On (SSO) integration using OpenID Connect (OIDC). Kryterion, Inc. offers OIDC alongside SAML.

Before implementing OIDC into Webassessor it is important to understand that OIDC, like SAML, has two parties:

• OpenID Provider (IdP): Always the Client.

• Relying Party (RP): Always Webassessor (the Webassessor SSO Service).

Please note: Webassessor signs in with the Authorization Code flow using PKCE (S256) and validates the signed ID token against the IdP's published signing keys (JWKS). Please ensure your IdP supports both before proceeding.

References

[OIDC]: OpenID Connect Core 1.0 specification: https://openid.net/specs/openid-connect-core-1_0.html

Pre-requisites

• The client must have an OpenID Connect compliant IdP (in-house, or a third-party IdP such as Okta or Auth0) that publishes an OIDC discovery document.

• The client must be created in the Webassessor system as an entity and region with a brand, since region and brand are part of the SSO call.

• An OIDC SSO configuration must be created for the client's region by Kryterion (Step 3 below). The configuration has a provider name that is unique to each client.

• Webassessor requests the following from the IdP: an ID token that carries a stable sub claim and a login identifier (see "How Webassessor identifies the user"). If the IdP does not return an email claim and no Login Claim Name is configured, the login is rejected.

Integration Points and Flows

1. The client sends the user to the Webassessor OIDC initiation link (Step 4).

2. Webassessor redirects the browser to the IdP's authorization endpoint (from the discovery document) with PKCE. Webassessor always sends prompt=login, so the IdP challenges the user to authenticate on every sign-in even when the IdP session is still active.

3. The IdP authenticates the user and redirects back to the Webassessor SSO Service callback with an authorization code. Webassessor exchanges the code for tokens.

4. Webassessor only needs the ID token, so as soon as the sign-in succeeds it revokes the access token and refresh token the IdP issued (RFC 7009), provided the IdP publishes a revocation endpoint. This is best-effort: if the IdP has no revocation endpoint, or the call fails, the sign-in continues normally.

5. Webassessor validates the ID token: signature (IdP JWKS), issuer, subject present, audience contains the client ID, azp (required and matching when the audience has more than one value), expiry, issued-at, and nonce binding. A clock skew tolerance of 60 seconds applies to expiry and issued-at. If validation fails, the user is sent to the login page.

6. Webassessor matches the ID token to a Webassessor user (see "How Webassessor identifies the user"), optionally creating one (JIT, see below), and then sends the user to the candidate or admin landing page according to the user's role.

Implementation Steps

Step 1: Client provides the OIDC IdP details

Before the integration can be set up, Kryterion needs the following from the client. Kryterion registers these in the client's OIDC SSO configuration.

Step 2: Client adds Webassessor information into their system

1. Redirect URI (callback): register this in the client's IdP as an allowed callback (redirect) URI. It must exactly match the Redirect URI stored in the client's Webassessor OIDC configuration. There is no provider name in the path.

   1. Sandbox: https://sb01.webassessor.com/SsoService/oidc/callback

   2. Production: https://www.webassessor.com/SsoService/oidc/callback

2. Logout URL: Webassessor always sends this as the post_logout_redirect_uri when it logs the user out of the IdP. If the IdP validates post-logout redirect URLs, register it as an allowed logout URL.

   1. Sandbox: https://sb01.webassessor.com/SsoService/sso/oidcLogoutComplete

   2. Production: https://www.webassessor.com/SsoService/sso/oidcLogoutComplete

3. Webassessor SSO Service base URL:

   1. Sandbox: https://sb01.webassessor.com/SsoService/

   2. Production: https://www.webassessor.com/SsoService/

   3. This is registered under allowed origins

4. {PROVIDER} is unique to each client.

Step 3: Kryterion creates the OIDC configuration

Kryterion Support configures the client's region in the Webassessor admin application (SSO details for the client region, type OIDC). The configuration fields are:

Changes to these settings take effect on every Webassessor SSO node as soon as they are saved. The IdP discovery document itself is cached for up to 10 minutes.

Step 4: Client uses the following links to initiate the SSO workflow

1. Sandbox: https://sb01.webassessor.com/SsoService/doOidc?provider={PROVIDER}&brand={BRAND}

2. Production: https://www.webassessor.com/SsoService/doOidc?provider={PROVIDER}&brand={BRAND}

3. {PROVIDER} and {BRAND} values are unique to each client.

4. Both parameters are required for a standard login. If brand is missing, or no OIDC configuration exists for the provider, the user is sent to the login page.

How Webassessor identifies the user

Webassessor resolves the Webassessor account in this order:

1. By IdP identity. Webassessor remembers the pair (provider, sub) from a previous sign-in. If the pair is known, that account is used, even if the user's email or login changed on the IdP side.

2. By login. The login identifier is read from the ID token claim named in Login Claim Name. If that is blank, or the claim is not present in the token, Webassessor falls back to the email claim and uses its value as the login. If neither is available the sign-in is rejected. The identifier must match a Webassessor user's login. Matching on the user's email address field, or on the Webassessor user ID, is not available.

3. By JIT provisioning, if no account matches and JIT Provisioning is Yes (see below).

4. If none apply, the user is sent to the login page with an error (or to the create-account page for a candidate when Allow Create Account Page is Yes).

After a successful sign-in, Webassessor records the sub against the account for subsequent sign-ins.

Candidate sign-in

A candidate is a Webassessor user whose role is Candidate.

• Existing, active candidate: the user is signed in and sent to the landing page configured on the SSO configuration (Home, Registration or Assessments).

  • If the client region uses the new candidate UI, the user is handed off through a one-time credential and arrives at the new candidate pages.

  • Otherwise the user lands on the legacy candidate pages with a login cookie set.

• Existing, inactive candidate: no session is created. The user is shown the "not authorized" page.

• Candidate does not exist and JIT is off: the user is sent to the login page with userNotFound. If Allow Create Account Page is Yes, the user is sent to the create-account page instead.

• Deep links: if the initiation link carries a postLoginParams value, the candidate is sent to the new candidate UI hand-off with that value after sign-in.

• Candidate with an admin role claim: if the IdP asserts an admin role claim but the matching Webassessor account is a candidate, the sign-in is denied (roleMismatch).

Admin sign-in

An admin sign-in requires both of the following, on top of the user matching a Webassessor account:

1. The IdP asserts an admin role in the ID token (see "Role claim").

2. The Webassessor account's role is one of the roles allowed for SSO, and the account is active.

Role claim. Webassessor reads the role from the ID token claim https://claims.webassessor.com/role. If that is not present it reads a claim named role.

• A value of admin is accepted as an admin assertion for an existing account.

• Otherwise the value must be the name of one of the allowed roles below (case-insensitive).

Roles allowed to sign in to admin through SSO:

An existing admin account whose role is not in this list (for example SYS_ADMIN) cannot sign in through OIDC; the user is sent to the login page.

Outcomes for an admin sign-in:

Just-in-time (JIT) provisioning

JIT automatically creates a Webassessor account on first sign-in when no existing account matches. It is controlled by two settings on the OIDC configuration: JIT Provisioning (Yes/No) and JIT Default Role (Candidate, Admin or Both). When JIT Provisioning is No, no accounts are ever created or updated from the IdP.

What JIT mode does with the role claim

"Any other role claim" includes the generic value admin (admin accounts need a specific role to be created), CLIENT_ADMIN (Site Administrators are never created by JIT), and unrecognized or non-allowed role names.

Required user data (candidates and admins)

JIT builds the new account from the User Claim Mappings configured on the SSO configuration. These are visible in the admin screen only when JIT Provisioning is Yes. For each Webassessor field, Kryterion enters the IdP claim name that carries it. Fields marked required must resolve to a value, otherwise the sign-in is rejected (userDataMissing).

Notes:

• Webassessor looks for each claim at the top level of the token, and also under the namespace https://claims.webassessor.com/ (for example https://claims.webassessor.com/email).

• If a mapped claim has a value that fails format validation, it is treated as absent and the standard-claim fallback is tried.

• If login is empty or invalid, Webassessor generates a unique login automatically (this does not reject the sign-in).

• Format checks include: valid email format; login 6 to 100 characters from letters, digits and @ . _ -; postal code up to 13 characters from letters, digits, space and -; phone characters limited to digits, spaces and ( ) * + , - .; street/city must not contain % * + < > ? ~ [ ] |; names must not contain certain punctuation; street, city, state and country limited to the lengths in the Webassessor user form (100 / 50 / 50 / 50).

• The email address must not already be in use by another user in the region, and a user with the same first name, last name and address must not already exist in the region. If either is true the account is not created (userProvisionFailed).

• At least one claim mapping row must be configured for JIT to create an account; with no mappings configured, creation fails.

• The same required-field rules apply to admin JIT, including the address fields, because both use the same User Claim Mappings.

Candidate JIT

• Creates the user with the Candidate role, status Active, in the client's region, plus a candidate record.

• Sets a random placeholder password. OIDC users never sign in with a Webassessor password.

• Custom fields (candidates only): if the client region has user custom fields, they are mapped from claims through Custom Field Claim Mappings. Validation is all-or-nothing: a required custom field with no mapping, a required custom field whose claim is missing or blank, or a value that fails its field-type validation (including picklist or options-list values) rejects the sign-in (userDataMissing) and no account is created. Optional custom fields with no mapping or no claim are skipped.

• The user is then signed in as a normal candidate (see "Candidate sign-in").

Admin JIT

• Requires JIT Default Role of Admin or Both, plus a valid, specific role claim (see table above).

• Creates the user with the claimed admin role, status Active, plus an admin record.

• Sets a random placeholder password.

• Custom fields are not applied to admins.

• A Site Administrator (CLIENT_ADMIN) is never created through JIT; that account must already exist.

• After creation the user continues through the admin sign-in checks above.

Updating existing accounts (Force Sync)

For an existing account matched by IdP identity or login, Webassessor can refresh the account's data from the ID token on sign-in. This happens only when JIT Provisioning is Yes and at least one of the following is true:

• The ID token carries the claim https://claims.webassessor.com/forceSync with the value true; or

• The ID token carries the claim https://claims.webassessor.com/last_updated_at with a time later than the last time Webassessor synced that user (or the user has never been synced). The value can be Unix epoch seconds, an ISO-8601 instant, or yyyy-MM-dd HH:mm:ss.SSS (UTC).

Force Sync is skipped for Site Administrators (CLIENT_ADMIN) and for a candidate account when the IdP asserts an admin role claim. Fields are updated only when the corresponding claim has a value; custom fields are refreshed for candidates only. If the refreshed data fails validation, the sign-in is rejected (userUpdateFailed).

Sign-in error outcomes

When sign-in cannot complete, Webassessor redirects the user to the login page with an error code:

If the ID token fails validation, or the discovery document cannot be loaded, the user is sent to the login page.

Logout

1. Webassessor ends the local Webassessor session first (cookies and session).

2. It then redirects the browser to the IdP's end-session endpoint (RP-initiated logout) with the client ID, the stored ID token as a hint when available (it can be omitted when it would make the request too large), and post_logout_redirect_uri set to the Webassessor logout URL from Step 2 (/SsoService/sso/oidcLogoutComplete). If the IdP has no end-session endpoint, or no provider is known, the user gets a local logout only.

3. When the IdP returns the browser to that Webassessor logout URL, Webassessor clears any remaining Webassessor cookies and sends the user on. The destination is, in order: the Post Logout Redirect URI from the OIDC configuration (https only), then the redirect page requested by the calling application, then the Webassessor logged-out page.

4. The Post Logout Redirect URI in the configuration is not what the IdP is told; the IdP is always given the Webassessor logout URL in Step 2.

Access to certain features is restricted based on role type in an effort to reduce item exposure and promote process integrity. Please see the member role description page for information on permissions.