2249
This article covers:
- OIDC Overview
- OIDC Set-Up
- Set-Up Requirements Provided by the Customer
- Set-Up Requirements Provided by BenchPrep
OIDC Overview
OpenID Connect (OIDC) is an authentication layer on top of the OAuth 2.0 authorization framework. It allows computing clients to verify the identity of an end-user based on the authentication performed by an authorization server, as well as to obtain the basic profile information about the end-user in an interoperable and REST-like manner.
At a high level, the authentication flow of OIDC looks like this:
Key OIDC Concepts
- BenchPrep will act as the client, which is the application providing a service.
- The Customer will act as the Identity Provider (IdP), which is the entity authorizing the user; sometimes known as the identity provider.
- Authentication Initiation: The authentication flow is initiated when a user visits a static URL hosted by BenchPrep. This URL can either be linked to by the Tenant or configured for unauthenticated users to be redirected to. Please Note: Configuring the URL is deploy dependent.
- Client Initiated Backchannel Authentication (CIBA) sign-in describes the OIDC sign-in flow when initiated by the client, triggered when the user tries to access content or sign in directly on the client application.
- Please Note: This sign-in flow is required if native mobile applications are to be used.
OIDC Set-Up
JSON Web Token (JWT) Claims
At a minimum for an OIDC SSO integration, BenchPrep expects the following learner information to be sent in the login payload (key names are flexible):
- name: Learner’s full name (can be provided as a collection of fields or one field)
- email: Learner's email (must be unique)
Optional claims can be included to provide greater flexibility.
- branch_slug: If present and valid, the user will be assigned to the slug of the branch included
- group_ids: Comma separated string of group ids (example: “13724,149223,23081”) that a user will be assigned to upon login
Technical Specifications for Course Authorization
The SSO payload may contain an optional authorized_courses claim. This claim will enable course authorization. This claim should include a JSON array object that includes BenchPrep course slugs and optional expiration dates (examples included below). This authorized_courses attribute may be specified within either the ID Token or the UserInfo response. If the field is not present within the ID Token, an additional request to the UserInfo endpoint will be made and an access token must be provided by the Token Endpoint during the Authorization Code Flow. Courses assigned to the user will be added or deactivated upon login based on what is included in the claim.
Example:
JSON Schema specification:
Setup Requirements Provided by the Customer
In order to set up an OIDC integration, BenchPrep can use a discovery URI where configuration information can be extracted or it can manually configure the integration.
The following information marked * is required, depending on the usage of discovery URI.
BenchPrep needs these fields per deployment environment in which OIDC is to be configured for the tenant. BenchPrep recommends configuring both Staging and Production to ensure pre-production testing of SSO.
| Field (*required) | Notes |
|
*identifier |
Provided by the Identity Provider. This identifier corresponds to the secret and identifies the configuration installed for a Deployment Environment. |
| *secret | Secret key. This secret corresponds to the identifier and authorizes the configuration installed for a Deployment Environment. |
| *discovery_uri | URL that the SSO application will reach out to to find the authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri information. The response from this URL is cached for 1 minute. If the Identity Provider does not have support for the discovery protocol, the information BenchPrep requires can be hardcoded. |
| *logout_url | Static URL to redirect the learner to after logout from BenchPrep. This URL can contain static query parameters if necessary but currently will not dynamically contain any learner information. |
| scopes | Optional. OIDC server may require BenchPrep to request scopes with the JWT. Scopes should be a whitespace-separated list of scopes in a string. Example: 'openid email profile cn' |
Setup Requirements Provided by BenchPrep
OIDC Provider Slug
BenchPrep will generate a slug that is unique across Deployment Environments, e.g. tenantSlug and tenantSlugStaging. This slug can be determined prior to receipt of the Setup Requirements Provided by Customer and will be used to generate the following fields.
| Field (*required) | Notes |
| redirect URL |
The client will typically need to register this as an allowed URL to redirect learners to after the login process. This can be generated once we know what the OIDC Provider and Tenant slugs will be.
IE - https://<tenant-public-link>/sso/oidc/<providerSlug>/login |
| login URL |
This is the URL that the learner will visit in the browser to initiate the login process. This can be linked to directly by the client. This can be generated once we know what the OIDC Provider and Tenant slugs will be.
IE - https://<tenant-public-link>/sso/oidc/<providerSlug>/initiate |
