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://www2.swcombine.com/ws/oauth2/auth/. This endpoint is accessible over SSL, and HTTP connections are refused.

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

https://www2.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:

https://www2.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:

POST ws/oauth2/token/ HTTP/1.1
Host: www2.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:

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:

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

<?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://www2.swcombine.com/ws/v2.0/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/v2.0/character/Testing%20Character HTTP/1.1
Authorization: OAuth 1/fFBGRNJru1FQd44AzqT3Zg
Host: www2.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://www2.swcombine.com/ws/v2.0/character/Testing%20Character?access_token=1/fFBGRNJru1FQd44AzqT3Zg

And the HTTP header option:

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

Using a Refresh Token

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

POST ws/oauth2/token/ HTTP/1.1
Host: www2.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:

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

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