For Developers

Anatomy of an SSO Request

There are dozens of pathways that a user can take from start to finish when signing into to your application via Edlink SSO. This guide will help you understand some of the common pathways and how they work.

SSO Overview

Typically, SSO requests go one of two ways, depending on the system the school uses for SSO, and the user experience you want to provide:

Client Initiated SSO

  1. The user starts on your application and clicks a button to sign in.
  2. The user is directed to an Edlink authorization endpoint.
  3. Edlink determines the user's identity provider (IdP) and redirects the user to that IdP (e.g. Google, Microsoft, etc.).
  4. The user authenticates with their IdP and the IdP redirects the user back to Edlink.
  5. Edlink processes the request and redirects the user to your application with an authorization code.
  6. Your application exchanges the authorization code for an access token and user information.

Platform Initiated SSO

  1. The user starts on their LMS or SSO platform and clicks a button to sign in to your application.
  2. The platform redirects the user to an Edlink authorization endpoint.
  3. Edlink processes the request and redirects the user to your application with an authorization code.
  4. Your application exchanges the authorization code for an access token and user information.

Broadly speaking, we can break down the SSO request into three main phases: Login Initiation, Authorization, and Token Exchange. Each of these components plays a crucial role in the SSO process, and understanding them will help you implement SSO effectively in your application.

Login Initiation

In Edlink, there are three ways that a login request can be initiated:

  1. Client Initiation
    • The end user clicks a link or button in your application that initiates the login process.
    • Your application generates a login request and redirects the user to one of our Edlink authorization endpoints.
    • This method is supported by all of our integrations except a purely LTI 1.3 integration.
  2. Platform Initiation
    • The end user clicks a link or button in their LMS or SSO platform that initiates the login process.
    • Edlink processes the request and redirects the user to your application.
    • This method is common for LTI launches as well as SSO integrations with platforms like Clever and Classlink.
  3. Edlink Initiation
    • This is a less common method of initiating a login request.
    • The user doesn't necessarily interact with their identity provider, and Edlink immediately redirects the user to your application.
    • This method will appear in situations like Impersonation and when a user signs in via the SSO Widget.

Determining the Identity Provider

When a developer initiates a login request, Edlink needs to determine which identity provider (IdP) to use for authentication. This can be done one of a three ways:

  1. The user enters their email address or searches for their school. If the user provides an email address, Edlink can look up the user's IdP based on their school's configuration.
  2. You (the developer) tell us the integration or identity provider. If you have a mechanism to determine what integration the user is coming from (i.e. you have set up custom subdomains for each school), you can pass that information when initiating the login request. Alternatively, for Clever, Classlink, and Google, it is possible to pass the IdP directly in the request.

In situations where the IdP is the initiator of the login request, no resolution is necessary.

Upstream Authorization

Since Edlink itself is not typically a root identity provider, it needs to redirect the user to their IdP for authentication. Please note, Edlink has very little control over the user experience at this stage, as it is entirely dependent on the IdP's implementation. Typically, the UX involves the user being redirected to a login page, entering their credentials, and then being redirected back to Edlink. In some systems, this process may be short-cutted if the user is already logged in to their IdP and the authorization may happen silently in the background.

Resolving the User's Identity

Next, Edlink needs to resolve the user's identity based on the information provided by the IdP. We are searching for the user in our system based on the information provided by the IdP. This is virtually never done using email address, as email is not a reliable identifier! Instead, we typically use the user's unique identifier from the IdP (e.g. Google ID, Microsoft ID, etc.).

In cases of data enrichment, there is some additional resolution that must occur (e.g. finding associated records in the linked systems).

Downstream Token Exchange

Edlink is now done with its processing and will redirect the user back to your application with an authorization code. Your application is responsible for exchanging this code for an access token and user information. This code must be exchanged within a short time frame to ensure the security of the process.

In cases where the IdP is the initiator of the login request and you have opted to use OIDC for SSO, Edlink will instead redirect the user to your application's OIDC initiation URL.

Additional Launch Context

In addition to the access token and refresh token, Edlink will provide you with additional context in the case of LTI launches (for example, Deep Linking). This context includes the user's intent (i.e. what they were doing when they launched your application), and additional information about the launch, such as the class, the assignment, the submission, and any custom parameters that were passed in the launch request (included as applicable).