Web Services Hub » OAuth 2.0 » Flows » Using OAuth 2.0 for Installed Applications

Using OAuth 2.0 for Installed Applications

The Web Service OAuth 2.0 endpoint supports applications that are installed on a device (e.g. Mobile, Mac, PC). These applications are distributed to individual machines, and it is assumed that these applications cannot keep secrets. These applications may access a Resourece while the user is present at the application or when the application is running in the background for long periods of time without direct interaction with the user. This flow requires that the application has access to the system browser or the ability to embed a browser control in the application.

Overview

The sequence is similar to the one shown in the Using OAuth 2.0 for Web Server Applications, but there are three exceptions:

  1. When registering the application, you specify that the application is a Installed application. This results in a different value for the redirect_uri parameter.
  2. The client_id and client_secret obtained during registration are embedded in the source code of your application. In this context, the client_secret is obviously not treated as a secret.
  3. The authorisation code is returned to your application in the title bar of the browser and body of the web page.

This sequence starts by redirecting a browser (system browser or embedded in the application as a web view) to a SW Combine URL with a set of query parameters that indicate the type of Resource access the application requires. Like other scenarios, SW Combine handles the user authentication and consent, but the result of the sequence is an authorisation code. The authorization code is returned in the title bar of the browser and body of web page.

After receiving the authorisation code, the application can exchange the code for an access token and a refresh token. The application presents its client_id and client_secret (obtained during application registration) and the authorisation code during this exchange. Upon receipt of the refresh token, the application should store it for future use. The access token gives your application access to a Resource.

Forming the URL

The URL used when authenticating a user is https://www.swcombine.com/ws/oauth2/auth/. This endpoint is accessible over SSL, and HTTP connections are refused.

Endpoint Description
https://www.swcombine.com/ws/oauth2/auth/ This endpoint is the target of the initial request for an access token. It handles active session lookup, authenticating the user, and user consent. The result of requests of this endpoint include access tokens, refresh tokens, and authorisation codes.

The set of query string parameters supported by the Web Service Authorisation Server for web server applications are:

Parameter Values Description
response_type code Determines if the OAuth 2.0 endpoint returns an authorisation code. For web server applications, a value of code should be used.
client_id the client_id obtained from the Web Service console Indicates the client that is making the request. The value passed in this parameter must exactly match the value shown in the Web Service console.
redirect_uri The redirect_uri values registered at the Application Registration Form Determines where the response is sent. The value of this parameter must exactly match one of the values registered value in the Web Service console. You may choose between urn:ietf:wg:oauth:2.0:oob or an http://localhost port. See Choosing a Redirect URI for more details.
scope space delimited set of permissions the application requests Indicates the resource access your application is requesting. The values passed in this parameter inform the consent page shown to the user. There is an inverse relationship between the number of permissions requested and the likelihood of obtaining user consent.
state any string Indicates any state which may be useful to your application upon receipt of the response. The Web Service Authorisation Server roundtrips this parameter, so your application receives the same value it sent.

An example URL is shown below.

https://www.swcombine.com/ws/oauth2/auth/?
scope=character_read%2Ccharacter_write&
redirect_uri=urn:ietf:wg:oauth:2.0:oob&
response_type=code&
client_id=812741506391
		

If the user logs in and grants access via a URL similar to the one shown above, the result will be a dialog similar to the following:

Another example URL is shown below.

https://www.swcombine.com/ws/oauth2/auth/?
scope=character_read%2Ccharacter_write&
redirect_uri=http%3A%2F%2Flocalhost:1099&
response_type=code&
client_id=812741506391
		

The difference between these two URLs is the redirect_uri parameter. The first one results in an authorisation code in the title of the page, and the second one results in the authorisation code sent to a http://localhost address as part of the query string.

Choosing a Redirect URI

When you register your installed application in the Web Service Console, two redirect_uris are created for you: urn:ietf:wg:oauth:2.0:oob and http://localhost. The value your application uses determines how the authorisation code is returned to your application. See

http://localhost

This value signals to the Web Service Authorisation Server that the authorisation code should be returned as a query string parameter to the web server on the client. You may specify any port number without changing the Web Service Console configuration. To receive the authorisation code on this URL, your application must be listening on the local web server. This is possible on many, but not all platforms. In some cases, it is possible, but other software (e.g. Windows firewall) prevents delivery of the message without significant client configuration. If your platform supports it, this is the recommended mechanism for obtaining the authorisation code.

