API:2/OAuth 2.0
|
This page contains information about a Guild Wars 2 element, mechanic, or feature that has been removed or replaced. The information on this page does not apply to the current version of the game or the content is no longer available. |
Guild Wars 2 supports the OAuth 2.0 protocol since February 24th 2015. OAuth 2.0 is an open standardized protocol for authentication with services such as the Guild Wars 2 account servers. A service that implements the OAuth 2.0 protocol on client side can request account specific information from a set of authorization secured endpoints. The entire protocol is based on HTTP. This API is deprecated since May 7, 2015 and will be removed by June 4, 2015. Use API keys instead.[1]
Overview
Application
An application is a service that is registered on the Guild Wars 2 site. Each access a user grants is related to an application and will not be delete unless the user revokes the granted access.
Client-ID
The Client-ID is a GUID that is unique to the application it is generated for. This GUID will never change. It is used to identify a request to the OAuth 2.0 server as related to a specific application. A Client-ID is meant for public visibility.
Example Client-ID:
46471910-7d43-4756-9432-504f618a33f7
Client secret
A client secret is a GUID too. This GUID must be kept secret. It is used to validate the identity, in combination with the Client-ID, of an application. The client secret can be regenerated in case of the old client secret became public or your service has been compromised in some way.
Callback URL
A callback is an URL that the OAuth 2.0 server (in our case the Guild Wars 2 authentication service) will pass access tokens to after a valid authentication. If an application tries to tell the OAuth 2.0 server to call back an invalid callback URL, the request becomes invalid.
Access tokens
An access token is a one day lasting token that represents a valid Guild Wars 2 authentication. It is one of the core components that must be kept secret. Any service can request user related information from the API if it has a valid access token, no matter which application requested the access token.
Refresh tokens
A refresh token is a never expriring token that can be used to request new access tokens from our OAuth 2.0 server in combination with the Client-ID and client secret. The OAuth 2.0 server will only provide a refresh token if the application requested the offline scope.
Scopes
Scopes are used to control which information can be requested by an application with a valid access token. Here is a list of current available scopes.
| Scope | Description |
|---|---|
| account | This scope will allow the application to request account data. See API:2/account for further detail. |
| offline | The offline scope will allow the application to request information at any time. An authentication will only be valid for one day unless the application request the offline scope. |
Working with OAuth 2.0
Every time you want to request information from a protected API:2 endpoint you need to have a valid access token. The following sections will guide you step by step to a valid request to API:2/account.
First step: Register an application
At first you need to register a new application. This can be done at the Guild Wars 2 account center. Most of the form should be self-explaining. Of course you may not know the callback url yet.
Note: The application icon is an URL to an image file. You can leave it empty anyway.
If you are developing locally you may want to create two applications: One for developing purpose and one for productive use. It is also possible to set a local callback URL such as http://localhost/myCallback.php or http://127.0.0.1/myCallback.php.
Second step: Request a temporary authentication code
From this step on, the implementation depends highly on the programming language you are using. Therefore these sections will only show you an abstract concept that you have to implement by yourself.
After registration you can start by requesting your first access token. You have to make a request to https://account.guildwars2.com/oauth2/authorization with specific GET data. A request must contain the following data:
| GET field | Possible value | Description |
|---|---|---|
| response_type | code | Controls what data the OAuth 2.0 server will pass to the callback URL. * |
| client_id | 46471910-7d43-4756-9432-504f618a33f7 | Your applications Client-ID. |
| redirect_uri | http://localhost/myCallback.php | A registered callback URL. |
| scope | account offline | A list of space separated scopes. |
| state (optional) | anything | This field is used for internal use inside of your application. Everything you set to this field will be appended to the callback request. You may set a GUID or something similiar to remember and verify the processed user. |
* It should also be possible to set this value to token to implicitly generate an access token based on the offical RFC. However, Guild Wars 2 does not support this method. [2]
A valid request will look like this:
https://account.guildwars2.com/oauth2/authorization?response_type=code&client_id=46471910-7d43-4756-9432-504f618a33f7&redirect_uri=http://localhost/myCallback.php&scope=account offline&state=MyFirstRequest
Please note that it may be necessary to encode this URL.
Third step: Handle callback
Right after the user authorize your application, the user will be redirected to the callback URL. The callback will contain the GET data fields code and state (if set). The code data field contains a short living token that can be used to request a valid access token. To get this access token, your script has to make a request to https://account.guildwars2.com/oauth2/token providing the following data with POST method.
| POST field | Possible value | Description |
|---|---|---|
| code | <randomstring> | The short living code your application received from the Guild Wars 2 authentication server. |
| client_id | 46471910-7d43-4756-9432-504f618a33f7 | Your applications Client-ID. |
| client_secret | 4613dc0d-0a59-43c9-b8e6-4aaaf2c04f47 | The client secret of your application. |
| redirect_uri | http://localhost/myCallback.php | Must be the same URL that you passed to the /authorization endpoint earlier. |
| grant_type | authorization_code | Tells the server that you want to generate an access token with an authorization code. |
The response that the OAuth 2.0 server will send back will be a JSON encoded object that contains the following values
| Field | Description |
|---|---|
| access_token | The access token that grants access to the requested scopes. |
| expires_in | The time in seconds the access token expires in. |
| refresh_token (optional) | The refresh token. Only provided when offline scope was requested. Store this token if you want to request user information after the script runtime. But keep it safe! |
Fourth step: An example request to /v2/account
This is the last and final step of a generic OAuth 2.0 workflow.
If you successfully gained an access token you can use it to request the actual data. Let us start with an example request to /v2/account.
It is fairly easy. You just have to make a request that looks just the same as any other request you make to the API with one exception. You also have to provide an additional HTTP-Header.
The header field name is Authorization and its value is Bearer <access token> (without brackets). The API server will automatically lookup the user the access token is related to and sends back the users account information.
Example raw HTTP header:
Authorization: Bearer <access token>
Addition: Dealing with refresh tokens
If you have requested the offline scope, you can request access tokens at any time. It is basically the same method as requesting an access token with an authorization code. You have to make a POST request to https://account.guildwars2.com/oauth2/token that contains the following POST fields:
| POST field | Possible value | Description |
|---|---|---|
| refresh_token | <randomstring> | The refresh token you have stored for the user you want to request an access token for. |
| client_id | 46471910-7d43-4756-9432-504f618a33f7 | Your applications Client-ID. |
| client_secret | 4613dc0d-0a59-43c9-b8e6-4aaaf2c04f47 | The client secret of your application. |
| grant_type | refresh_token | Tells the server that you want to generate an access token with a refresh token. |
The result will look the same as described in step three.
Links
- RFC 6749 - The OAuth 2.0 Authorization Framework - The official RFC that describes the protocol
- Launching /v2/account (w/ Authentication) - Official announcement
- Google OAuth 2.0 Playground - A tool provided by Google that can be used to learn dealing with OAuth 2.0
