Skip to main content

Deep Links SSO Integration (OAuth2)

A step-by-step integration mechanism into the Webassessor SSO implementation using the OAuth2 standard.

Article_Divider.png

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

DeepLinksSSOIntegrationOAuth2.jpg

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
“-” sign to parse the incoming parameters.

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.
Expected Values: KTN, OLP, NP.

CURRENCY

Currency of the amount.
Accepted Values: USD, EUR, GBP, JPY, CAD, AUD

PRICE

Price of the exam. If price is not applicable then a default of “0.00” should be sent.
Example: 23 or 23.0 or 23.00

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:

 

  1. Send the User Profile object back to Webassessor.

  2. 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.
{
“login”:”exampleCand1″,
“firstName”:”Example First Name”,
“lastName”:”Example Last Name”
}

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.
Only possible options:
LOGIN
USER-ID
EMAIL

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.


We’d Appreciate Your Feedback!

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.