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.

Authorisation workflows

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

All of the OAuth workflows below describe methods of acquiring an access token for use with your web service requests.

Implicit Grant (two legged)

1. A request (A) is made to an authorisation server provided by the web service you want to connect to (note that the authentication server and the web service end point may or not be the same.
2. The request is built to satisfy the requirements of the web service, some will ask for client id and access code others will require basic authentication headers. (see examples below for the most common types).

Once the web service is satisfied that the request is authenticated 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 a resource owner hosting the web services you wish to connect to Note that the authorisation server and the web service end point are not the same.
2. The resource owner will respond (B) (typically in a 302 redirect) either using the redirection URL provided in request (A), or a redirect configured with the resource owner.
3. The client is then redirected to an authorisation server (C) which will authenticate the request and ask the resource owner for a token to use in future requests. (D)
4. The resource owner responds with a long lived token (E) (and optional refresh token) which is then returned to IMan (F)
5. IMan will then use this access token in all requests to the web service (G) and the web service will respond (H).

setup screen

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

Each of the settings on this screen (except for id, description and trace) will have an impact on the OAuth token request and how the resultant token is applied to any future web service requests.

ID

A unique ID for this object.

Request Type (Header, UrlEncoded, Body, Proxied)

Each option (with the exception of proxied) determines how the Token Request Settings are used:

• Body
  • The token request settings are deemed to be inserted in the request body, when body is set the settings will be converted into either json or XML as defined by the Token Request MimeType.
• UrlEncoded (Default)
  • The token request settings will be added as parameters on the URL. When this type is selected the settings must be presented in a semi colon delimited key value pairs.
• Header
  • The token request settings will be added as HTTP headers. When this type is selected the settings must be presented in a semi colon delimited key value pairs.
• Proxied
  • This option provides the ability for the Authorisation Code flow by proxying the request through the Realisable Authorisation service.

Override Response MimeType

The MimeType the response is expected in. This will additionally affect how the Token Request Settings are serialised when Token Request Type is set to Body. Only application/xml and application/json are currently supported.

Description

A description for this authentication.

Authorisation URL

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

Token Endpoint URL

The URL to request an access token from.

Client Id

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

Client Secret

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

User Name

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

Password

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

Basic Authentication

Allows the use addition of a basic authentication header.

• User Name/Password
  • The basic auth string will be composed of the user name and password.
• Consumer Key/Secret
  • The basic auth string will be comprised of the client id and client secret.
• Neither (Default)
  • No basic auth header will be added.

Token request headers

Additional headers to be added to the token request. Configured using semi colon delimited key=value paired string.
This is typically left empty, but can be used where the OAuth webservice requires one or more static key/value header pairs.

Token request settings

The token request settings are a dynamic field whose use varies dependant on the Request Type configured. Configured using semi colon delimited key=value paired string. The token request settings can use the following replacement string. Each replacement string will be replaced with a value at runtime:

Name	Replaced value
%[client_id]	The value from the Client Id text box.
%[client_secret]	The value from the Client Secret text box.
%[guid]	A new GUID value. This can be useful for creating one-off nonces.
%[user_name]	The value from the User Name text box.
%[password]	The value from the password text box.
%[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”
%[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.

Refresh Request Settings

The token refresh settings are a dynamic field whose use varies dependant on the Request Type configured. Configured using semi colon delimited key=value paired string. The token refresh settings can use the following replacement string. Each replacement string will be replaced with a value at runtime, per the table above.

Token Request User Agent

A custom user agent string to be used for the token request. Typically this is left blank unless the OAuth webservice explicitly requires it.

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).

Error Path

The path used to retrieve a message in a response body in the event of an error. Where the return content type is JSON this property will be the JPath corresponding to the Token value. Otherwise, where the Path is Xml, this property should be XPath.

Connection Timeout

The number of seconds to wait until a connection times out.

Authenticated Headers

Additional headers to be added to an authenticated request. Configured using semi colon delimited key=value paired string.

The authenticated headers can use any of the tokens from the table above from the token request settings.

The header %[token] can be replaced with the access token.

Authenticated Header Token

The header name to be used for authenticated requests.

Authenticated Prefix

The prefix to use for the authenticated request header value. %[token] is replaced with the access token.

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

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

When a new window will open and send a request to the Authorise Url.

If the authorisation URL is valid, the screen will be redirected, ultimately to the logon screen of the service.

Test Button

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