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%20character_credits&
redirect_uri=urn:ietf:wg:oauth:2.0:oob&
response_type=code&
client_id={client_id}
		

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%20character_credits&
redirect_uri=http%3A%2F%2Flocalhost:1099&
response_type=code&
client_id={client_id}
		

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, urn:ietf:wg:oauth:2.0:oob is registered as its redirect_uri, and an http://localhost address (on any port) is also accepted. The value your application uses determines how the authorisation code is returned to your application, as described below.

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=8F3K2JD9X0QW7LZP5N1VB6MC4TY8RHGE&
client_id={client_id}&
client_secret={client_secret}&
redirect_uri=urn:ietf:wg:oauth:2.0:oob&
grant_type=authorization_code&
access_type=offline&
code_verifier={code_verifier}
		

Using PKCE

PKCE (Proof Key for Code Exchange, RFC 7636) protects the authorisation code flow for applications, such as installed and mobile apps, that cannot reliably keep a client_secret confidential. It is optional, but strongly recommended for these applications.

To use PKCE:

1. Before redirecting to the authorisation URL, generate a high-entropy random string of 43-128 characters (letters, digits, and the characters -, ., _, ~) called the code_verifier, and keep it in your application.
2. Compute the code_challenge from the code_verifier. If using code_challenge_method=S256 (recommended), the code_challenge is the SHA-256 hash of the code_verifier, base64url-encoded without padding. If using code_challenge_method=plain, the code_challenge is simply the code_verifier itself.
3. Include code_challenge and code_challenge_method as query string parameters on the authorisation request, as shown in the table above.
4. When exchanging the authorisation code for an access token, include the original code_verifier as a parameter. The Web Service Authorisation Server recomputes the challenge from the supplied code_verifier and compares it to the code_challenge stored with the authorisation code, rejecting the exchange with an invalid_grant error if they do not match.

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":"Q7ZP2M9XK4D8VB1N6CJ3HT5RW0LY8FGE",
	"expires_in":3600,
	"scope":"character_read character_credits",
	"token_type":"Bearer",
  	"refresh_token":"R4TN8W2KJ7XM1QZ5HB9CV3DP6LY0GFEA"
}
		

<?xml version="1.0" encoding="utf-8"?>
<OAuth>
    <access_token>Q7ZP2M9XK4D8VB1N6CJ3HT5RW0LY8FGE</access_token>
    <expires_in>3600</expires_in>
    <scope>character_read character_credits</scope>
    <token_type>Bearer</token_type>
    <refresh_token>R4TN8W2KJ7XM1QZ5HB9CV3DP6LY0GFEA</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=M2XK9D4PQ7VB1N6CJ3HT5RW0LY8FGEZA

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 M2XK9D4PQ7VB1N6CJ3HT5RW0LY8FGEZA
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=M2XK9D4PQ7VB1N6CJ3HT5RW0LY8FGEZA

And the HTTP header option:

curl -H "Authorization: OAuth M2XK9D4PQ7VB1N6CJ3HT5RW0LY8FGEZA" 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={client_id}&
client_secret={client_secret}&
refresh_token=R4TN8W2KJ7XM1QZ5HB9CV3DP6LY0GFEA&
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 and a new refresh token. A response from such a request is shown below:

{
  "access_token":"M2XK9D4PQ7VB1N6CJ3HT5RW0LY8FGEZA",
  "expires_in":3600,
  "scope":"character_read character_credits",
  "token_type":"Bearer",
  "refresh_token":"K9D2M7XQ4PVB1N6CJ3HT8RW0LY5FGEZA"
}
		

<?xml version="1.0" encoding="utf-8"?>
<OAuth>
    <access_token>M2XK9D4PQ7VB1N6CJ3HT5RW0LY8FGEZA</access_token>
    <expires_in>3600</expires_in>
    <scope>character_read character_credits</scope>
    <token_type>Bearer</token_type>
    <refresh_token>K9D2M7XQ4PVB1N6CJ3HT8RW0LY5FGEZA</refresh_token>
</OAuth>