Using OAuth

The Battle.net API uses OAuth 2.0, a federated access control mechanism, to help secure sections of the APIs that we provide out to the public. By using OAuth, you can let Battle.net handle the authentication process and receive a unique ID representing that user, then use an access token to gain access to allowed resources like their World of Warcraft characters, StarCraft II profile, or other data as appropriate. The usage of OAuth itself is relatively simple, but the flows can seem a little intimidating at first. Hopefully, by following the processes below, you can quickly integrate with Battle.net and worry more about building that cool idea and less about how to get data from players.

Note, due to the sensitive nature of storing user data, it is HIGHLY RECOMMENDED that you use stable libraries for performing the OAuth process instead of implementing your own. If we suspect that your site has been compromised or see suspicious activity regarding your project, all access tokens and authorizations for your client will be removed and your client ID could be permanently revoked.

Sample Libraries

For many oauth2 libraries you only need the data below (oauth urls) and your key and secret from your application registration. Some platforms also make use of plugins that come preset with both the urls and ability to get some profile information about the user. We have prepared two sample libraries that the community can use for Ruby and Node webapps:

Library Quick Start

If you're using a library, there should mainly only be four items that you'll typically need to get started. Those are a client_id, client_secret, authorize_uri and token_uri.

Client ID and Secret

The first step in using OAuth is getting a client_id. If you head on over to the registration page, you can complete the registration process, which will provide you with a client_id and client_secret. If using a library, you should be able to plug those values into it, and begin working. Please note that your application Key is the client_id and the Secret is the client_secret.

Redirect URL

When registering an application you can specify a redirect url for that key. This must be a valid HTTPS (SSL-enabled) URL. After a user authorizes themselves on Battle.net's login page we will only redirect them back to this URL.

OAuth URIs

In order for OAuth to work properly, there are a couple of URIs that are commonly used. The authorize_uri is used to get player authorization for you to access certain resources of theirs, like a list of Diablo III characters. The token_uri is used to turn in items (like an authorization code) for access tokens that you can then use with any of our APIs. Those values are:

RegionAuthorize URI Token URI
US EU KR TW https://<region>.battle.net/oauth/authorize https://<region>.battle.net/oauth/token
CN https://www.battlenet.com.cn/oauth/authorize https://www.battlenet.com.cn/oauth/token

Where the <region> is one of the following: us, eu, kr or tw. In order to use oauth on the SEA Sc2 community api, you should use the US oauth servers.

There is also a check_token endpoint available to check the details of a token. It is available in all regions at /oauth/check_token?token=<token>. This can be used to verify that an access token actually was generated for your client.

Scopes and OAuth enabled APIs

Scopes are used to request specific information from a user of your site. You don't need to request any scopes to use Battle.net login. Without scopes you will get access to a users account ID and BattleTag. To get any more specific user information you'll need to request it from the user using scopes.

Right now we only have two scopes that are able to be requested:

Scope Description Example API URL
wow.profile Access to a users World of Warcraft characters https://us.api.battle.net/wow/user/characters
sc2.profile Access to a users StarCraft II profile https://us.api.battle.net/sc2/profile/user

Access Tokens

Our access tokens last for 30 days. Access tokens may expire before 30 days in specific cases. A user changing their password, removing the authorization for your account, or getting their account locked for any reason will result in the expiration of their current access tokens. Always check the response and request a new access token if your current one fails to work.

The Details

If you do decide to implement an OAuth client yourself, or are just interested in the general flow of OAuth, here is the process in more detail:

Authorization Code Server Flow

The Authorization Code server flow is the most common flow, and represents a client (that's you!) attempting to access the data of a player on behalf of that player. This allows you to get details around a player, such as their World of Warcraft characters, without having to go through a clunky UI where they do things like fill in server and character names. It has two major parts, the Authorization Code request, and the access token request.

For an authorization code request, you need to either redirect the browser or open a new window to the authorize URI with the following query parameters:

Term Description
client_id The client id given to you upon registration.
scope The space separated scope values you wish to request from the player.
state A semi-random data blob to be sent back along with the player when completing authorization.
redirect_uri The location to redirect the user to. Should either be https://localhost for testing or the redirect_uri configured when signing up.
response_type The code type being requested. For the authorization code server flow, this should be code

Once the player has granted authorization, they will be directed back to the site listed at redirect_uri along with the state query parameter and a query parameter called code. This is the authorization code that represents the user's agreement to allow you data. Note, however, that users can fine tune what data they wish for you to view, so the authorization may not encompass all of the scopes you requested. You should parse this token and prepare to request access tokens from it.

To request access tokens, you need to provide the following POST parameters to the token URI, using your client ID and secret with HTTP Basic Authorization:

Term Description
redirect_uri The same redirect_uri used when obtaining the authorization.
scope The scopes you need for the access token. Note that this can be less than the authorization.
grant_type authorization_code.
code The code for the specific grant_type used.

The server should respond with a JSON structure that contains an access token. From there, you should be able to use the access token to access any of the allowed resources on behalf of that player! You can refer to any of the game API pages to learn about what data you can request.

Security Considerations

When dealing with OAuth, there are several steps that you should take in order to ensure that you don't accidentally leak client information or have a potential security hole. We'll detail each one, in order through the system.

HTTPS

One of the major changes to OAuth when releasing version 2.0 was removing transport considerations from the protocol, instead relying on implementors to handle the transport of codes and tokens themselves. What this means in practical terms is that HTTPS is required, and for extra security, checking the cert during the HTTPS handshake is recommended. This will prevent any surprises and will prevent the codes from being captured while in transit.

State Parameter

When requesting an authorization code (by directing the player to battle.net), one of the parameters you should pass is the state parameter. To us, this is an opaque blob, but should be semi-random to help prevent cross-site scripting attacks. Otherwise, an evil hacker could direct someone to us, who direct to you, which causes you to do some action that the user didn't actually request. In addition, since the data is sent back to you untransformed, this can be used as a way for you to manage multiple redirect locations...but if not properly secured, could be used to redirect a user to a phishing site or other evil purpose because the redirect location wasn't checked.

Client Secret

Understand that the only time the client secret should be sent to us is as part of exchanging the authorization code for an access token, and should always be sent as part of a POST operation

Access Token

Access tokens are all-access passes to player data, and as such, should be handled very closely. They should never be sent out to the player in any format, and should only be used server side. In addition, if an attacker compromises your site, those tokens can be used to glean details about players that none of us want to divulge. An access token only lives for about 30 days, so if you are doing an operation that doesn't require constant access, making a single request to get that data and never storing the token allows for the safest use of our APIs.

Learning More

If you wish to learn more about OAuth 2.0, the next step is to look at the official RFC, located here