GuidesClever App DashboardAPI Postman CollectionClever AcademySupportStatus
Guides
Start typing to search…

Clever Single Sign-On - Best Practices & Edge Cases

Review Clever Single Sign-On best practices and handle common edge cases before certification.

Use this page to review implementation best practices for Clever Single Sign-On and handle common edge cases before certification.

Best practices

Use these practices to avoid common SSO implementation problems:

  • Do not exchange the same authorization code more than once. Clever returns an error if you do.
  • Support login requests that start from the Clever Portal or an Instant Login link. Do not redirect those users back to your own login page.
  • Make sure your first configured redirect URI can handle logins for all districts without requiring extra parameters or district-specific subdomains.
    • A common pattern is to use one centralized redirect URI, then route users to the correct domain or path after login.
  • Use HTTPS on your production redirect URI. The rest of your application should also use HTTPS.
  • Include a Log in with Clever button on your site.
  • Override any existing session when a new Clever authentication request arrives. This is important on shared devices.
  • Show clear account indicators in your UI, such as the user’s name or username, so users can confirm they are signed in to the correct account.
  • Include a logout button.
  • If your app requires fields that Clever Single Sign-On does not provide, such as school information, collect them during first login.

Edge cases

Multi-role users

With v3.0 of the API, Clever introduced multi-role users. This supports users who have multiple roles in a district, such as someone who is both a teacher and an administrator.

In API responses from /v3.0/users, the roles object contains each role that is shared with your application. Each role includes role-specific fields such as legacy_id. This value is different from the user’s top-level id.

Example:

{
    "data": {
        "created": "2022-05-15T22:20:03.535Z",
        "district": "62817af12d430f5d54001f99",
        "email": "[email protected]",
        "last_modified": "2024-07-10T16:22:11.422Z",
        "name": {
            "first": "PE",
            "last": "Bot"
        },
        "roles": {
            "teacher": {
                "schools": [],
                "legacy_id": "6298ef2e9e30ed3d9066e118"
            },
            "district_admin": {
                "legacy_id": "62817af1d65e86e415b6f68d"
            }
        },
        "id": "62817c88dc4dc002ea40b594"
    },
    "links": [
        {
            "rel": "self",
            "uri": "/v3.0/users/62817c88dc4dc002ea40b594"
        }
    ]
}

When a multi-role user starts SSO from Clever, your application does not receive context about which role they intended to use. Plan a default behavior for that case.

For example, if a user is both a teacher and an admin, your application might send them to the admin experience by default.

State parameters

If you use an identity management system such as Okta or Auth0, your implementation may require a state parameter.

The state parameter helps prevent CSRF attacks and preserve application state between the authorization request and callback.

Clever-initiated logins do not include a state parameter by default, which can create problems for those implementations.

To handle this:

  1. Detect Clever-initiated logins that arrive without state.
  2. Do not complete authentication from that request.
  3. Treat that request as a trigger to restart authentication from your own site.
  4. Include your own state parameter in the new request.
  5. Clever will pass that state value through after authentication.

If you need help planning this flow, contact Clever Support through the Help Center chat. Your application is still responsible for implementing the logic.

Supporting multiple applications with one Log in with Clever button

Some products support multiple environments or multiple Clever integration accounts, but still want to use a single login page with one Log in with Clever button.

For this use case, add the return_unshared=true parameter to the authorization URL:

https://clever.com/oauth/authorize?response_type=code&redirect_uri=&client_id=&return_unshared=true

If a user does not have access to that specific app, Clever sends an unauthorized-user error to the redirect_uri instead of showing a user-facing error.

Your application can then start a new login attempt with a different client ID and, if needed, a different redirect URI.

🚧

Avoid infinite loops

Do not include return_unshared on the final app you try. If every attempt includes return_unshared=true and the user has access to none of the apps, your flow can loop forever.

Shared devices for students

If your app has strict security requirements and needs to reduce the chance of a student accessing the wrong account on a shared device, add confirmed=false to the authorization URL.

This prompts Clever to confirm the identity of the student.

Example:

https://clever.com/oauth/authorize?response_type=code&redirect_uri=&client_id=&confirmed=false

This behavior only applies to student users.

Implicit grants

Clever uses the authorization code grant flow by default.

In some cases, the implicit grant flow documented here may also be allowed.

Single logout

🚧

Clever does not support SLO

Use safe session-management practices in your own application, especially for shared devices.

Single Logout (SLO) means logging a user out of multiple applications or services with a single action through a centralized authentication service.

Clever sessions can last up to 24 hours depending on the device. Clever does not recommend logging users out of their Clever session when they log out of your app, because that would interrupt the expected SSO experience across the rest of their learning tools.

If you believe you have a strong use case for logging users out of Clever, contact Clever Support through the Help Center chat.

Identifying impersonations

District admins can sometimes impersonate users and then use SSO into your application on that user’s behalf. This can affect login analytics or inflate certain login metrics.

Clever can expose a flag that indicates whether an SSO request came from impersonation.

If you want this feature, contact support at https://support.clever.com.

Once enabled, impersonated login attempts include loginas_by_admin=true in the redirect URL.

Updated 5 days ago

What’s Next