Sign in with Tapico

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

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.

Getting set up requires:

Create an Application via the Tapico Developer Portal and generate API credentials - client_id and client_secret.
Send an Authentication Request to Tapico’s Auth Service.
Handle the auth flow to get an id_token and/or access_token.
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 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 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. 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 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.

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

Your App will require logic on the redirect_uri page to extract the code and state out of the URL so 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 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 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	[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’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 string 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 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
Correlating Tapico users with existing users in your application.