Using OAuth 2.0 to Access Resources

Web Services use the OAuth 2.0 protocol for authentication and authorization. SW Combine supports several OAuth 2.0 flows that cover common web server, JavaScript, device, and installed application scenarios.

OAuth 2.0 is a relatively simple protocol and a developer can integrate with the OAuth 2.0 endpoints without too much effort. In a nutshell, you register your application with SW Combine, redirect a browser to a URL, parse a token from the response, and send the token to the Web Service you wish to access.

This article gives an overview of the OAuth 2.0 scenarios supported and provides links to more detailed content.

Basic Steps

Applications follow the same basic pattern when accessing a Resource using OAuth 2.0. At a high level, using OAuth 2.0 to access a Resource consists of four steps:

Note: During steps 2 and 4, the request may fail if the character's current status is invalid (eg. if the character is dead/inactive/banned/unconscious/arrested/etc). This may impact users trying to grant permissions to your app and you should alert your user to this fact ahead of time. There is no way to determine which status is impacting the character.

1. Register Application

All applications that access a Web Service must be registered through the Application Registration Form. The result of this registration process is a set of values that are known to both us and your application (e.g. client_id, client_secret, redirect_uri, etc.).

2. Obtain an Access Token from the Web Service Authorization Server

Before your application can access a Resource, it must obtain an access token that grants access to that Resource. A single access token may grant varying degrees of access to multiple Resources. The set of resources and operations permitted by an access token is controlled during the access token request via a variable parameter called 'scope'. Several scopes may be included in a request.

There are several ways to make this request, and they vary based on the type of application you are building. For example, a JavaScript application may request an access token using a browser redirect to SW Combine, while an application installed on a device that has no browser uses web service requests.

The request requires the user to login to SW Combine. After logging in, the user will see the permissions requested by the application and is asked if they are willing to grant your application those permissions. This process is called "user consent".

If the user grants permission to your application, your application will be sent an access token or an authorization code (which is used to obtain an access token). If the user does not grant permission to your application, the Web Service Authorization Server returns an error.

3. Send Access Token to a Resource

After an application has obtained an access token, it may send the access token in a request to a Web Service. Access tokens are valid only for the set of operations and resources described in the token request. For example, if an access token is issued for the Character Resource, it will not grant access to the Inventory Resource. It may, however, be sent to the Character Resource multiple times for similar operations. Access tokens are sent to a Resource in the HTTP Authorization header, or as a query string parameter (if HTTP header operations are not available).

4. Refresh the Access Token (optional)

Access tokens have a limited lifetime and, in some cases, an application needs access to a Resource beyond the lifetime of a single access token. When this is the case, your application can obtain what is called a refresh token. A refresh token allows your application to obtain new access tokens.

Simple Example

Below is a trivial example of how to use the OAuth 2.0 endpoint to gain access to a Resource. The flow of the example is fairly straightforward:

1. When the application loads, it shows you a "Login" link.
2. When you click that link, you are asked to login to SW Combine and asked to release basic account information to the application (user consent).
3. If you grant consent, the application receives an access token.
4. Once it has the access token, the application presents the access token to the Resource that provides basic account information (https://www.swcombine.com/ws/v2.0/character/account/)
5. The application renders the basic account information in a simple table.

Scenarios

Web Server Applications

The Web Service Authorization Server supports web server applications (e.g. PHP, Java, Python, Ruby, ASP.NET, etc.). This sequence 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, session selection and consent, but the result of the sequence is an authorization code. After receiving the authorization code, the application can exchange the code for an access token and a refresh token.

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

For more information, see Using OAuth 2.0 for Web Server Applications documentation.

Client-side Applications

The Web Service Authorization Server supports JavaScript applications (JavaScript running in a browser). Like the other scenarios, this one begins by redirecting a browser (popup, or full-page if needed) to a SW Combine URL with a set of query string parameters that indicate the type of resource access the application requires. SW Combine handles the user authentication, session selection, and user consent. The result is an access token. The client should then validate the token. After validation, the client includes the access token in a Resource request.

For more information, see Using OAuth 2.0 for Client-side Applications documentation.

Installed Application

The Web Service 2.0 Authorization Server supports desktop and mobile applications (e.g. Android, Windows, Mac OS, iOS, Blackberry, etc.). These applications, in general, cannot keep secrets.

The sequence for installed applications is similar to the one shown in the Web Server section, but there are three exceptions:

1. When registering the application, you specify that the application is an 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.
4. The authorization code is returned to your application differently.

This sequence begins by redirecting a browser (either a browser embedded in the application or the system browser) 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, session selection, and user consent. The result of the sequence is an authorization code that is returned in the title and body of the web page. Once the application receives the authorization code, it can exchange the code for an access token and a refresh token.

After the application has received the access and refresh tokens, it may store the refresh token for future use, and use the access token to access a Google API. Once the access token expires, the application obtains a new one with the refresh token.

For more information, see Using OAuth 2.0 for Installed Applications documentation.