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.
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.
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:
/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 1redirect_uri
- Url where users will be redirected to exchangeToken, also done in step 1cancel_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.
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 serversubject
- is ID of the created user, can be used to give OAuth client permissions to read your dataclient_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.