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.
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.
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.).
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.
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.
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).
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.
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:
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.
For more information, see Using OAuth 2.0 for Client-side Applications documentation.
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:
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.