Back to top
Vastuu Group

Building Apps in the Platform

Last updated: Feb. 6, 2020
|
Reading time: 4 min

Aim is that with help of this guide any developer with moderate amount of skills is able to create "hello digital twin" kind of app which uses one data product in sandbox environment.

You will learn,

  • how to build apps that utilize Platform of Trust authentication
  • and data products of various data providers. In the example we use one data product.
  • how to use sandbox environment in application testing.

To go through the guide, you'll need around 10-15 minutes of time.

1. Before you start to code

Keep in mind the following things before you start coding for your application:

1.1. Register yourself as a user of Platform of Trust

To maximize the use of Platform Of Trust, you must be logged in as a user. Currently, you are able to do it only via World of Trust .

1.2. Register your application to enable OAuth

Firstly you need to create oAuth client for your application. Thus the users of your application can log in to Platform of Trust. It is necessary for sending requests to protected API endpoints.

You also should be able to do it only from World of Trust UI. After registration of your application on the platform, you will get

Client ID, Client Secret, and Access Tokens.

NOTE! These values are crucial and shown only once, so you should save them immediately. Your application will use a Client ID, Client Secret and Access Tokens in various requests to Platform of Trust.

2. Implement User authorization

Users of your app must be logged in to Platform of Trust in order to perform most of the useful requests. We have implemented oAuth2 flow into the platform, so you only need to do the following steps:

Generate the authorization link. Initiate authorization flow by sending the request from a browser to your application backend.

The following are worthy to keep in mind:

GET /authorize: This should generate state and return redirection URL to login portal with necessary parameters

state: base64 encoded string to validate later

grant_type: authorization_code

response_type: is code

redirect_uri: is where to login portal will send code and state for validation and token exchange:

https://login.oftrust.net/? \
grant_type=authorization_code&response_type=code& \
redirect_uri=https://login.oftrust.net/api/exchangeToken& \
client_id=37e278c6-1af9-4537-b92d-af8609b6e1e7& \
state=eyJkIjogeyJyIjogImh0dHA6Ly9idWlsZGVyLmxvY2Fs....SZkZWQifQ==

Once browser gets this response, it should open url in the same browser's tab. User will be presented to login portal page where they can sign in or sign up.

3. Implement code exchange endpoint

When the user has logged in into Platform of Trust system, the login portal will send code and state to redirect_uri that you have specified in the previous step and when you created oAuth client. This endpoint needs to be implemented on a side of your application. So that you can exchange code for authorization token with another request to login portal API.

POST https://login.oftrust.net/api/exchangeToken:

'client_secret': <YOU_GET_IT_IN_STEP_"Register oauth client">,
'client_id': <YOU_GET_IT_IN_STEP_"Register oauth client">,
'redirect_uri': <TO_VALIDATE_URI (BTW do we validate it both in auhorization and exchange token steps?)>,
'grant_type': 'authorization_code', // MUST BE
'code': <code you get from login portal's request>,
'state': <state you get from login portal's request>

On success you should validate state. After that we recommend to write authorization token in client's cookie with HTTP response including following header:

Set-Cookie: 
Authorization="Bearer eyJ0eXAiOiJKV1OiJSU....ZuQ_gi6eLHOFhZi8xaChtg"; 
HttpOnly; Max-Age=86400; 
SameSite=Strict; Secure

Pay attention to HttpOnly, SameSite=Strict and Secure.

And redirect the user to the desired location with another header in the very same response:

Location: <URL where cookie with authorization token will be written>

4. Sending request to Platform of Trust API

For certain requests, you need to pass authorization token as a header Authorization to Platform of Trust API.

GET https://login.oftrust.net/api/me
GET <oftrust_api_url>/identities

Authorization: "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1N...5LCJzdWIiOiJmZDlaChtg"`

5. Select Data Product to use

In order to be able to fetch data products one of our data products providers you need to know in advance: product_code and parameters that will be processed by the data provider's system. In addition to that you need to specify Client ID, Client Secret and Access Tokens, which you get when created oAuth client in previous steps of this guide.

POST <Broker_API_URL>/fetch_data_product

Headers:

'X-Pot-App': <Client ID>
'X-Pot-Signature': <HMAC-SHA256(Access Tokens, request body)> 
'X-Pot-Token': <Auhtorization token NOTE! exclude "Bearer:" part> #optional

Body:

{
    'timestamp': <RFC-3339 Timestamp>,
    'productCode': <Product code e.g. "business-identity-test">,
    'parameters': <set of predefined parameters to pass to data provider>
}

E.g. parameters can be something like this:

{
    "businessId": "0831312-4"
}

Ready to explore more?

Try Platform Sandbox

Improvement Suggestions? or a New Guide?

Tell us in GitHub