Token-based Single Sign-On

Follow

Token-based SSO for the Skilljar platform is accomplished by retrieving a single-use login token for your user, and then redirecting their browser to the login endpoint. Don't want to use token-based? Go here to see other SSO options!

To fully configure token-based SSO, you must:

  1. Configure and provide to us your Remote Login URL (this is the URL where your users enter in their login information to your website or platform)
  2. Call our APIs to generate a Login Token for the user

1. Remote Login URL

The remote login URL is a URL within your system that handles login requests.  Once your Skilljar domain is configured with a remote login URL, then attempts to view protected resources on the Skilljar platform (course content, profile page, or the user clicks the "sign-in" link) will forward the user's browser to your configured remote login URL rather than show the standard Skilljar login page.  Skilljar's platform appends a next querystring parameter with the path on your Skilljar domain that the user was attempting to access.

Your remote login endpoint should authenticate the user, if not already signed-in on your platform, generate 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 example course:

/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

 

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

Adding a user to a domain is accomplished 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 as well since any personalization we do (Certificates, Notification Emails, Profile Page) look better when we have an actual name for the user.

Create a User (or retrieve an existing user)

POST /v1/domains/example.com/users

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,
    "login_token": "qrstuvw321098-3xn-a1b23cd456dfg7890hijk"
}

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.

 

 

Have more questions? Submit a request

Comments

Powered by Zendesk