GuidesClever App DashboardAPI Postman CollectionClever AcademySupportStatus
Guides

Clever Single Sign-On - Overview

Suggest Edits

❗️

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
This guide will be helpful for you if:
SSO Types
Definitions
Generating a Code
Redeeming an Access Token
Grabbing User Data With Your Token

Overview

The main flavor of SSO at Clever is OAuth 2.0. This guide will serve to illustrate key steps in the authorization grant flow of OAuth 2.0 with Clever.

The OAuth flow includes the following steps:

  1. Generating a code
  2. Redeeming an access token
  3. Accessing data on the Clever API

This guide will be helpful for you if:

  • You are just getting started with Clever Single Sign-On.
  • You're planning on building a Clever Single Sign-On integration or a Library SSO/Rostering integration.
  • You are not familiar with OAuth 2.0 authorization grant flow.
  • You have access to a command line with cURL.
  • You are not hosting anything at https://localhost:3000 in your local environment.

📘

Not what you're looking for?

SSO Types

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.

  • 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.
  • 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.
  • 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.”
  • 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.
  • 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).
  • 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.
  • 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.
  • 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.
  • Redirect URI
    • The location where the authorization server sends the user once the app has been successfully authorized and granted an authorization code.
    • Clever will always use the first Redirect URI listed in your App Dashboard Settings for Clever Portal-initiated logins.
  • 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.

Generating a Code

The authorization grant flow of OAuth 2.0 kicks off when a user initiates SSO. This happens when a user clicks on an SSO icon in the Clever Portal or a "Log in with Clever" button on your website. In the first stage of the SSO process, an authorization code is sent to the provided 'redirect_uri' once a user has authenticated with Clever. To generate this code, click the link below and proceed through the rest of the guide.

🚧

Clear existing Clever sessions.

Before you get started, ensure that you do not have any existing Clever sessions in your browser. For the best experience, we recommend using a private/incognito browser.

Click Here to Generate a Code

Enter the following credentials:

Upon authentication, you will be redirected to a localhost address. You will see an authorization code appended in the browser URL bar.

An authorization code appended to a redirect URI. This represents the first step in the authorization grant flow of OAuth 2.0.

An authorization code appended to a redirect URI. This represents the first step in the authorization grant flow of OAuth 2.0.

Redeeming an Access Token

Drop this code into the cURL command below where it says ENTER_CODE_HERE. Be sure to leave the double quotes. Notice that the authorization header already includes credentials formatted as seen below:

Authorization: Basic " + Base64.encode(client_id + ":" + client_secret)

curl --request POST \
     --url https://clever.com/oauth/tokens \
     --header 'Authorization: Basic MDk1YjgyY2JiZDhjNjg3MTRkMWM6NGIzMzg0ODljZWI0YmVjMzYyNDYxYTdjOTZlM2FhNjA5ZWZmZjA0OQ==' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "code": "ENTER_CODE_HERE",
  "grant_type": "authorization_code",
  "redirect_uri": "https://localhost:3000"
}
'

Run your cURL command. You should receive an access token as seen below:

An access token that is retrieved from the Clever /tokens endpoint using a POST call with the authorization code.

An access token that is retrieved from the Clever /tokens endpoint using a POST call with the authorization code.

Grabbing User Data With Tour token

This token can be used to grab user data. As seen below, you can drop your token into the cURL command below where it says ENTER_TOKEN_HERE. This makes a call to the /me endpoint.

curl --request GET \
     --url https://api.clever.com/v3.0/me \
     --header 'Authorization: Bearer ENTER_TOKEN_HERE' \
     --header 'accept: application/json'

The response should look something like this:

📘

Want to test using Postman?

Check out our collection here.

Updated 2 days ago

What’s Next