Skip to content

OAuth Documentation

John Shaffstall edited this page Jan 6, 2021 · 12 revisions

OAuth 2.0

OAuth Support

Bungie.net supports a subset of OAuth 2.0 (RFC 6749) as described in the following sections.

Authorization Grant

Bungie.net supports the Authorization Code grant type as described in section 1.3.1 of the OAuth 2.0 specification.

Client Registration

Developers must register all clients at the application portal. (https://www.bungie.net/en/Application)

Among a few other details, the developer must provide the following:

  • Client Type: Public or Confidential as described in section 2.1 of the OAuth 2.0 specification.
  • Scope: The scope required by their client. The client cannot request a different scope dynamically and the scope parameter must be omitted from authorization and token requests.
  • Redirect URL: A single redirect URL used by the client. The client must not specify a different redirect URL dynamically. If a redirect URL is specified, it must match the URL registered for the client. The developer may also specify other details about the client such as its name, a link to its website and its origin header.

The portal issues client ID used with the OAuth endpoints, and an API Key used with Bungie.net resource endpoints.

The portal also issues confidential clients a client secret which can also be used as the client password as described in section 2.3.1 of the OAuth 2.0 specification.

These identifiers: client ID, client secret, API Key are linked together and are referred to collectively as the client’s API keys. The developer may create a second set of API keys if there is concern that the first set has been compromised in some way. The developer has complete control over the creation, deletion, and enablement of the API keys.

Protocol Endpoints

Bungie.net defines protocol endpoints as defined in section 3 of the OAuth 2.0 specification.

Authorization endpoint: https://www.bungie.net/en/oauth/authorize

Token Endpoint: https://www.bungie.net/platform/app/oauth/token/

Redirection endpoint: Developer provides this value in the application portal.

Authorization Request

The client constructs the request URI by adding the following parameters to the query component of the authorization endpoint.

  • response_type: Must be “code”
  • client_id: Provided by the portal
  • state: An opaque value used by the client to maintain state between the request and the callback. The parameter should be used for preventing cross-site request forgery as described in section 10.12 of the OAuth 2.0 specification.

The redirect_uri parameter is optional. If it is present, it must be a case sensitive exact match with the value registered in the portal.

Do not include the scope parameter. Bungie.net does not define a syntax for this parameter and will reject requests that specify a scope.

GET https://www.bungie.net/en/oauth/authorize?client_id=12345&response_type=code&state=6i0mkLx79Hp91nzWVeHrzHG4

The response is consistent with section 4.1.2 of the OAuth 2.0 specification.

Access Token Request

The client makes a request to the token endpoint by sending the following parameters using the “application/x-www-form-urlencoded” format in the body of a POST request.

grant_type: Value must be set to “authorization_code”. code: Authorization code received from the authorization endpoint. client_id: Public clients must provide this parameter. It is optional for confidential clients if they are providing credentials using the Authorization header. client_secret: Confidential clients may provide this parameter if they are not using the Authorization header. Public clients must not provide the client_secret parameter.

The redirect_uri parameter is optional. If it is present, it must be a case sensitive exact match with the value registered in the portal.

The following is a request by a confidential client using the Authorization header.

POST https://www.bungie.net/platform/app/oauth/token/ HTTP/1.1
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

An example successful response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "refresh_expires_in": 7776000
    "membership_id":"4352344"
}

The token_type is always “Bearer”. Bungie.net adds two additional parameters: membership_id which is the Bungie.net membership ID of the authenticated user. The “refresh_expires_in” provides the number of seconds before the refresh token expires.

Note: A public client differs from a confidential client in that it is not issued a client_secret (or password) and it will not receive a refresh token in response to a token request.

Refreshing the Access Token

A confidential client may refresh an access token by making a refresh request to the token endpoint, using the following parameters in the body of the POST request.

  • grant_type: Value must be set to “refresh_token”
  • refresh_token: Previously issued refresh token

The client must not include the scope parameter. The new access token will have the same scope as the one being refreshed.

Accessing Protected Resources

The client must add both its assigned API key (from the portal) and the access token to each request using the Authorization header. For example:

GET /resource HTTP/1.1
Authorization: Bearer mF_9.B5f-4.1JqM
X-API-Key: 8d6484be63a845848a9affde4ec9f682

The API key supplied must be the key associated with the client ID used to get the access token. This is identical to the way authentication currently works in Bungie.net.

Unlike the existing Bungie.net authorization mechanism, the Bungie.net will return a HTTP 401 response code if the Authorization header cannot be accepted for any reason, including if the OAuth access token has expired.

Cross Site Request Forgery Mitigation

The Authorization URL accepts a ‘state’ parameter which will be echoed back on your Redirect URL. Your application should generate a random value that an attacker could not guess. It should then verify that value is the same when it gets the code back via the Redirect URL. There are several good write-ups about the use of the state parameter on the internet with respect to OAuth 2.0. For example:

https://auth0.com/docs/protocols/state-parameters

We recommend you make use of the state parameter in your implementation.

Signing in via the System Web Browser

One of the key values of this authentication mechanism is that it makes it possible for users to enter their credentials into the default system web browser. Contrast this with using an in-app web view which can allow a mischievous application to collect a user's credentials without the user's knowledge.

Using a web view is strongly discouraged by Bungie. We will block it using technical means where possible. In the very least, applications that implement the sign in flow via a web view will not be featured or promoted on Bungie.net in any way. We may take other measures as well.

It is not that we do not trust app developers, but we want to set a consistent example for users. Users should be wary of entering credentials in applications that are not the custodians of those credentials. Users can only confirm they are authenticating with Sony, Microsoft, or Bungie if they have the user interface provided by the browser, including the URL and the https certificate information.

iOS applications may use the SFSafariViewContoller class instead of switching to Safari. Android applications may use Chrome Custom Tabs. Web applications may not use an iframe, the URL bar where the user is authorizing or signing in must always be visible.