OAuth2 Authentication

what is oauth2

OAuth 2.0 is an authorisation framework, typically enabling a third-party application access to a web service. Access can be granted via a number of methods, either on behalf of the service by orchestrating an approval process between the user and the web service (think Facebook app authorisation or mobile applications) or by allowing the third-party application to obtain access on its own behalf.

OAuth 2 is defined in RFC: https://tools.ietf.org/html/rfc6749 and replaces the OAuth 1.0 protocol. OAuth 1.0 is not supported by IMan.

On this page

Authorisation flows

In order to access the protected resources of a web API, IMan must authenticate with that service and acquire an access token to be used with each request.

There are numerous OAuth flows, however these are divided into two basic forms: two-legged or three-legged. IMan supports both.

two legged - Resource Owner, Client Credentials (and Implicit)

Both flows are similar in nature, where a set of credentials are provided to an authorisation server where a token is returned and used to access the resource server.

  1. A request (A) is made to an authorisation server provided by the web service you want to connect to. In the case of an implicit flow the authentication server and the web service end point are the same.
  2. Different services will require different sets of credentials. Some will want a client id and secret, other services may want a basic authentication header.
  3. If the request is successful it will respond with an access token response (B), an example is shown below:

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

Cache-Control: no-store

Pragma: no-cache

 

{

  "access_token":"mF_9.B5f-4.1JqM",

  "token_type":"Bearer",

  "expires_in":3600,

  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"

}

IMan will then use this access token in all requests to the web service (E) and the web service will respond (F).

Authorisation Code (three legged)

  1. A request (A) is made to the authorisation service via the IMan Authorisation server.
  2. The IMan Authorisation server forwards the request (B) to authorise URL.
  3. The authorisation service will redirect the request (C) to the authorisation service's login.
  4. The end user will login and consent (D) access to IMan.
  5. The authorisation service will make a request (a callback) (E) to the IMan Authorisation service with a short lived authorisation code.
  6. The IMan Authorisation Service will make a request to the Token Request URL (F) exchange the short lived authorisation code for an access token and possible refresh token (G).
  7. The returned access is returned to IMan (H).
  8. IMan makes a request (I) to the resource server with the returned access token.
  9. The resource server returns a response (J).

OAuth setup

The screen is divided into two panes: a configuration pane on the left and a preview/results panel on the right.

Typical Setup Workflow

  1. Enter an OAuth ID and description.
  2. Select the appropriate flow type (2-Legged or 3-Legged).
  3. Configure the Token Request URL and body parameters with your provider's details.
  4. Add any required custom headers (e.g. Authorization: Basic ...).
  5. Set up the Authenticated API Request Headers (e.g. Authorization: Bearer %[token]).
  6. Review the sequence diagram in the right pane to verify the flow.
  7. Enter a Test URL and click Test to validate connectivity.
  8. (3-Legged only) Click Authorise to complete the browser-based authorisation.

Configuration Pane

The OAuth Setup screen allows you to configure a token request:

ID

A unique ID for this object.

Description

A corresponding description.

Request Type

  • 2-Legged (Resource Owner, Client Credentials and Implicit)
    • Some credentials are provided to a server (either an authorisation or the resource server directly) where a token is returned for on-going access.
  • 3-Legged (Authorization Code)
    • The authorisation code flow is used.
    • This can be augmented with

Authorisation URL (3-Legged only / Authorisation Code)

The  URL to initiate the authorisation request for Authorisation Code flow.

Request Tokenisation

The Authorise Url can be tokenised using any of the key / values in the Token Request settings. The following Url uses the client_id tokenisation. 

https://login.myservice.com/oauth2/authorize?response_type=code&client_id=%[client_id]

Token Request URL

The URL to request an access token from.

Token Request Path

It is assumed that all token request responses are in JSON form.

The value here is the JPath pointing to the returned access token. Typically this is the access_token property at the root object.

{
  "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "token_type":"Bearer",
  "expires_in":3600,
  "scope": ....
}

Token Request Body Type

This specifies the body type of the token request.

  • JSON Body
    • When specified will send a request where the body is JSON formatted.
  • Form Url Encoded
    • The authorisation code flow is used.

The client_id supplied by the resource owner. Can be inserted into the token request settings using %[client_id]

Token Request Settings

Each of the key / pair values listed in the token request settings will be sent in the body. Default parameters are pre-populated based on the selected flow type.

Token Key / Value Edit

Adding/editing values will display a popup where the key and the values can be selected or entered.

The first drop down allows you to pick either a well known request value OR allows you to enter a value not in the list.

The second drop down you can either select from an auto-generated value OR enter the specific value.

Name

Replaced value

%[client_id]

