Allow users to sign in to your App with their Tapico Identity.

Table of Contents

A key benefit to participating in a Tapico powered ecosystem is Single Sign-on (SSO). Once integrated users can sign in to your app with their Tapico Ecosystem ID. This allows users to seamlessly transfer from account servicer systems to your app.

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 via the Tapico Developer Portal 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.


1. Create an Application in the Tapico Developer Portal

Go to the Tapico Developer Portal and create an app. Give your app a name and a redirect_uri - users will be sent to the configured redirect_uri after authenticating with Tapico.

Save your app details and generate a client_id and client_secret. Keep your client_secret somewhere secure because it will only be displayed once. You will need to generate a new set of client credentials if you lose or misplace the old credentials.


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 document 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 users to in order to initiate an authorization request.

Authorization Request Parameters:

Parameter

Example

Description

client_id

{YOUR_CLIENT_ID}

REQUIRED. Unique identifier for your app

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.

  • openid – Indicates that an id_token should be returned in addition to an access_token

  • profile – Access to the user’s name and unique identifier

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

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

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

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 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=https://myapp.com/redirect
&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 app 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

test@email.com

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’ve now securely confirmed the user’s identity and you can log them into your app 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 a user is redirected to your application from a Tapico powered platform ecosystem (transferring users to your application via landingUri or registrationUri), we will also pass along a query parameter accountServicerId, which uniquely identifies the source platform where the user originated.

In order to correctly complete the SSO hand-off from the platform to your application, your application must replay the received accountServicerId parameter in the auth request parameters detailed in part 2. This informs the Tapico authorisation service to delegate to the specified partner platform to authenticate the user. 

In practice this will mean that your landingUri and registrationUri pages should be implemented to detect the presence of the accountServicerId query string parameter and can automatically redirect the user to the Tapico authorization request URI without needing to prompt the user to explicitly click a “Sign in with {Platform}” button.

Note that you may choose to take action after successfully receiving an id_token to perform any user correlation you wish to do within your application. Common use cases for this are; onboarding a new user to your application with the tapico id_token, or correlating Tapico users with existing users in your application.

5. Overview of the SSO interactions between the different parties