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 is experimental and not yet fully supported.

Description

A description for this object.

Token Endpoint URL

The URL to request an access token from.

Consumer Key Value

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

Consumer Secret Value

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.
%[user_name]	The value from the User Name text box.
%[password]	The value from the password text box.
%[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 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.

Token Path

The path used to retrieve the token from the token response. 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.

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

Error Path

The path used to retrieve a message in a response body in the event of an error.

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.

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.

Trace

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

OAUTH EXAMPLES

Salesforce

The salesforce API documentation: https://goo.gl/v365UT lists three supported authorisation workflows, Web server flow, User-agent flow and Username password flow.

As Both Web server and User-agent flows require a redirect URL (three legged) we will need to use the Username-password flow: https://goo.gl/Hvh8II

As is common to almost all two legged workflows; an application must first be registered with the resource owner (salesforce) so that it can generate client ids and secrets for use. https://goo.gl/3C5LgF

Once the client id and secret are known we can start setting up our OAuth settings in IMan.

The salesforce documentation describes the request:

Unfortunately the documentation neglects to mention how these parameters are to be passed; though a quick search through the documentation shows that Url-encoding is commonly being used.

The documentation also provides an example response:

{

  "id":"https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P",

  "issued_at":"1278448832702","instance_url":"https://na1.salesforce.com",

  "signature":"0CmxinZir53Yex7nE0TD+zMpvIWYGb/bdJh6XfOH6EQ=",

  "access_token":"00Dx0000000BV7z!AR8AQAxo9UfRcgKFmxOtvxjTrKW19ye6PE3Ds1eQz3z8jr3W7_VbWmEu4Q8TVGSTHxs"

}

We can see from the response that for a successful authorisation we require a request like this:

POST https://login.salesforce.com/services/oauth/token HTTP/1.1

Accept: application/json; charset=utf8

User-Agent: realsiable-iman-salesforce/v29.0

Content-Type: application/x-www-form-urlencoded

Host: login.salesforce.com

 

grant_type=password

client_id=[some client id]

client_secret=[some client_secret]

username=[some user_name]

password=[some password]

Configuring IMan to create an authorisation requests such as this is

straight forward and achieved via the IMan setup screen.

Lets have a look at the required request and where these options will map into the setup screen:

The token request settings:

client_id=%[client_id];client_secret=%[client_secret];grant_type=password;username=%[user_name];password=%[password]

Twitter

Twitter supports a number of OAuth authentication workflows, one of which is application only workflow: https://goo.gl/UNbKKx

As you can see the diagram on this workflow matches the implicit grant (two legged) description above:

An example token request for twitter is shown below:

POST http://api.twitter.com/oauth2/token HTTP/1.1

Authorization: Basic eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFMdzhpRUo4OERSZHlPZw==

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

 

grant_type=client_credentials

Configuring a token request in IMan

Setup screen: