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.
Sign in with Tapico conforms to the OpenID Connect specification and will work with any certified client library.
Getting set up requires:
- Create an Application via the Tapico Developer Portal and generate API credentials -
client_id
andclient_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:
- SANDBOX: https://auth.sandbox.tapico.io/oauth/.well-known/openid-configuration
- PROD: https://auth.prod.tapico.io/oauth/.well-known/openid-configuration
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 |
---|---|---|
| {YOUR_CLIENT_ID} | REQUIRED. Unique identifier for your app |
| code | REQUIRED. The authorization grant type being requested For SSO Tapico only supports the value code i.e. the authorization code flow |
| openid profile email | REQUIRED. The permissions that your app is requesting for approval. This must include openid at a minimum for SSO. |
| 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. | |
| {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. |
| {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
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 | 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 |
---|---|---|
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
/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:
- SANDBOX: https://auth.sandbox.tapico.io/oauth/.well-known/openid-configuration
- PROD: https://auth.prod.tapico.io/oauth/.well-known/openid-configuration
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.
5. Overview of the SSO interactions between the different parties


Updated 7 months ago