❗️

Clever Complete Agreement Required

This feature is included with a Clever Complete subscription. Sign up here or email your Application Success Manager to learn more.

Table of Contents

Overview
OAuth/OIDC Data Access
Working with Third-Party Authentication Services
OIDC Flow

Overview

OpenID Connect (OIDC) is the standard protocol we use to verify the identity of users. While OAuth 2.0 is about authorization (what a user can do), OIDC is about authentication (who a user is).

If you are building out an OIDC SSO integration yourself, the implementation will be exactly like that of the OAuth Flow with the key difference being the receipt of an identity token and access to the userinfo endpoint.

📘

Get Set Up for OIDC

To use OpenID Connect with Clever and receive identity tokens, you must first contact Clever Support to have your application account appropriately configured.

OAuth/OIDC Data Access

While Clever's Data API has endpoints for roster information (and more), access tokens acquired through the OAuth flow only have access to:

• /me - provides the token type (always user for SSO tokens), Clever user ID, and district ID
• /districts/{id} (where id is the district Clever ID)
• /users/{id} (where id is the user Clever ID)

Claims

Identity tokens provide the following claims:

• user_id: the Clever user ID for API versions prior to 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 beyond
• email: the user's email, if available
• email_verified: false by default (reach out to Clever Support if you need this claim to be 'true')
• given_name: the user's first name
• family_name: the user's last name

Metadata

The Identity tokens also provide some standard metadata:

• iss: always set to "https://clever.com"
• sub: the multi-role Clever user ID (used for API v3.0 and beyond)
• aud: the application Client ID
• iat: the time the token was created
• exp: one hour from the token issued time
• nonce: Used to prevent CSRF attacks. The nonce should match the parameter included in the original /authorize request to Clever. If it does not match, your application should reject the token. This claim will not show up if a nonce parameter is not provided (e.g. if the IDP initiated the request)

🚧

Multi-role users

Note the difference between user_id and multi_role_user_id. Also note that multi_role_user_id matches sub.

Secure Sync allows you to access the entirety of the Data API, our matchmaking tools, and more.

Working with Third-Party Authentication Services

One of the benefits of OpenID Connect is that it specifies a standard way for identity providers to share configuration information, which means that connecting with any third-party authentication service only requires providing a few key details.

The Discovery Endpoint

An OIDC compliant provider such as Clever shares necessary information about their requirements at something called the discovery endpoint. Clever's discovery endpoint is:

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

Even this endpoint is set up according to a standard format, so in many cases all you need to know is that Clever supports OIDC and the issuer is https://clever.com.

The discovery endpoint tells any authentication service where and how to kick off the authentication process, get tokens, and verify the tokens.

An Example Configuration

Setting up OIDC with most authentication services usually only requires filling out a few fields. This example is for AWS Cognito, but the required fields should be similar for many other providers:

• Provider name: this can be anything you'd like to use, but "Clever" makes a lot of sense here!

• Client ID: your application's Client ID, found on the Clever application dashboard

• Client secret: your application's Client secret. This is required for authenticating with Clever

• Attributes request method: Clever supports both POST and GET

• Authorize scope: Clever manages scopes through application configuration, so this is not required by Clever. However, some authentication services may still require a value of openid at a minimum

• Issuer: this is used to make a call to the discovery endpoint to grab the rest of the information needed to connect with Clever

OIDC Flow

The OIDC flow is similar to the basic OAuth 2.0 flow, but is better suited for authentication and is meant to be more secure.

Clever's OIDC discovery endpoint can be found here: <https://clever.com/.well-known/openid-configuration>

The flow is described below:

1. A user initiates a login (see Initiating Logins)
2. If the user is already authenticated with Clever, Clever will redirect the user to your application’s redirect URI with an authorization code appended. If the user is not yet authenticated with Clever, they will be asked to provide their Clever credentials before being redirected.
3. Your application will POST the authorization code back to Clever’s token endpoint with the appropriate credentials. See (our Postman collection) for an example.
4. Clever responds with an identity token that can be decoded and used to identify the resource owner (See OAuth/OIDC Data Access above).

📘

Limitations

At this time, the ID token is not available for Library integrations. However, you can also use the userinfo endpoint mentioned below.

It's worth noting that the access token can also be used at the userinfo endpoint: <https://api.clever.com/userinfo> . This is also considered a part of the OIDC specification.