Deep Links SSO Integration (OAuth2)
A step-by-step integration mechanism into the Webassessor SSO implementation using the OAuth2 standard.
This document provides a step-by-step integration mechanism into the Webassessor SSO implementation using the OAuth2 standard. Clients can choose the landing page based on what task they want to complete when they SSO into Webassessor. Depending on the landing page selected, they will be sending appropriate parameters. This enhanced, custom-SSO implementation will allow client applications to integrate with Webassessor, so SSO can be used for registration or launch of an exam in Webassessor.
Some of the use cases that will be handled by this enhanced SSO integration are:
Seamless candidate access to the home page after SSO.
Seamless candidate access to the “Register for an Assessment” page after SSO.
Seamless candidate access to either the “Testing Center” selection” page (KTN) or the “Calendar” page (OLP) after SSO.
All the above options will be supported by the same SSO call. Based on their needs, clients can choose to pass in the appropriate parameters in the SSO call. The integration specification will be generic enough to accommodate most of the clients’ needs as of December 5, 2023.
Purpose
This Integration Document provides a high-level overview of the Webassessor Single-Sign On using Deep Links 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 facilitates client integrations with the Kryterion Webassessor SSO solution.
References
[OAuth]: The OAuth 2.0 specification. http://tools.ietf.org/html/rfc6749
Prerequisites
The SSO follows the OAuth2 spec. In order for a client to be able to effectively integrate with Webassessor for SSO, either the client should have an in-house OAuth server or should be able to use a third-party, OAuth-validating server like Okta, Salesforce, etc. Assuming there is a functioning OAuth server (typically consisting of a validating service, a token service, and a profile service), the following diagram explains the communication during a typical OAuth2 SSO call between Webassessor and a potential client.
Client should be created in the Webassessor system as an entity and region. Brand should also be created since it is part of the communication during SSO calls.
Integration Points and Flows
Implementation Steps
Step 1: Client Provides OAuth 2.0 Server Details
Before the integration can be set up, we need certain values in our Webassessor system that communicate with the client OAuth server. The table below lists the information (per the standard OAuth spec) needed before we can 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 the Webassessor database can the SSO integration be tested.
Step 2: Client’s First Communication with Kryterion SSO
The client’s first communication during an SSO call will be through this URL:
https://www.webassessor.com/wa/oauth/ssoLogin/BRAND/PROVIDER
In the above URL, “BRAND” and “PROVIDER” values will be available to the client once the client has been created as an entity in Webassessor.
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 |
Step 3: Kryterion Access to Client’s Web Services/API Calls
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 authenticate 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 / pre-population 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
Step 4: Webassessor Call Back URL Parameters
After the URI is authenticated against the client’s OAuth 2.0 server, the Webassessor callback URL (REDIRECT_URI) includes the following parameters:
PARAMETER | SUPPLIED BY | DESCRIPTION | MANDATORY |
state | Webassessor | This is the same ‘state’ parameter passed by the application in AUTHORIZATION_URI (see Step 3) | YES |
code | client | Authorization code generated by client OAuth 2.0 server | YES |
postLoginParams | client | This is used for post login actions such as registration or launching an exam. The separator is the Registration For registration after Login, accepted parameter combinations & scenarios: · REGISTER-SCHEDULE- PRODUCT_ID-DELIVERY_TYPE-CURRENCY-PRICE · REGISTER-SCHEDULE- PRODUCT_ID-DELIVERY_TYPE · REGISTER-RESCHEDULE-REGISTRATION_ID · REGISTER-CANCELLATION-REGISTRATION_ID (Only when there is Price or fee involved) Notes: · SCHEDULE call – “PRODUCT_ID” is the product ID of an exam in Webassessor. · RESCHEDULE call – REGISTRATION_ID should be the “REGISTRATION_ID” of the registration in Webassessor (This will be available to clients based on the “Add Registration” Webservice they will use to create the registration in Webassessor or the “Get Registration” call they make at the end of SSO “SCHEDULE” call above). · CANCEL call – REGISTRATION_ID should be the “REGISTRATION_ID” of the registration in Webassessor (This will be available to clients based on the “Add Registration” Webservice they will use to create the registration in Webassessor or the “Get Registration” call they make at the end of SSO “SCHEDULE” call above). · CANDIDATE_LOGIN should be passed in only in case of Admins trying to login using SSO. Based on the CANDIDATE_LOGIN, Webassessor will know which candidate the admin is trying to register/reschedule/cancel. Launch For Launch after Login, the accepted parameter combination is as follows: LAUNCH-REGISTRATION_ID Notes: “REGISTRATION_ID” for launch will always be the “REGISTRATION_ID” of the registration in Webassessor. This will be available to clients as a result of the “Add Registration” Webservice they use to create the registration in Webassessor or “Get Registration” call they make at the end of the SSO “SCHEDULE” call above. Completed Assessments/Receipts This is a read-only function, where a Test Candidate can use a deeplink SSO to come to Webassessor for viewing Completed Assessments/Transcripts and generate receipts if applicable. For viewing Transcripts/Receipts after Login, the accepted parameter is TRANSCRIPTS | NO |
Examples:
REDIRECT_URI?code=CODE&state=STATE&postLoginParams=REGISTER-SCHEDULE-123456-KTN-USD-100.00
REDIRECT_URI?code=CODE&state=STATE&postLoginParams=REGISTER-RESCHEDULE-123456
REDIRECT_URI?code=CODE&state=STATE&postLoginParams=REGISTER-CANCELLATION-123456
REDIRECT_URI?code=CODE&state=STATE&postLoginParams=LAUNCH-123456
Registration Related Parameters Explanation
VARIABLE | DEFINITION |
REGISTER | This value is always REGISTER and indicates that the post login action is Registration. |
SCHEDULE, RESCHEDULE, CANCEL | Acceptable values in the call above. |
CLIENT_PRODUCT_UNIQUE_ID | This is the unique external reference ID of the product. Clients can provide this when creating a product in Webassessor. |
DELIVERY_TYPE | Delivery Type of the intended exam registration. |
CURRENCY | Currency of the amount. |
PRICE | Price of the exam. If price is not applicable then a default of “0.00” should be sent. |
Launch Related Parameters Explanation
VARIABLE | DEFINITION |
LAUNCH | This value is always LAUNCH and indicates that the post login action is Launching an exam. |
REGISTRATION_ID | Registration ID of the exam that needs to be launched. |
Step 5: OAuth 2.0 Server Parameters
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
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 the access token as defined in OAuth 2.0 specification) |
with the parameters below:
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
}
Step 6: Retrieving the User Profile
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:
Send the User Profile object back to Webassessor.
Call the Kryterion demographic Web Services to create the User (with all required attributes) in Webassessor. After the User creation is complete, the User profile object (with minimum information like “email” to help identify a User in Webassessor) is sent back by the client Web Service to Webassessor.
User Profile After Retrieval
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.
User Profile Attributes
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 |
Step 7: Redirect Back URL and Mapping Attributes
Redirect Back URL:
This feature is purely for user continuity and related end-user experience. Some clients would prefer that the end user go back to the origin site, and this step will describe how to achieve that.
On the Webassessor SSO configuration page, there is a new parameter, “Client Redirect URL”. This is one standard URL chosen by the client for the whole SSO integration. While setting up SSO through the Webassessor UI, clients can provide a URL. Users will be redirected to that URL at the end of the registration or launch process. Previously, they were left in Webassessor. If no value is given for the URL during setup, the test candidate will be logged out of Webassessor as the last step.
The suggestions for clients for this URL would be some standard acknowledgment page based on the flow on their sites.
Mapping Attributes
There should be at least one unique value between Webassessor and the Client system, such as LOGIN or USER-ID or EMAIL. These values have to be mapped using the Client_Map_Key and Webassessor_Map_Key
ATTRIBUTE NAME | DESCRIPTION |
Client_Map_Key | This is the actual attribute name received in the Profile Service Call. This attribute will contain the unique value through Webassessor and will be able to retrieve a candidate’s profile. |
Webassessor_Map_Key | This is the Webassessor value to which the Client_Map_Key retrieved value will be mapped. Clients can have the candidate email on their end mapped to Login on our end or they can have user ID from there end mapped to Login on our end. |
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.
Access to certain features is restricted based on role type in an effort to reduce item exposure and promote process integrity. Please see the member role description page for information on permissions.