Integrate OAuth 2.0 | Platform of Trust

Using OAuth 2.0 to access Platform of Trust. This guide is meant for developers who want to provide access to Platform of Trust APIs by implementing proper authorization flow for their users. In this guide you will find information on how to build basic authorization flow.

Get OAuth credentials

First of all, developers must make sure they have OAuth credentials that will be pass to the authorization server. To obtain OAuth credentials you have to create OAuth client or register an application. We have described it in Register an application guide. As a result, you must have at least the following data:

            
Client ID: cc4a3f95-ad8b-4048-842e-71d6ea810bc9
Client Secret: CQYP75kYXbmUgcKQZYg7q-2f_ndeJ-_9biEsbyLzUXQ
App access tokens: 
[
    {‘id’: ‘98e5c752-1a2b-4c78-b021-2b9e447c75af’, ‘token’: ‘413af71d-4d1e-4bbe-8b12-fe16f723ee9c’},
    {‘id’: ‘197969b8-32e0-47b1-a722-d82052dd5a53’, ‘token’: ‘f097cd95-9943-45e9-9311-159cb54712ca’}
]

This OAuth 2.0 credentials is required to start implementing authorization flow to Platform of Trust.

Implement the authorization process.

Usually, developers set up a backend application to communicate with Authorization server. In Platform of Trust, your application will be sending requests to Login portal. The portal will take care of some specific parts of authorization flow. In your application, you should have 2 necessary endpoints: login and exchangeToken.

            
# Routes and API endpoints

GET /login
GET /exchangeToken

The whole process should look like this:

Process diagram for creating authorization flow in the Platform with apps.

Login endpoint

/login endpoint's main purpose is to generate uri to the Login portal and provide required parameters that will be used by the login portal to authenticate users.

Required parameters are:

grant_type - Must be "authorization"
response_type - Must be "code"
client_id - ID of OAuth application you have gotten in step 1
redirect_uri - Url where users will be redirected to exchangeToken, also done in step 1
cancel_url- Fallback URL in case user decline authorization of your application

Optional parameter:

state - even though state is optional, it is recommended to generate one for each request. Enforce state validation during /exchangeToken to add additional security layer. Read more about state.

Example:

            
https://login-sandbox.oftrust.net/?grant_type=authorization&response_type=code&redirect_uri=https://world-sandbox.oftrust.net/api/exchangeToken&client_id=f77...jIn0=

Pseudo code:

            
auth_uri = my_app.generate_uri(
    grant_type=authorization, 
    response_type=code, 
    client_id=foobar, 
    redirect_uri=foobar.example.com/exachangeToken, 
    cancel_url=foobar.example.com, 
    state=state
)
my_app.redirect(auth_uri)

This URI will redirect a user to the Login portal, where authorization flow continues. At some point Login portal will generate an authorization code and redirect the user from Login portal to redirect_uri that you specified in this step. The purpose of it is to exchange the code for an access token and some other data.

Exchange token

This user request due to redirection from Login portal to your redirect_uri, should contain at least following params:

code - authorization code generated by the authorization server
subject - is ID of the created user, can be used to give OAuth client permissions to read your data
client_id - your OAuth application ID, can be used to validate state

Optional:

state - Should be validated. Parameter generated during /login request, optional but recommended to protect against CSRF.

Example:


https://foobar.example.com/exchangeToken?code=35z...304

But it is not there yet, we still need to provide additional data to Authorization Server

            
client_secret # OAuth application's secret you recieved in step 1
client_id # OAuth application's id you recieved in step 1 or client_id from initial user exchangeToken request
redirect_uri # redirect uri to validate, must be the same as provided previously in `/login`  
grant_type # Must be "authorization_code"
code # from initial user exchangeToken request 
state # from initial user exchangeToken request

So from your backend you need to send an API request to Login portal.

Example

            
curl --request POST \
  --url https://login-sandbox.oftrust.net/api/exchangeToken \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data code=5z9T7bBmbtbhRZ6xTF1NF \
  --data client_id=f773dafe-20c0-4a25-aa3e-9da0b81b9304 \
  --data redirect_uri=https://foorbar.example.com \
  --data grant_type=authorization_code \
  --data state=IxMzlhZjI5MzM4YzJiZGFmY2Q2Y2E1 \
  --data client_secret=ICI2ZDRiNTIxMzlhZjI5MzM4YzJiZGFmY2Q2Y2

With this request you should get following response's data:

            
{
    'access_token': 'eyJ…ANEs',
    'expires_in': 86400,
    'token_type': 'Bearer',
    'state': 'eyJ...fQ==',
    'refresh_token': 'XBR0l7f8eWspLlxmrk2UPjSNVX0zuC'
}

Note access_token should be passed with each request that requires Authorization to API. You can e.g. store this token to the client's cookie with httpOnly and secure flags. Then pass it to any Platform of Trust APIs in the Authorization header.


headers['Authorization'] = authorization_token

Pseudo code:

            
state = my_app.request.get('state')
code = my_app.request.get('code')

oauth_res = my_app.send_exchange_token_request(state, code, client_secret, client_id,  redirect_uri, grant_type)
my_app.validate_state(oauth_res.state)

bearer_token = f'{oauth_res.token_type} {oauth_res.access_token]}'
my_app.set_cookie('Authorization',
                   bearer_token,
                   max_age=oauth_res.expires_in,
                   httponly=True,
                   secure=True
                   samesite='Strict'
)

my_app.redirect(foo_bar_host)

For detailed documentations on Platform of Trust core APIs, Visit Platform of Trust API Documentation.

Improvement Suggestions? or a New Guide?

Tell us in GitHub