urn:ietf:wg:oauth:2.0:oob

This value signals to the Web Service Authorisation Server that the authorisation code should be returned in the title bar of the browser. This is useful when the client cannot listen on an HTTP port without significant client configuration. Windows applications possess this characteristic.

When this value is used, your application can sense that the page has loaded and the title of the HTML page contains the authorisation code. It is then up to your application to close the browser window if you want to ensure that the user never sees the page that contains the authorisation code. The mechanism for doing this varies from platform to platform.

Handling the Response

After the application receives the authorisation code, it may exchange the authorisation code for an access token and a refresh token. This request is an HTTP post, and includes the following parameters:

Field Description
code The authorisation code returned from the initial request
client_id The client_id obtained during application registration
client_secret The client secret obtained during application registration
redirect_uri The URI registered with the application
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of authorisation_code

The actual request might look like:

POST ws/oauth2/token HTTP/1.1
Host: www.swcombine.com
Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=8819981768& client_secret={client_secret}& redirect_uri=https%3A%2F%2Fwww.example.com.com/oauthcallback& grant_type=authorization_code

A successful response to this request contains the following fields:

Field Description
access_token The token that can be sent to a Resource
refresh_token A token that may be used to obtain a new access token, and are included by default for installed applications. Refresh tokens are valid until the user revokes access. This field is only present if access_type=offline is included in the authorisation code request.
expires_in The remaining lifetime on the access token

Other fields may be included in the response. Your application should allow additional fields to be returned in the response. The set shown above is the minimum set.

A successful response is returned as a JSON array, similar to the following:

JSON

{
	"access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
	"expires_in":3920,
  	"refresh_token":"1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}
		

XML

<?xml version="1.0" encoding="utf-8"?>
<OAuth>
    <access_token>1/fFAGRNJru1FTz70BzhT3Zg</access_token>
    <expires_in>3920</expires_in>
    <refresh_token>1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI</refresh_token>
</OAuth>
		

Calling a Resource

After your application has obtained an access token, your application can access a Reource by including it in either an access_token query parameter or an Authorization: OAuth HTTP header.

For example, a call to the Character Resource using the access_token query string parameter looks like the following:

GET https://www.swcombine.com/ws/v0.1/character/Testing%20Character?access_token=1/fFBGRNJru1FQd44AzqT3Zg

A call to the same resource using the access_token Authorization: OAuth HTTP header looks like the following:

GET /ws/v0.1/character/Testing%20Character HTTP/1.1
Authorization: OAuth 1/fFBGRNJru1FQd44AzqT3Zg
Host: www.swcombine.com

You can try either out in the CURL command line application. Here's an example of the query string parameter option:

curl https://www.swcombine.com/ws/v0.1/character/Testing%20Character?access_token=1/fFBGRNJru1FQd44AzqT3Zg

And the HTTP header option:

curl -H "Authorization: OAuth 1/fFBGRNJru1FQd44AzqT3Zg" https://www.swcombine.com/ws/v0.1/character/Testing%20Character

Using a Refresh Token

To obtain a new access tokenis simple. To obtain a new access token, make an HTTPs POST to https://www.swcombine.com/ws/oauth2/token. The request must include the following parameters:

Field Description
refresh_token The refresh token returned from the authorisation code exchange
client_id The client_id obtained during application registration
client_secret The client secret obtained during application registration
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of refresh_token

Such a request will look similar to the following:

POST ws/oauth2/token HTTP/1.1
Host: www.swcombine.com
Content-Type: application/x-www-form-urlencoded client_id=8819981768& client_secret={client_secret}& refresh_token=1/6BMfW9j53gdGImsiyUH5kU5RsR4zwI9lUVX-tqf8JXQ& grant_type=refresh_token

As long as the user has not revoked the access granted to your application, the response includes a new access token. A response from such a request is shown below:

JSON

{
  "access_token":"1/fFBGRNJru1FQd44AzqT3Zg",
  "expires_in":3920
}
		

XML

<?xml version="1.0" encoding="utf-8"?>
<OAuth>
    <access_token>1/fFAGRNJru1FTz70BzhT3Zg</access_token>
    <expires_in>3920</expires_in>
</OAuth>