Using OAuth 2.0 for Web Server Applications

The Web Service OAuth 2.0 endpoint supports web server applications (e.g. PHP, Java, Python, Ruby, .NET, etc.). These applications may access a Resource while the user is present at the application or after the user has left the application. This flow requires that the application can keep a secret.

This article describes how to use OAuth 2.0 when accessing a Resource from a web server application.

Overview

This scenario begins by redirecting a browser (popup, or full page if needed) 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 authorization code (as opposed to directly delivering an access token).

SW Combine returns the authorization code to the web server application in the query string.

After receiving the authorization code, the application can exchange the code for an access token and, in some cases, a refresh token. The application presents its client_id and client_secret (obtained during application registration) along with the authorization code when obtaining an access token and refresh token.

The application may access a Resource after it receives the access token.

If a refresh token is present in the authorization code exchange, then it may be used to obtain new access tokens at any time. This type of access to a Resource is called offline, since the user does not have to be present at the browser when the application obtains a new access token.

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 Authorization Server for web server applications are:

https://www2.swcombine.com/ws/oauth2/auth/?
scope=character_read%20character_credits&
state=%2Fprofile&
redirect_uri=https%3A%2F%2Fwww.example.com%2Foauthcallback&
response_type=code&
client_id={client_id}
		

Handling the Response

The response will be sent to the redirect_uri as specified in an access token request. If the user approves the access request, then the response contains an authorization code and the state parameter (if included in the request). If the user does not approve the request the response contains an error message. All responses are returned to the web server on the query string, as shown below:

https://www.example.com/oauthcallback?error=access_denied&state=/profile

https://www.example.com/oauthcallback?state=/profile&code=8F3K2JD9X0QW7LZP5N1VB6MC4TY8RHGE

After the web server receives the authorization code, it may exchange the authorization code for an access token and a refresh token. This request is an HTTPs 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=https://www.example.com/oauthcallback&
grant_type=authorization_code
		

A successful response to this request contains the following fields:

{
	"access_token":"Q7ZP2M9XK4D8VB1N6CJ3HT5RW0LY8FGE",
	"expires_in":3600,
	"scope":"character_read character_credits",
	"token_type":"Bearer"
}
		

<?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>
</OAuth>
		

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.

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

Offline Access

In some cases, your application may need to access a Resource when the user is not present. Examples of this include backup services and applications that make GNS posts exactly at 8am on Monday morning. This style of access is called offline, and web server applications may request offline access from a user. The normal and default style of access is called online.

When an application requests offline access, the user sees a consent page that indicates your application is requesting the ability to make requests without the user being present at the browser.

If your application needs offline access to a Resource, then the request for an authorization code should include the access_type parameter, where the value of that parameter is offline. An example request for offline access is shown below:

https://www2.swcombine.com/ws/oauth2/auth/?
scope=character_read%20character_credits&
state=%2Fprofile&
redirect_uri=https%3A%2F%2Fwww.example.com%2Foauthcallback&
response_type=code&
client_id={client_id}&
access_type=offline
		

When the user's browser is sent to this URL, they see a consent page. If they grant access, then the response includes an authorization code which may be redeemed for an access token. To also receive a refresh token, include access_type=offline when redeeming the authorization code (the access_type on the authorization request only affects the consent page shown to the user).

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=https://www.example.com/oauthcallback&
grant_type=authorization_code&
access_type=offline
		

The response then includes an access token and a refresh token, as shown below:

{
	"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>
		

After your application receives the refresh token, it may obtain new access tokens at any time. See the section on refresh tokens for more information.

Each time your application requests an authorization code, the user is shown the consent page again. Every exchange that includes access_type=offline issues a new refresh token; refresh tokens issued by earlier exchanges stay valid until they are used or revoked. An exchange that does not include access_type=offline returns only an access token.

Using a Refresh Token

As indicated in the previous section, a refresh token is obtained in offline scenarios, when access_type=offline is included in the authorization code exchange. In these cases, your application may obtain a new access token by sending a refresh token to the Web Service OAuth 2.0 Authorization server.

To obtain a new access token this way, your application performs 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>
		

Revoking a Refresh Token

In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting the Web Service Console in Account Settings and explicitly revoking access. It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes or removes an application. In other words, part of the removal process can include a request to ensure the permissions granted to the application are removed.

To programmatically revoke a token, your application makes a request to https://www2.swcombine.com/ws/oauth2/revoke and includes the refresh token and client id as parameters:

curl "https://www2.swcombine.com/ws/oauth2/revoke?token={refresh_token}&client_id={client_id}"

Only the refresh token is revoked. The most recently issued access token remains valid until it expires (up to one hour), but it can no longer be renewed. If the revocation was successfully processed, then the status code of the response is 200. For error conditions, a status code 400 is returned along with an error code.