Standard SSO Integration (OAuth2)

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.

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 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:

Only after the above information is shared by the client and properly saved in Webassessor database can the SSO integration be tested.

Step 2: Client’s First Communication with Kryterion SSO

The client’s first communication with Kryterion SSO will be through this URL:

https://www.webassessor.com/form/ssoLogin.do?method=process&provider=PROVIDER&brand=BRAND

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.

Only after the above information is shared by the client and properly saved in Webassessor database can the SSO integration be tested.

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 authorize Webassessor to access its web services or make API calls through the Authorization URI, which will accept the following parameters:

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) is called back with the following parameters:

REDIRECT_URI?code=CODE&state=STATE

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

*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:

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!