Custom 2-legged OAuth with Oracle Integration Cloud Service (ICS)

Oracle ICS provides OAuth authentication for REST APIs using a curl-like syntax. Given the many implementations of OAuth are not exactly to spec, syntax pitfalls sometimes occur. ICS provides the flexibility configure using regex the values needed to pull out the tokens from the JSON payload.

This flexibility allows us to integrate with the gamut of OAuth-compliant REST APIs in the consumer apps market.

Today, we’re going to use TrackVia (https://developer.trackvia.com/livedocs)

TrackVia is pitched to LOB users as a low-code alternative to spreadsheets, legacy databases and complicated enterprise systems to track, manage and automate critical business processes or operational workflows with greater efficiency, speed and ease.

*Note: From my assessment of the TrackVia API, it provides a significant amount of flexibility to developers who want a simple way to authenticate through parameters. The documentation is great for ease of integration, but doesn’t exactly match OAuth security spec. ICS, however, being an Enterprise Integration utility enforces the spec match. So I had to prod around the curl syntax to get the right fit.

TrackVia implements 2-way OAuth to retrieve data in its views.

1. Get Access Token: /oath/token

https://developer.trackvia.com/livedocs#!/oauth/getAccessToken_post_0

2. Get Records in a Given View: /openapi/views/{viewId}

https://developer.trackvia.com/livedocs#!/views/getRecordsInView_get_0

Curl Commands

Since ICS configurations utilise a curl-like like syntax, let’s have a look at what these queries would look like in curl commands.

*Note: I recommend Postman to start with playing with to explore APIs.

The 2 curl commands are:

1. Get Access Token:

curl -X POST -v https://go.trackvia.com:443/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'client_id=TrackViaAPI' \
-d 'grant_type=password' \
-d 'username={your_username}' \
-d 'password={your_password}'

*Note: I have added -v for verbose and Content-Type in the header to ensure HTTP compliance.

2. Get Records in a Given View:

curl -G -v https://go.trackvia.com:443/openapi/views/999 \
-d 'user_key={your_userkey}' \
-d 'access_token=TEAEj2PPS5M5H0FbDplhJFnVz2aHLPJLpwtYGZw7NBXaYmkvRrQxrqyryHzMkTwWlVHcFq9ar5T9qkiZ1e%2F67xalXogDeeaOxcp4byairjyiPGe%2FC9Vra%2Bf2mukgFQvJ111gFHJBC8TRUv9EQH%2BFrHEzN7hiJmvDJ8bLMnfoC229HIFWsQ43%2F2oCuzelcVNRSPshGoVxoMufOSze3f37dlHv5BLZGz%2BkPhGjgNJM5E0%3D'

In the above that you are passing access tokens in the clear through a query. ICS only accepts OAuth security-compliant queries. This means the token should be passed through headers instead.

To have a OAuth-compliant curl query, we should do this for the 2^nd call.

curl -G -v https://go.trackvia.com:443/openapi/views/999 \
-H "Authorization: bearer ArD5mAtunM0Mh6YHjnIfB6MPRMc7IADw+USCL8JFW2oqr7n5rn+gmsxRgzgXT48EHQCFkFiYgYQpuSEk1yV4AIu5tfM3e0JncpvTmk1dqRsPdWMvCUY+04jtEinKjVWylw+m4gVgUvP8g/8zRxAbQllX68ByKcM6F9yt9H+LYnMVDpZL0YvoQdBrfr1rYaC6goDAZKjljUwKFBDYG4SyIO5JU0t2+5EwVEPf9Ebu7/g=" \
-d 'user_key=a20b4cb5c02cf424df3aaa16f65ad8db'

*Syntax Alert: Don’t get caught in URL-encoding hell. If you are passing tokens through a parameter query, you will need to URL-encode them. Whereas through the header you would use the exact token in the JSON response.

Configuration in ICS

Create a REST Adapter Connection

You have the flexibility to select Trigger, Invoke or Trigger and Invoke here.

Since TrackVia has no triggering capabilities, but provides a passive REST API that can be called, we will just select Invoke here.

Click on Configure Connectivity

Enter the TrackVia information. We will use https://go.trackvia.com:443 as the REST Base.

Click on Configure Security

We will select OAuth Custom Two Legged Flow.

*Syntax Alert: Note the references of how to fill in these fields. The format is curl-style and might be confusing to some people as the syntax is not exactly the same.

Let’s have a look at [Access Token Request]. Our curl statement is

curl -X POST -v https://go.trackvia.com:443/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'client_id=TrackViaAPI' \
-d 'grant_type=password' \
-d 'username={your_username}' \
-d 'password={your_password}'

This is the money-line, translating to the curl command above into your ICS [Access Token Request] field:

-X POST -H "Content-Type: application/x-www-form-urlencoded" 
-d 'client_id=TrackViaAPI&grant_type=password&username={your_username}&password={your_password} https://go.trackvia.com:443/oauth/token

Make sure to:

1. Enter the Content-Type in the header to ensure HTTP compliance. Your authentication will fail if you do not use this.
2. Enter the full URL to get the token as ICS will not concatenate it with the REST Base previously entered.

We retrieve a JSON payload from the curl call:

{
"value": "plT72t+ikfmirfNFKaUQsmsTBi9TjJe+m6bB6k48YfSneMht3eV6qIatSn+bE9j11bEzkrBfl34TBMms6Bx0CQvAx0Z0NECJJdJS/V8ogoVaW5hs5LX1oi4hF4E73rdL6UabyGfcpyQjoONbzdmxC2dGxoCFX4cz1OzEKpvqwG4XmoaiktAjeBAeMCLJvRpnhoOkIczKJlE3EQna3adUNCYC5byEXkxrW/nOLP05CXc=",
"tokenType": "bearer",
"refreshToken": {
"value": "eqD9A2egkpuiQOL4EWszGpxRBrDh45E2IkLP5RlaUi1uibwxIV+a9PrPWqQ++FUBVPThRnUuqov5Bbo08jN3flDnXslVg6MwU6KoA/7VN/RPPfqPNQEtjp4ySXaVEWhC32xYLbYQp8+yKKdzmf8e1jDp4x6rumejgg9DHbcVLK6D9Z5G6dbr0T9J7QHhpM0X",
"expiration": "2085-02-04T08:04:19.365+0000"
},
"expires_in": 299,
"expiresIn": 299,
"expiration": "2017-01-17T04:55:12.368+0000",
"scope": [
"read",
"trust",
"write"
],
"apiVersion": "9.82",
"pusher_application_key": "ab36d6081579876e9801",
"access_token": "plT72t+ikfmirfNFKaUQsmsTBi9TjJe+m6bB6k48YfSneMht3eV6qIatSn+bE9j11bEzkrBfl34TBMms6Bx0CQvAx0Z0NECJJdJS/V8ogoVaW5hs5LX1oi4hF4E73rdL6UabyGfcpyQjoONbzdmxC2dGxoCFX4cz1OzEKpvqwG4XmoaiktAjeBAeMCLJvRpnhoOkIczKJlE3EQna3adUNCYC5byEXkxrW/nOLP05CXc=",
"accessToken": "plT72t+ikfmirfNFKaUQsmsTBi9TjJe+m6bB6k48YfSneMht3eV6qIatSn+bE9j11bEzkrBfl34TBMms6Bx0CQvAx0Z0NECJJdJS/V8ogoVaW5hs5LX1oi4hF4E73rdL6UabyGfcpyQjoONbzdmxC2dGxoCFX4cz1OzEKpvqwG4XmoaiktAjeBAeMCLJvRpnhoOkIczKJlE3EQna3adUNCYC5byEXkxrW/nOLP05CXc=",
"refresh_token": "eqD9A2egkpuiQOL4EWszGpxRBrDh45E2IkLP5RlaUi1uibwxIV+a9PrPWqQ++FUBVPThRnUuqov5Bbo08jN3flDnXslVg6MwU6KoA/7VN/RPPfqPNQEtjp4ySXaVEWhC32xYLbYQp8+yKKdzmf8e1jDp4x6rumejgg9DHbcVLK6D9Z5G6dbr0T9J7QHhpM0X"
}

Key in the JSON parameter matching what you would like to extract from the payload in the [$access_token], [$refresh_token], [$expiry], [$token_type] fields. The API uses regex to allow a few options to retrieve the same key.

For [access_token_usage], note the command in curl to utilise the token to then access the API:

curl -G -v https://go.trackvia.com:443/openapi/views/999 \
-H "Authorization: bearer ArD5mAtunM0Mh6YHjnIfB6MPRMc7IADw+USCL8JFW2oqr7n5rn+gmsxRgzgXT48EHQCFkFiYgYQpuSEk1yV4AIu5tfM3e0JncpvTmk1dqRsPdWMvCUY+04jtEinKjVWylw+m4gVgUvP8g/8zRxAbQllX68ByKcM6F9yt9H+LYnMVDpZL0YvoQdBrfr1rYaC6goDAZKjljUwKFBDYG4SyIO5JU0t2+5EwVEPf9Ebu7/g=" \
-d 'user_key={your_userkey}'

You would utilise:

-H Authorization ${token_type} ${access_token}

OR

-H Authorization: ${token_type} ${access_token}

*Syntax Alert: Note in the curl syntax, we use “Authorization: bearer” in the header. You can use “:” or none after Authorization. In this case, you can even leave to default.

Select Test and it is successful!

You are now ready to map your Custom OAuth REST connection to some integrations.

Want to test it out? Goto https://cloud.oracle.com/integration and hit [Try It] to get a trial account.