Skip to content

Instantly share code, notes, and snippets.

@iBotPeaches
Created August 24, 2017 14:12
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
Save iBotPeaches/04d6c7cfec9a4f42894393634eec9e99 to your computer and use it in GitHub Desktop.
OAuth Bungie.md

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 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment