GuidesClever App DashboardAPI Postman CollectionClever AcademySupportStatus
Guides

OAuth and OIDC Overview

Prerequisites

Read Clever SSO Overview.

Overview


Clever uses OAuth 2.0 and the related OpenID Connect (OIDC) standard to manage user authorization and authentication.


The OAuth 2.0 specification (see below) defines several methods, or flows, for providing tokens. These tokens can be used to access an API or, in the case of OIDC, may directly provide information about a user's identity. Clever uses the authorization code grant type. If you are unable to use the authorization code grant type, please reach out to Clever Support.



Definitions


📘

Bolded terms found in this section of the documentation are defined below.


  • Client
    • An application making protected resource requests on behalf of the resource owner and with its authorization. Please note that the term “client” does not imply any implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices)
  • Authorization Grant
    • A credential representing the resource owner’s authorization. The end-user is saying, “Yes, this application is authorized to access my data. Please give them an access token”.
  • Access Token
    • Credentials used to access user data. The token is an opaque string representing authorization that has been issued to the client
    • Do not confuse a user-level access token with the district-level token. The user-level token only authorizes access to that specific user’s data while a district token grants access to data across the district. To learn more about the district token, see District-App Tokens
  • Identity Token
    • JSON Web Tokens (JWTs) that conform to the OpenID Connect (OIDC) specification. They are composed of a set of key-value pairs called claims. Unlike access tokens, which are opaque objects that cannot be inspected by the application, ID tokens are meant to be inspected/decoded and used by the application.
  • Discovery Endpoint
    • Provides a client with configuration details about the OpenID Connect Authorization Server. The client makes an HTTP GET call to the discovery endpoint: /. well-known/openid-configuration. A discovery document is returned containing the OpenID Connect implementation details.
  • Userinfo Endpoint
    • An OAuth 2.0 protected resource of the Connect2id server where client applications can retrieve consented claims, or assertions, about the logged in end-user. The claims are typically packaged in a JSON object where the sub member denotes the subject (end-user) identifier, in this case, a Clever ID.
  • Authorization Code Grant Type
    • This is one of the grant types associated with the OAuth Authorization Grant Flow. It requires an authorization server to grant an authorization code after the resource owner is authenticated and has authorized the client
  • Redirect URI
    • The location where the authorization server sends the user once the app has been successfully authorized and granted an authorization code
  • Primary Redirect URI
    • The first redirect URI in your list of redirect URIs. When a redirect URI is not specified for an SSO request, the primary redirect URI will be used
  • Clever ID
    • Globally unique identifier assigned to each data object in Clever. Denoted as id in the API response, this field should be used to identify resource owners in an SSO exchange.

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)

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

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)

🚧

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.


OAuth Flow


The expected implementation of SSO with Clever is the authorization code grant type. The step-by-step flow is detailed 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.
    1. You can also test it out from your terminal using our guide here.
  4. Clever responds with an access token in order to provide your application access to the end-user’s protected resource.
  5. The access token can then be used at https://api.clever.com/v3.0/me to grab the resource owner’s Clever ID.

🚧

/me Endpoint Version

Be sure to specify a version in your /me endpoint call. This will ensure you receive the correct Clever ID for a user given the API version being used in other API calls.

  1. Using the access token and the resource owner’s Clever ID, your application can then make a call to https://api.clever.com/v3.0/users/{id} to access additional information that can be used to authenticate a user. See our Postman collection for an example.

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).

📘

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.

Updated about 2 months ago

What’s Next