Standard SSO Integration (OAuth2)
Updated March 5, 2021
Updated March 5, 2021
This document provides a step-by-step integration mechanism into Kryterion SSO implementation using OAuth2 standard.
The integration Document provides a high-level overview of the Webassessor Single-Sign-On Integration offered by Kryterion, Inc to its clients. It is intended to capture the integration points and boundaries of the SSO implementation done by Webassessor and facilitate client integration with the Kryterion SSO solution.
[OAuth]: The OAuth 2.0 specification. http://tools.ietf.org/html/rfc6749
For your reference, here is the link to the integration document for a SAML implementation.
Before the integration can be setup, we need certain values to be in our Webassessor system to be able to communicate with the client OAuth server. The first table below lists the information (per the standard OAuth spec) needed before we attempt to integrate.
The client will provide OAuth 2.0 server details (URL & login information) for Kryterion to register Webassessor as an application authorized to access the client’s User Profile information. In addition, Webassessor will require the following information to be stored in our database before an active SSO integration:
| Authorization URI | URL address of OAuth 2.0 server that will provide authorization code |
| Token Exchange URI | URL address of OAuth 2.0 server that will provide access token |
| WebService URI | Client WebService address (or specification) |
| Client Id | Identification of the application (Webassessor) as a “subscriber” to the client |
| Client Secret | (Optional) The client secret |
Only after the above information is shared by the client and properly saved in Webassessor database can the SSO integration be tested.
The client’s first communication with Kryterion SSO will be through this URL:
In the above URL, “PROVIDER” and “BRAND” values will be available to the client once the client is created in Webassessor system as an entity.
| PARAMETER | SUPPLIED BY | DESCRIPTION |
| provider | Webassessor | A unique name saved in the Webassessor database to identify the client |
| brand | Webassessor | The client’s brand name created in Webassessor |
Only after the above information is shared by the client and properly saved in Webassessor database can the SSO integration be tested.
Once the above request reaches Webassessor, the application prepares an authentication URL and executes an HTTP redirect to the client’s OAuth 2.0 server for authentication. The client will authorize Webassessor to access its web services or make API calls through the Authorization URI, which will accept the following parameters:
| PARAMETER | SUPPLIED BY | DESCRIPTION |
| scope | client | The scope of the access request (member permissions needed, data to be used to create user info for automatic creation / prepopulation of user profile) |
| redirect_uri | Webassessor | The Webassessor call back URI |
| state | Webassessor | Concatenated string “PROVIDER_NAME>-<BRAND>” |
| response_type | client | The value is always “code” (indicating a request for an authorization code as defined in OAuth 2.0 specification) |
| client_id | Webassessor | The registered client id of the application / API key |
Webassessor will access the URI in this manner:
AUTHORIZATION_URI?scope=SCOPE&redirect_uri=REDIRECT_URI&state=STATE&response_type=code&client_id=CLIENT_ID_OR_API_KEY
After the URI is authenticated against the client’s OAuth 2.0 server, the Webassessor callback URL (REDIRECT_URI) is called back with the following parameters:
| PARAMETER | SUPPLIED BY | DESCRIPTION |
| state | Webassessor | This is the same ‘state’ parameter passed by the application in AUTHORIZATION_URI (see Step 3) |
| code | client | Authorization code generated by client OAuth 2.0 server |
REDIRECT_URI?code=CODE&state=STATE
Once the control reaches the Webassessor callback URL, the “code” received from the client is sent to OAuth 2.0 server (Token Exchange URI) together with the parameters below:
| PARAMETER | SUPPLIED BY | DESCRIPTION |
| code | client | The authorization code retrieved from previous step |
| client_id | client | The registered client id of the application / API key |
| client_secret | client | Issued to the application during registration |
| response_uri | Webassessor | |
| grant_type | client | The value is always “authorization_code” (indicating request for access token as defined in OAuth 2.0 specification) |
Submission is via HTTP “POST” method as these parameters must not be transmitted through the request URI.
POST /TOKEN_EXCHANGE_URI HTTP/1.1Host: CLIENT_SERVERContent-Type: application/x-www-form-urlencoded
code=CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI&grant_type=authorization_code
In exchange, client authorization server must respond with an “access_token” written in JSON format. For example:
{
“access_token”:”ACCESS_TOKEN”,
“expires_in”:3600
}
Webassessor may now use the token to call (RESTful web service call) the Web Service provided by the client to retrieve the User Profile. Webassessor will be customized to call the client’s Web Service.
| PARAMETER | SUPPLIED BY | DESCRIPTION |
| ACCESS_TOKEN_PARAMETER | client | Access token retrieved from OAuth 2.0 server |
*Note that ACCESS_TOKEN_PARAMETER itself may vary per client.
Once the client Web Service receives the token sent by Webassessor, Web Service may opt to do the following:
Once SSO is authenticated and received from Clients, user profile data will be searched to match an existing User profile in Webassessor. Once the match is found (matching “email” in Webassessor), the User will be automatically logged into Webassessor and redirected to the home page where he/she will have options like registering for or launching an exam.
At a minimum, Webassessor expects the following attributes to match and identify a User profile:
| ATTRIBUTE NAME | DESCRIPTION | MANDATORY |
| Webassessor Login OR Webassessor database User ID | When APIs are used to create a new user in Webassessor, both the login and the database ID are sent in the response. Clients can use either one for SSO, as agreed by both parties. | Yes |
Please Note: Identifying a user with a unique email address that also acts as a link between the two systems, is not ideal because email addresses may change. A User ID is a more secure and lasting way to identify a user.
Our platform, solutions, and services are perfect for building modern credentialing programs. Let us help you get off to a flying start.
7776 South Pointe Parkway West
Suite 200
Phoenix, Arizona 85044
429-433 Pinner Road
North Harrow
Middlesex HA1 4HN
United Kingdom
Want more information on how to start or expand a credentialing program? Fill out the form below and we’ll get back to you right away!