Authentication library for Bungie.net
npm install bungie-authThe bungie-auth module exposes a nice API to authenticate withe Bungie.net's
oAuth 2.0 based authentication process.
- Installation
- Usage
- API
- token
- request
- refresh
- payload
- alive
- expired
- capture
- open
- url
- secure
- send
- setTimeout
- pre-build
- electron
- license
The module is released to the public npm registry and can be installed by
running:
``
npm install --save bungie-auth
Please note that this module is written in ES6, if you wish to use it in a
Node.js environment you might need to use babel to transform the module to an
ES5 compatible version.
The following configuration values are required:
- redirectURL The URL that Bungie redirects to.url
- The unique Authorization URL that Bungie created for your application.key
- The API for your Authorization URL.
While not strictly required you want to supply this by default as well if
you have it:
- refreshToken The responseToken object you got back from the API.accessToken
- The accessToken object you got back from the API.
These values should be stored locally and securely so you don't have to
authenticate every single time people open your application. The following
configuration values are optional:
- buffer Number in seconds. Amount of seconds that will be extracted from theexpires
value of the accessToken and refreshToken. Defaults to 60.fresh
- Function. Callback to indicate that we automatically want to refreshaccessToken
the cached internal when it's about to expire. The fresh
method will be called with the new payload.
`js
import Bungo from 'bungie-auth/electron';
const bungie = new Bungo({
key: '..',
url: '..'
});
`
The created bungie instance will have the following methods available.
- token
- request
- refresh
- payload
- alive
- expired
- capture
- open
- url
- secure
- send
- setTimeout
Once you've received the accessToken from one of our API methods you can usevalue
it's to create the Authorization header that might be needed for the
the API calls:
`js
bungie.token(function (err, paylaod) {
if (err) throw err;
const token = payload.accessToken.value;
const authorization = Bearer ${token};`
});
Retrieve the access token from the API. If we have a cached accessToken whichrefreshToken
is still good, we will use that. If it's expired we will generate a new one with
a that we might have. If that case fails, we will ask the userrefreshToken
login again so we get a fresh and accessToken.
The method accepts a single argument:
- fn An error first callback that receives potential errors as first argument
and the payload as second argument.
`js
bungie.token(function (err, payload) {
});
`
Request a new access token. This will ask the user to login with their
credentials and does the initial call the Bungie servers to retrieve the
accessToken and refreshToken.
The method accepts a single argument:
- fn An error first callback that receives potential errors as first argument
and the payload as second argument.
`js
bungie.request(function (err, payload) {
});
`
Refresh the accessToken as it expires after like 30 minutes once you firstaccessToken object
requested it (see expires value in seconds on the ).
The method accepts two arguments:
- token An optional token object that you received from payload. When omittedrefreshToken
and used as single argument function it will default to the internally stored
.fn
- An error first callback that receives potential errors as first argument
and the payload as second argument.
`js
bungie.refresh(token, function (err, payload) {
});
bungie.refresh(function (err, payload) {
});
`
Formats and returns the payload that we received from the Bungie servers. API
methods like refresh, token, request use the
returned object as response.
`js`
const data = bungie.payload();
The method returns the following object structure:
`js`
{
accessToken: {
value: 'your access token',
readyin: 0,
expires: 3600,
epoch: 90874174017
},
refreshToken: {
value: 'your refresh token',
readyin: 1800,
expires: 3600
epoch: 90874174017
}
}
The value is the actual token from the server. The readyin and expires areepoch
seconds. We add our own property to each object. This is the result ofDate.now() when we first received the information from the Bungie servers.
This allows you to determine if the token is still valid or if it's expired.
Check how long a given token has been alive. Returns time in seconds so it can
be matched against the token.expires property.
The method accepts a single argument:
- token The accessToken or refreshToken object that was returned from the
payload method.
`js`
bungie.alive(bungie.accessToken) // 189
Check if a token is expired. It does this by checking the amount of seconds that
have been passed since the token was received based on the epoch value that weconfig.buffer
added to the object. It automatically adds in seconds to thebuffer
time passed so we will have some spare time to request a new access token and
prevent that API calls will use the token RIGHT when it expired. This gives you
some peace of mind that the token you receive is alway valid for the amount
of time was configured with the option.
The method accepts a single argument:
- token The accessToken or refreshToken object that was returned from the
payload method.
The method will return a boolean indicating if the token is still valid or needs
to be re-requested.
`js`
bungie.expired(bungie.accessToken) // false
private api
Intercept and capture all API responses from Bungie so we can store the values
internally.
The method accepts a single argument:
- fn An error first callback that receives potential errors as first argument
and the payload as second argument.
And it will return a wrapped function that should be for callbacks.
`js`
const fn = bungie.capture(callback);
bungie.send('GetAccessTokenFromRefreshToken', { refreshToken: token } fn);
private api
This is a method that should be implemented by our pre-build
integrations. This method should start the oAuth 2.0 Authorization flow using
the bungie.url() method. It should call the supplied callback once it receivescode
the and state back as query string values from the oAuth 2.0 redirect
URL.
The method accepts a single argument:
- fn An error first callback that receives potential errors as first argument
and the full redirect URL as second value.
Example implementation, take this with a grain of salt and look at our
electron flow for a working example.
`js
bungie.open = function open(fn) {
var url = bungie.url();
// implement opening of url, and capturing redirect url
fn(undefined, redirect.url);
};
`
private api
Generate the URL that needs to be used for the oAuth 2.0 authorization flow.
This automatically generates and stores a unique value as this.state which
will be used in the secure method to validate the response.
The method will return a string which is the URL that should be opened to start
the authentication process.
`js`
const url = bungie.url();
private api
Checks the received URL to see if the received state query string matches ourstate
internal stored so we can check if the request/response was tampered
with.
The method accepts a single argument:
- url Full, unparsed URL string that Bungie used to redirect to. Shouldcode
include the and state query string values.
The method will return a boolean indicating if the URL is secure.
`js`
bungie.state = 'foo';
bungie.secure('http//example.com/oauth/redirect?state=foo&code=bar'); // true
private api
Our internal HTTP request method that does the API calls to the Bungie servers
to validate/request the tokens and codes we receive from the Authorization flow.
It automatically uses the supplied config.key for the X-API-Key header and
handles all responses as JSON responses.
It requires the following arguments:
- pathname The pathname of /Platform/App/{pathanme here}/ we need to access.body
- An object that will be used as POST body.fn
- Completion callback that uses the error first callback pattern.
`js
bungie.send('GetAccessTokenFromRefreshToken', {
refreshToken: token
}, function (err, data) {
});
`
private api
Start the internal setTimeout so we can automatically refresh the cached
accessToken using the refreshToken so our internally cached token is alway
fresh and elimination possibility to provide an token that might expire in a
second or to accidentally send multiple refresh requests to the bungie API.
`js`
bungie.setTimeout();
- Electron
In addition to the pre-build authorization flows for the various of frameworks
that we support it is quite easy to roll your own. The only thing you need todo
is extend our class and implement the open method as shown below:
`js
import Bungo from 'bungie-auth';
export default class MyImplementation extends Bungo {
open(fn) {
const url = this.url();
/*
do the stuffs that opens the authorization url and receives the redirect
information and call the fn callback function with an optional error as`
first argument and the redirected URL as second argument and you're done.
*/
}
}
After that you just construct an instance of your custom MyImplementation
class and it should work with our described API's! If you want to contribute
back to the community, we would love to support more pre-build authorization
flows to make it easier for other people to create applications. So create
a pull request with your new implementation and we'll make that happen!
This is a pre-build authorization flow for Electron so you can easily build
desktop applications that interact with the Bungie.net API. The API should run
in the electron instance and not the browser instance as it needs to be able to
spawn windows and do POST calls to the Bungie API for access tokens.
The following properties are specific to electron
- electron Allows you to control options for the created BrowserWindow by
default we will spawn a window that the same size as oAuth window.
While we allow you to configure the browser option, we forcefully applynodeIntergration: false so the authentication actually works.
`js
import Bungo from 'bungie-auth/electron';
const bungo = new Bungo({ /.. config ../ });
bungo.token(function token(err, data) {
console.log(data.accessToken.value); // CJ098da098df...
});
``
This module is released under the MIT license.