OIDC Implementation

Use this page to implement OpenID Connect (OIDC) with Clever, configure third-party identity services, and understand how identity tokens and the /userinfo endpoint work.

Overview

OpenID Connect (OIDC) is the protocol Clever uses for user authentication. While OAuth 2.0 focuses on authorization, OIDC focuses on identifying who the user is.

If you are building an OIDC integration with Clever, the flow is almost the same as the OAuth flow. The key differences are:

your application can receive an identity token
you can use the /userinfo endpoint as part of the OIDC flow

📘
Get set up for OIDC
To use OpenID Connect with Clever and receive identity tokens, contact Clever Support to have your application configured for OIDC.

OAuth and OIDC data access

Access tokens

Access tokens acquired through the Clever OAuth flow do not grant full Data API access. They can only access:

/me — returns the token type, Clever user ID, and district ID
/districts/{id} — where id is the district Clever ID
/users/{id} — where id is the user Clever ID

If you need full roster access, use Secure Sync.

Identity token claims

If your application is configured for OIDC, Clever can return an identity token with these claims:

user_id — the Clever user ID for API versions before v3.0
user_type — student, teacher, staff, or district admin
district — the user’s Clever district ID
multi_role_user_id — the Clever user ID for API v3.0 and later
email — the user’s email, if available
email_verified — false by default; contact Clever Support if you need this claim to be true
given_name — the user’s first name
family_name — the user’s last name

Identity token metadata

Identity tokens also include standard metadata claims:

iss — always https://clever.com
sub — the multi-role Clever user ID used for API v3.0 and later
aud — your application client ID
iat — the token creation time
exp — one hour after token creation
nonce — used to prevent CSRF; this must match the nonce value from the original /authorize request when provided

🚧
Multi-role users
user_id and multi_role_user_id are different values. multi_role_user_id matches sub.

Working with third-party authentication services

One advantage of OIDC is that many third-party authentication services can connect to Clever with only a small set of standard configuration values.

The discovery endpoint

OIDC providers publish configuration details through a discovery endpoint. Clever’s discovery endpoint is:

https://clever.com/.well-known/openid-configuration

In many cases, all you need to know is:

Clever supports OIDC
the issuer is https://clever.com

The discovery endpoint tells your authentication service where to:

start authentication
exchange tokens
validate tokens

Example configuration

Most third-party authentication services only require a few values to connect to Clever. The example below uses AWS Cognito, but the same general fields appear in many services.

593 — Example OIDC configuration for AWS Cognito

Typical fields include:

Provider name — any label you want to use, such as Clever
Client ID — your application’s client ID from the Clever dashboard
Client secret — your application’s client secret
Attributes request method — Clever supports both GET and POST
Authorize scope — Clever manages scopes through application configuration, but some providers still require openid
Issuer — https://clever.com

OIDC flow

The OIDC flow is similar to the standard OAuth flow, but it is designed for authentication and identity verification.

Clever’s OIDC discovery endpoint is:

https://clever.com/.well-known/openid-configuration

The flow looks like this:

A user initiates login.
Clever authenticates the user if needed.
Clever redirects the user to your application’s redirect URI with an authorization code.
Your application sends that code to Clever’s token endpoint.
Clever returns an identity token and access token when your app is configured for OIDC.
Your application verifies the identity token and, when needed, uses the access token with /userinfo or other allowed endpoints.

For the full login initiation patterns, see OAuth Implementation.

Limitations

📘
OIDC limitations
Identity tokens are not available for Clever Library integrations.
If you are building for Clever Library, use the /userinfo endpoint instead:
https://api.clever.com/userinfo

The access token can also be used with the /userinfo endpoint as part of the OIDC flow.