Self service single sign on

Introduction

The case URL and case token returned by the Unified Create Case API are not secret or confidential, so when users navigate to the URL, they are required to have a valid logon session in the target line-of-business application, otherwise they are prompted to sign in. This is not desirable for customer self service. I.e. when claimant who have already authenticated on their insurance company's home portal is redirected to Scalepoint self-service application, prompting him to authenticate again can ruin user experience.

This document describes single sign-on scheme for end users (i.e. claimants) to access self-service functions of Scalepoint applications from company portal without entering credentials.

The scheme described is effectively anonymous access delegation, so it cannot be used to login company employees (i.e. claim handlers) into the line-of-business applications.

Flow

To prevent manual authentication step for the end user, instead of simply redirecting user to the URL returned by the Unified Create Case, the home portal backend must obtain a short-lived single sign-on token from Scalepoint Authorization Service and append it to the original URL as query string parameter with name "ssotoken". _This should be done immediately before the navigation, so these tokens cannot be obtained and stored beforehand. This means the portal should intercept navigation to Scalepoint self-service application with a local backend handler.

A request to get the token is made against the same token endpoint as in case of Client Authentication for Unified Create Case (i.e. https://accounts.scalepoint.com/connect/token), but using a custom OAuth grant named "urn:scalepoint:params:oauth:grant-type:resource-scoped-access" with the following parameters:

Key Value Description
grant_type urn:scalepoint:params:oauth:grant-type:resource-scoped-access Custom grant
client_id example: "future_insurance_sso" Client identifier
client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer JWT Bearer token assertion type
client_assertion example: "eyJ0eXA...FJcCY8gw" (shortened) JWT token signed with client private key, read Client Authentication on how to generate one
scope self-service:sso Self-service SSO scope
target example: "ci.9fe6672c-abc9-4ece-816a-622088b99a89" Case URL or case token returned by Unified Create Case

Just like with standard "client_credentials" flow, the token is returned in "access_token" parameter in JSON body and can look like "53b3c016ca0b84a87ccd1d0ccf5853d5".

So, this token must be appended to the original open case URL like this: https://sandbox.scalepoint.com/api/integration/dk/future/v1/case/ci.9fe6672c-abc9-4ece-816a-622088b99a89?sso_token=53b3c016ca0b84a87ccd1d0ccf5853d5 (or like this for claimant page https://.../Claimant/Page?auth=3512a27a-6b77-4cc5-ab77-2abee33af8c8&sso_token=53b3c016ca0b84a87ccd1d0ccf5853d5). This is the final link that the end user should be navigated to.

For technical reasons, "client_id" should be different from the one used for "client_credentials" flow. The certificate can (but doesn't have to) be the same.

Authentication endpoint

For authentication, Scalepoint provides two endpoints – one for production and one for everything else.

Production endpoint https://accounts.scalepoint.com/connect/token

Non-production endpoint https://sandbox-accounts.scalepoint.com/connect/token

Implementation

In Java, you can use https://github.com/scalepoint-tech/oauth-token-java-client like this:

ResourceScopedAccessGrantTokenClient ssoTokenClient = new ResourceScopedAccessGrantTokenClient(
    tokenEndpointUri,
    new JwtBearerClientAssertionCredentials(
        tokenEndpointUri,
        ssoClientId,
        keyPair
    )
);
String resource = localCase.getCaseToken();
String ssoToken = ssoTokenClient.getToken(new ResourceScopedAccessGrantParameters("self-service:sso", resource));
String ssoUrl = localCase.getScalepointCaseUrl() + "?sso_token=" + ssoToken;




see more about widget implementation: