API:2/OAuth 2.0

From Guild Wars 2 Wiki
Jump to navigationJump to search

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

References