The value corresponding to the client_id from the Token Request settings. If no client_id is defined an empty string is returned.

%[client_secret]

The value corresponding to the client_secret from the Token Request settings. If no client_secret is defined an empty string is returned.

%[code]

The authorisation code (3-Legged flow) provided in the OAuth callback. This value is typically provided during the initial access token request.

%[redirect_uri]

The redirect uri (3-legged flow). This resolves to the Realisable Authentication server: https://authorisation.realisable.co.uk/OAuthCallback

%[refresh_token]

The current refresh token.

%[guid]

A new GUID value. This can be useful for creating one-off nonces.

%[user_name]

The value corresponding to the user_name from the Token Request settings. If no user_name is defined an empty string is returned.

%[password]

The value corresponding to the password from the Token Request settings. If no password is defined an empty string is returned.

%[random_base64]

A random string encoded with base64. This can be useful for creating one-off nonces.

%[random_int]

A random 32-bit integer. This can be useful for creating one-off nonces.

%[random_smallint]

A random 16-bit integer. This can be useful for creating one-off nonces.

%[random_string]

A random lower case 12-character string. This can be useful for creating one-off nonces.

%[timestamp]

The current date and time of the server in the local timezone in the server’s configured timezone formate.g. “16/07/2015 17:08:10”

%[timestamp_unix]

The number of seconds from the unix epoch (1970-01-01 00:00:00).

%[utc]

The date and time expressed as UTC:

“2015-07-16T16:08:10.655Z”

If a date is required, the utc is the more likely to be required.

%[token_url]

The token endpoint url.

%[token_path]

The token path.

%[error_path]

The error path.

Using the following values will generate the following requests.

client_id

myClientId

client_secret

theCorrespondingSecret

grant_type

client_credentials

redirect_uri

%[redirect_uri]

JSON Body

{
  "client_id":"myClientId",
  "client_secret":"theCorrespondingSecret",
  "grant_type":"client_credentials",
  "redirect_uri": "https://authorisation.realisable.co.uk/OAuthCallback"
}

Form Url Encoded

Header
Content-Type: application/x-www-form-urlencoded
Body
client_id=myClientId&
client_secret=theCorrespondingSecret&
grant_type=client_credentials&
redirect_uri=https://authorisation.realisable.co.uk/OAuthCallback

Token Request Headers

Each of the key / pair values listed in the token request headers will be sent as headers (in conjunction with the body) in the token request.

This functions in the same manner as the token request body.

Persist Token

If the authentication process provides a token with a long expiry date (a month, a year) the token can be saved to the IMan database, where each subsequent request uses the saved token instead of requesting a new one.

Persistent Token

The saved token when the token is persisted (see above).

ReFresh Token Settings (3-Legged only / Authorisation Code, when Persist Token is unchecked)

Requests will be made to the same url as the Token Url.

Configure the body parameters sent when refreshing an expired token. These follow the same key-value format and support the same substitution tokens as the token request body.

The refresh token flow is invoked when either the token in a long running session expires OR at the start of a new sesssion.

Authenticated API Request Headers

Headers that are automatically added to every authenticated API call made using this OAuth profile.

A typical setup includes Authorization header with the %[token] placeholder (e.g. Authorization: Bearer %[token]).

Connection Timeout

Maximum time in seconds (0–120) to wait for a response during token requests and test connections. Default is 20 seconds.

Test URL

Used in conjunction with the Test Button, this is a URL to issue a a GET request to test the Authentication.

Trace

Will log out trace information to a log file located in c:\IMan\debug\OAuth.txt

AUTHORISATION Button (3-Legged only / Authorisation Code)

When the authorisation button is enabled when the request type is set to 3-Legged / Authorisation Code flow.

When pressed steps a. through h. of the authorisation code flow (above) will be initiated.

Assuming the authorisation url is valid, the screen may redirect to the authorisation service's login screen and following consent screen.

Following consent and successful token exchange between IMan Authorisation service and the authorisation service a corresponding success / failure screen will be displayed.

Test Button

Will test the supplied details can successfully authenticate using the Test Url.

Preview & Results Pane

The right pane contains two tabs: the preview and test results.

OAuth Flow Preview

Displays a live sequence diagram that visualises the configured OAuth flow. The diagram updates automatically as you change settings, showing:

  • The participants involved (Client Application (IMan), Token Server, API/Resource Server).
  • The request/response messages including URLs, headers, and body parameters.
  •  The complete end-to-end authentication and API call sequence.

Test Results

Clicking the test button will execute the OAuth connection and attempt to make a GET request to the Test Url with the returned access token. The test results show :

  • Success/failure status.
  • Response details from the token endpoint.
  • Error messages if the test failed.