The Principles of IoL Token Exchange

This section describes the underlying principles of IoL token exchange.

IoL token exchange is modelled on the OAuth2 protocol, and has been adapted to better suit the underlying IoL security model, and to satisfy the IoL requirement of supporting bidirectionality with webhooks. 

In order for an application to be able to access the data belonging to a data owner it necessary for the data owner to grant access to the data requested by the application.

  • The application requests the types of data if wishes to have access to in the data owner’s IoL account.  The data owner is presented with information about the extent and type of the data being requested, along with the name of the application requesting access.  For example, the application might request access to TradeUnit and TransportStatus information belonging to the data owner.
  • The data owner accepts the request for access to the indicated data types.  Alternatively, the data owner can reject the request for data access.
  • A secure key exchange between the IoL and the application now occurs.  To grant access to the data owner’s data, an access token is generated, which is used in subsequent calls to the IoL API when the application requests data.  This access token, along with notification of application and connection ID parameters are sent to the application.  In response the application returns a bearer token which is used by IoL to send a notification to the application via webhooks.

To facilitate this token exchange mechanism, the IoL token exchange relies on the implementation of:

  • Registered application – A registered application must have been created and the client ID noted.
  • Connection URL – Is built dynamically by the application and is published to a data owner by the application developer.
  • The provision of an Authorization Callback URL endpoint by the application for the handle token exchange.

The following sections describe the IoL token exchange mechanism in more detail

Application Registration

A registered application is created by an application developer in IoL using the IoL Admin Portal.  Before an application or a data owner can participate in token exchange, a registered application must be created.  The essential aspects that a registered application defines are

  • Scope – this is the set of Iol entities that can be accessed by a connecting application.
  • Authorization URL – the callback URL IoL uses to call the application during token exchange
  • Webhook URL – the callback URL to be used by webhooks (if the scope permits the creation and use of webhooks)
  • Client ID – is a unique ID and is generated when an application is registered.

Scope

Within the IoL token exchange mechanism, scopes are indicated by data entity name and the type of operation that is permitted.

The general format of a scope is:

scheme.entity.operation

Where:

schemeSupported schemes: api – a scope to access an API entitywebhook – a scope specifying a webhook for the specified entity  
entityIoL entity types: assetasseteventlegalpartylocationtradeunittransportinstructiontransportrequesttransportrequestaccepttransportstatus

operationIoL entity operation: read – Read-only operation on the specified entity.  When combined with the webhook scheme, it signifies a push notification with the supplied webhook.edit – Read/write operations on the specified entity

When creating a registered application, the application developer specifies the set of scopes that are supported.  An application connecting to a registered application can specify to connect to one or more of these scopes, up to the limit imposed by the scopes associated with the registered application.  If Connection URL requests more scopes than a registered application supports, then only those scopes requested and supported by the registered application will be configured for the connection.

If the Connection URL does not request specific scopes, then it is assumed by IoL that the application wishes access to all scopes defined by the registered application to be granted by the data owner.

As an example – suppose a registered application has these scopes assigned to it:

Registered Application ScopesRequested Scopes in
Connection URL

Grant access scopesDescription
Example 1  
api.tradeunit.edit
webhook.tradeunit.read
api.transportrequest.read
api.transportstatus.edit
api.location.read  
api.tradeunit.edit
webhook.tradeunit.read
api.transportrequest.edit
api.tradeunit.edit
webhook.tradeunit.read
api.transportrequest.edit
All request scopes in the Connection URL are supported by the registered application.  The data owner will grant access to these scopes.

Example 2  
api.tradeunit.edit
webhook.tradeunit.read
api.transportrequest.read
api.transportstatus.edit
api.location.read  
api.tradeunit.edit
api.transportrequestaccept.edit
webhook.legalparty.read
api.tradeunit.editOnly one of the scopes in the Connection URL is supported by the registered application.  The data owner will grant access to this one scope.

Example 3   
api.tradeunit.edit
webhook.tradeunit.read
api.transportrequest.read
api.transportstatus.edit
api.location.read  
(no scopes in Connection URL)api.tradeunit.edit
webhook.tradeunit.read
api.transportrequest.read
api.transportstatus.edit
api.location.read  
If a Connection URL does not define specific scopes, then IoL assumes that the connection wishes to access all scopes defined by the application.

Application Registration in IoL Admin Portal

The IoL Admin Portal provides an application registration screen:

FieldDescription

NameName of the registered application.

DescriptionA description of the registered application.

ScopesThese are the set of scopes that the registered application can request.

Authorization Callback URLThis is the URL used during token exchange to which IoL sends the generated access token.  In reply, the application creates and returns a bearer token to IoL.

Associated Entity Webhook URLThis URL is specified if the application wishes to receive details of entity association changes.  This field is optional.  If not specified, no changes to entity associations will be posted to the application.
 
Scope WebhooksEach webhook scope gets an associated webhook.  The registered application specifies the webhook URLs.  The application-generated bearer token is used to authenticate with the application when IoL posts a message to these URLs.

