Single Sign-on with Tapico

Create a seamless bridge between an Account Servicer and your Application

Overview

In order to maintain the best possible experience for End-Users. Tapico Partner App Stores rely on Single Sign-on (SSO) to allow End-User's to sign in from their App Store and their associated digital proposition to your Application.

Overview of how SSO works for the App Store (Advisor = End-User)Overview of how SSO works for the App Store (Advisor = End-User)

Overview of how SSO works for the App Store (Advisor = End-User)

Sign in with Tapico conforms to the OpenID Connect specification and will work with any certified client library.

Getting set up requires:

  1. Create an Application and generate API credentials - client_id and client_secret.
  2. Send an Authentication Request to Tapico’s Auth Service.
  3. Handle the auth flow to get an id_token and/or access_token.
  4. Handle SSO request from Account Servicer.

How to Implement SSO with Tapico

 

1. Add a Redirect URL to your Application

Your ApplicationApplication - Your digital application that is represented on and consumes services from the Tapico Platform. should already be setup and have an associated client_id and client_secret. If you have not done this please see Create an Application and follow the steps.

As part of the initial setup or you can add it once your Application is created. Add a redirect_uri - the End-Users will be sent to the configured redirect_uri after authenticating with Tapico.

Toggle 'Enabled Sign in with Tapico' on the Basic Details page in the Tapico Developer Portal to expose the input fieldToggle 'Enabled Sign in with Tapico' on the Basic Details page in the Tapico Developer Portal to expose the input field

Toggle 'Enabled Sign in with Tapico' on the Basic Details page in the Tapico Developer Portal to expose the input field

 

2. Starting an Authentication Request

To initiate the OpenID Connect flow, you will need to send an authorisation request to Tapico’s Auth Service. There are a variety of certified client libraries in different languages that you can use to implement the flow: https://openid.net/developers/certified/

Our OpenID Discovery documents can be found here:

This contains all the configuration required to setup and initiate the SSO flow with Tapico. OIDC client library APIs will often support initialisation by simply supplying the OIDC Discovery URI. The client library will then handle configuration for you.

A typical authorization request looks like this:

https://auth.sandbox.tapico.io/oauth/auth
?response_type=code
&client_id={YOUR_CLIENT_ID}
&redirect_uri={YOUR_REDIRECT_URI}
&scope=openid%20profile%20email
&state={STATE_STRING}

This is the location that you need to redirect your End-User to in order to initiate an authorization request.

Authorization Request Parameters:

Parameter

Example

Description

client_id

{YOUR_CLIENT_ID}

REQUIRED. Unique identifier for your Application

response_type

code

REQUIRED. The authorization grant type being requested

For SSO Tapico only supports the value code i.e. the authorization code flow

scope

openid profile email

REQUIRED. The permissions that your app is requesting for approval. This must include openid at a minimum for SSO.
a) openid; Indicates that an id_token should be returned in addition to an access_token
b) profile; Access to the user’s name and unique identifier
c) email; Access to the user’s email address

redirect_uri

https://wwww.yourapp.com/callback

REQUIRED. Your URI that the user will be redirected to once authorization is completed. This must match the redirect_uris you have configured in the Tapico Developer Portal for your Application.

state

{any_string}

RECOMMENDED. The state parameter is used both to prevent forgery attacks as well as to allow your application to preserve some state which is replayed back to it upon success of the authentication at Tapico.

accountServicerId

{unique identifier}

OPTIONAL. Unique ID for an account servicer whom you wish to redirect the user to for authentication.

 

3. The Authorization Code Flow

3.1. End-User Authentication

When the End-User is redirected to Tapico via the URL mentioned above they will need to sign in to approve access to their identity information. If the request is approved the End-User will be redirected back to your redirect_uri with a short lived access code parameter. If you supplied a state parameter this will also be replayed back to you.

{YOUR_REDIRECT_URI}?code=xxxxxx&state={STATE_STRING}

📘

Your Application needs to extract...

Logic is required within the Application on the callback page redirect_uri, to extract the code and state query string parameters out of the URL in order they can be exchanged for tokens.

 

3.2. Retrieving the id_token and access_token

With the short lived access code you can request an id_token and access_token that will give you access to the End-User’s identity details, as defined by the requested scopes. This is done by making a POST request to:

https://auth.sandbox.tapico.io/oauth/token

With the following payload:

POST https://auth.sandbox.tapico.io/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=xxxxxx
&redirect_uri={YOUR_REDIRECT_URI}
&client_id={YOUR_CLIENT_ID}
&client_secret={YOUR_CLIENT_SECRET}

The response to this request will contain the id_token and access_token.

3.3. Accessing user claims from the id_token

The id_token returned contains the user’s identifying information in the form of a JWT (JSON Web Token). The id_token contains some standard claims as defined in the OIDC Specification.

Claim

Example

Description

iss

https://sandbox.tapico.io

Issuer - the issuer of the token

sub

{unique identifier}

Subject - Tapico Ecosystem Unique User ID

aud

{YOUR_CLIENT_ID}

Audience - Your appplication's client_id

exp

Expiration Time - Expiry time of the token

iat

Issued at Time - The issue time of the token

And depending on the requested scopes may also contain

Claim

Example

Description

email

[email protected]

The authenticated user's email address

family_name

Kusanagi

The authenticated user's family name

given_name

Motoko

The authenticated user’s given name

👍

Congratulations!

You have now securely confirmed the End-User’s identity using the details contained within the id_token.

 

3.4. Accessing /userinfo with the access_token

Some OpenID Connect client libraries expect to retrieve data about the authenticated user from the /userinfo endpoint instead of from the id_token as outlined above.

If this is the case then you can use the access_token to retrieve this data from the /userinfo endpoint - The specific URL you need to call is detailed in the discovery endpoints:

An example request looks like:

GET https://auth.sandbox.tapico.io/oauth/me
Authorization: Bearer {ACCESS_TOKEN}

The response will contain data about the authenticated user as requested by the provided scopes

 

4. Handle SSO Request from Account Servicer

When an End-User is redirected to your Application from a Tapico Partner App Store / Account Servicer proposition (transferring End-Users to your Application via landingUri or registrationUri), we will also pass along a query string parameter accountServicerId, which uniquely identifies the source platform where the End-User originated.

In order to correctly complete the SSO hand-off from an App Store / Account Servicer to your Application, your Application must replay the received accountServicerId parameter in the auth request parameters detailed in section 2. This informs the Tapico authorisation service to delegate to the specified partner Account Servicer to authenticate the End-User.

In practice this will mean that any pages within your Application that reference the Sign-Up URL or any deep links you have setup against your Application in the Tapico Developer Portal should be implemented to detect the presence of the accountServicerId query string parameter. To automatically redirect the End-User to the Tapico authorization request URI without needing to prompt the End-User to explicitly click a “Sign in with {Platform}” button.

Sign-Up URL and Deep Links can be configured on the Basic Details page in the Tapico Developer PortalSign-Up URL and Deep Links can be configured on the Basic Details page in the Tapico Developer Portal

Sign-Up URL and Deep Links can be configured on the Basic Details page in the Tapico Developer Portal

👍

What Next?

Now that you have confirmed the End-User’s identity. If their details match an existing End-User on your Application you can login them in. Alternatively you can register them as a new End-User using the details contained within the id_token.


Did this page help you?