Configuring Token-Based Single Sign-On (SSO)

Token-based single sign-on (SSO) can be used as an SSO method for your Skilljar training. This method takes a single-use login token for your user, and then redirects their browser to the login page for them (known as the login endpoint). In this article, we’ll explain how to set up and manage token-based SSO for your Skilljar platform. 

Don't want to use token-based? See other SSO options we support!

What is an SSO token?

An SSO token is data, such as the user’s login email address, that is passed from one system to another during the SSO process. Using a token-based authentication method, users verify their data and then receive a unique access token (created using the Skilljar API - see below), allowing them to log in. When enabled, users can sign in to your learning content using just one set of credentials. For more detailed information, see the Remote Login URL section.

Using token-based SSO is the most flexible of all of our support SSO methods and allows you to build your own custom authentication using our API, tailoring the experience to fit your customer’s needs without the need for any third parties.

Basic Setup

• Note: Setup can take anywhere from 45 to 160 minutes, depending on your organization's IDP configuration. This does not include potential troubleshooting.

To fully set up and configure token-based SSO for your platform, you must:

1. Configure your remote login web address/URL (the URL where users will be re-directed to for login and authentication)
2. Provide the remote login URL to our Customer Success team or Skilljar's Product Support Team (support@skilljar.com)
3. Call our APIs to generate a login token for the user. 

Here is a conceptual diagram of Skilljar’s Token-based SSO configuration. The initial setup steps are above and the detailed API call flows are listed below. 

Remote Login URL

The remote login URL is a URL within your system that handles login requests. Once your Skilljar domain is set up with a remote login URL, it’ll attempt to view protected resources on the Skilljar platform (such as course content, profile page, or when the user selects the "sign-in" link) and will forward the user's browser to your configured remote login URL rather than show the standard Skilljar login page. Skilljar's platform adds a next querystring parameter with the path on your Skilljar domain that the user was attempting to access.

Your remote login endpoint (where the user logs in) should authenticate the user (if they aren’t already signed in on your platform), create a single-use login token, and then redirect the user back to the Skilljar domain's login token callback endpoint with the next querystring parameter that was passed in.

For example, a user attempts to access a lesson on the example course below:

/example-course-url/lesson-id

If the user is not signed in on the Skilljar platform, the user will be forwarded to your remote login URL:

Response: HTTP 302
Location: http://your-domain/login-endpoint?next=%2Fexample-course-url%2Flesson-id

Your "login-endpoint" then validates the user, retrieves a login token via the API as described above, and then forwards the user back to your Skilljar domain's login token callback endpoint:

Response HTTP 302
Location: http://your-skilljar-domain/auth/login/callback?token=qrstuvw321098-3xn-a1b23cd456dfg7890hijk&next=%2Fexample-course-url%2Flesson-id

Here is an example of an API call to the user’s endpoint, including their login credentials and the login_token key:

APIs

Skilljar APIs return JSON over HTTP. See the Getting started with the Skilljar API article for details on how to set-up and get started calling our APIs.

List Domains

GET /v1/domains

Example Response: HTTP 200 OK

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "abcdefg123456",
            "name": "example.com",
            "catalog_title": "All Courses",
            "private": false,
            "access_code_message_html": "",
            "marketing_message": null
        }
    ]
}

Get details for a Domain

GET /v1/domains/example.com

Example Response: HTTP 200 OK

{
    "id": "abcdefg123456",
    "name": "example.com",
    "catalog_title": "All Courses",
    "private": false,
    "access_code_message_html": "",
    "marketing_message": null
}

List Users for a Domain

GET /v1/domains/example.com/users

Example Response: HTTP 200 OK

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "user": {
                "id": "opqrstu345678",
                "email": "joe@example.com",
                "first_name": "Joe",
                "last_name": "User"
            },
            "active": true,
            "marketing_optin": null,
            "expires_at": null
        },
        {
            "user": {
                "id": "cdefghi567890",
                "email": "jane@example.com",
                "first_name": "Jane",
                "last_name": "Doe"
            },
            "active": false,
            "marketing_optin": null,
            "expires_at": null
        }
    ]
}

Add a User to a Domain

You can add a user to a domain via an HTTP POST to the v1/domains/{{domain.name}}/users endpoint. If a user already exists with the given email, the existing user is retrieved and returned. If the user is new (or new to this domain), the user is created, added to the domain and the details are returned.

The minimum required data to add a user to a domain is the user.email field. It is recommended that you always include user.first_name and user.last_name since any personalization we do (such as certificates, notification emails, and profile page) looks better when we have an actual name for the user.

Create a User (or retrieve an existing user)

• Note: Token-Based SSO must be enabled on the domain level before being able to retrieve a login_token.

POST /v1/domains/example.com/users

• Note: This POST request is required to generate a new single-use login token. A valid login token is needed to successfully find and log the user into Skilljar. The GET request below won't generate a new login token but will show the last login token generated by a POST.

Where the POST data includes:

{
    "user": {
        "email": "bob@example.com",
        "first_name": "Bob",
        "last_name": "User"
    }
}

Example Response: HTTP 201 CREATED

{
    "user": {
        "id": "qrstuvw321098",
        "email": "bob@example.com",
        "first_name": "Bob",
        "last_name": "User"
    },
    "active": true,
    "marketing_optin": null,
    "expires_at": null,
    "login_token": "qrstuvw321098-3xn-a1b23cd456dfg7890hijk"
}

Get User details

You can also get the details for a given user via the following endpoint:

GET /v1/domains/example.com/users/qrstuvw321098

Example Response: HTTP 200 OK

{
    "user": {
        "id": "qrstuvw321098",
        "email": "bob@example.com",
        "first_name": "Bob",
        "last_name": "User"
    },
    "active": true,
    "marketing_optin": null,
    "expires_at": null,
}

Logging a User in via the Login Token

If your domain is configured for token-based SSO, you'll notice the Domain User detail responses contain a login_token parameter. This is a single-use token that can be used to login the User on your Skilljar domain. After you've retrieved the Login Token via the API, you can then redirect the User's web browser to the Skilljar Login Token Endpoint as described in the following section.

Login Token Callback Endpoint

Your domain on the Skilljar course platform has a special endpoint configured to log-in users with a single-use login token:

/auth/login/callback?token=qrstuvw321098-3xn-a1b23cd456dfg7890hijk&next=%2Fexample-course-url

This endpoint validates the token supplied in the token querystring parameter, if valid - logs the user into the Skilljar platform, then redirects the user to the path supplied in the next querystring parameter.

Frequently Asked Questions

How long is a login token valid?

Login tokens expire after three days. This is the default and maximum limit. 

How long is the session cookie?

If left blank, the default idle session timeout is two weeks before a student is signed out. This is also the maximum amount of time and the two weeks or that you set will reset whenever the student engages with the platform.