Token Exchange


The following diagram illustrates the sequence flow between an application and IoL.

Data Owner Account

During the grant access and token exchange process, the following are created in the data owner’s IoL account space by the IoL API:

Access tokenThis is the token generated by IoL.  The token entitlements are derived from the scopes requested by the application connecting to the data owner’s data and which are shown to the user in the grant access screen. 

WebhookIf the request Connection URL contains webhook scopes, the relevant webhooks will be created in the data owner’s account.  Each webhook will have associated with it the token returned by the application during the token exchange process.  The URLs specified in the registered application are assigned to the webhooks.

Associated Entity WebhookIf the registered application specifies an Associated entity webhook URL, then a webhook using the supplied URL and the token returned by the application is assigned to it.

Application

During token exchange IOl sends the generated access token to the application.  In addition, a number of other parameters are provided, e.g. state, client ID, which the application can use for validation purposes.

The application responds with a bearer token which is assigned to the webhooks created in the data owner’s account.  This token is used to authenticate calls the webhooks by IoL.

There are no changes to the application developer’s account during token exchange.

Managing Connections

When an application wishes to obtain access to specific data owned by the data owner, the data owner must grant access to the data.  A Connection URL is published to the data owner by the application developer, and on using the Connection URL the data owner can grant access to the requested data.  Alternatively, the data owner can deny access to the data.

Connection URL

The application creates a Connection URL with this format:

https://www.anydomain.com/oauth/connect?client_id=GxMTljAiSUmUpolLyTYKtA&state=request6065&scope=api.transportstatus.read+api.tradeunit.edit+webhook.legalparty.read&connection_name=My%20Connection%20Request&requesting_party=http://www.anydomain.com/l.abcde12345 

Where:

https://www.anydomain.com/oauth/connectIs the IoL end point

client_idIs the client ID of the registered application.  It is extracted from the application registration panel of the IoL Admin Portal.
stateAn identifier that identifies the request from the requesting application – this is used to enable the application to identify the response with the access token from IoL. It is typically used to identify a user account in the application. Limited to a maximum length of 35 characters.
scopeIdentifies the read/write data access scope and whether webhooks are to be created for the connection. api.transportstatus.read
api.tradeunit.edit
webhook.legalparty.read

If no scopes are specified in the Connection URL, then all scopes from the registered application will be requested – the data owner will then be requested to grant access to all of these scopes.

connection_nameThe name of the connection. If the name is not supplied, the connection approval screen will display a textbox for manual entry of the connection name. Limited to a maximum length of 70 characters.
requesting_partyThe IOL account ID of the entity requesting connection to the data owner’s data.  Optional.

Distributing the Connection URL

The Connection URL is a plain text string and can be distributed to a data owner by, for example, email, text message. 

IoL Connection Grant Access Consent

When the data owner enters the Connection URL into a browser an access consent screen is displayed which requests approval by the data owner to the requested data.

If the data owner is not currently logged in to the IoL Admin Portal, then a login screen is displayed before showing the accept access grant screen.

The data owner is requested to consent to the data access request, thereby granting access to their data for the requesting application.  The data scopes requested details are displayed in a less technical format in the access grant screen.  

In this example, the application connecting to registered application AssocTest2, is requesting access to.

Text

ScopeDescription
Edit TransportInstruction

api.transportstatus.editRead and write of TransportInstruction entities.
TransportInstruction Push Notification

webhook.transportstatus.readRead and write of TransportInstruction entities.
Edit Asset

api.transportstatus.editRead and write of Asset entities.
Asset Push Notificationwebhook.transportstatus.readReceive a webhook notification for an Asset entity.

Note: IoL displays the requested webhook scope as ….Push Notification in order to clarify the purposes of the requested scopes for data owner users of a less technical background.

Filtering Data Access

Pressing the control View and configure data access in the consent screen allows the filtering and exclusion options to be configured.  Configuring filters is an optional step.

Here we see filters and exclusion options have been configured.  The filters refer to the field names of the respective entity type.

Settings for a …Push Notification scope will modify the relevant IOL webhook, configuring the filtering and exclusion filters for the webhook.

Settings for Edit…. Scopes will set the filtering and exclusions options for the token.

The filtering and exclusion settings can be viewed by inspecting the relevant webhook and/or token created by IoL as part of the OAuth2 protocol.

Managing Granted Connections

A data owner can manage granted connections in the IoL Admin Portal. 

If a granted connection is revoked, then all further access to the data owner’s data is denied to that connection. 

Revoke a Connection

To revoke a connection, select the Applications | Authorized item in the navigation panel of the IoL Admin Portal.

Click the Revoke Access button to revoke the connection.

On connection revocation IoL performs the following actions:

  • Deletes the webhooks associated with the data owner’s account
  • Deletes the access token associated with the data owner’s account
  • Marks the connection as revoked internally