OAuth2Server

Represents an OAuth2 server instance.

const OAuth2Server = require('oauth2-server');

new OAuth2Server(options)

Instantiates OAuth2Server using the supplied model.

Arguments:

Name Type Description
options Object Server options.
options.model Object The Model.

Return value:

A new OAuth2Server instance.

Remarks:

Any valid option for OAuth2Server#authenticate(), OAuth2Server#authorize() and OAuth2Server#token() can be passed to the constructor as well. The supplied options will be used as default for the other methods.

Basic usage:

const oauth = new OAuth2Server({
  model: require('./model')
});

Advanced example with additional options:

const oauth = new OAuth2Server({
  model: require('./model'),
  allowBearerTokensInQueryString: true,
  accessTokenLifetime: 4 * 60 * 60
});

authenticate(request, response, [options], [callback])

Authenticates a request.

Arguments:

Name Type Description
request Request Request object.
response Response Response object.
[options={}] Object Handler options.
[options.scope=undefined] String The scope(s) to authenticate.
[options.addAcceptedScopesHeader=true] Boolean Set the X-Accepted-OAuth-Scopes HTTP header on response objects.
[options.addAuthorizedScopesHeader=true] Boolean Set the X-OAuth-Scopes HTTP header on response objects.
[options.allowBearerTokensInQueryString=false] Boolean Allow clients to pass bearer tokens in the query string of a request.
[callback=undefined] Function Node-style callback to be used instead of the returned Promise.

Return value:

A Promise that resolves to the access token object returned from Model#getAccessToken(). In case of an error, the promise rejects with one of the error types derived from OAuthError.

Possible errors include but are not limited to:

UnauthorizedRequestError:
The protected resource request failed authentication.

The returned Promise must be ignored if callback is used.

Remarks:

const oauth = new OAuth2Server({model: ...});

function authenticateHandler(options) {
  return function(req, res, next) {
    let request = new Request(req);
    let response = new Response(res);
    return oauth.authenticate(request, response, options)
      .then(function(token) {
        res.locals.oauth = {token: token};
        next();
      })
      .catch(function(err) {
        // handle error condition
      });
  }
}

authorize(request, response, [options], [callback])

Authorizes a token request.

Arguments:

Name Type Description
request Request Request object.
[request.query.allowed=undefined] String 'false' to deny the authorization request (see remarks section).
response Response Response object.
[options={}] Object Handler options.
[options.authenticateHandler=undefined] Object The authenticate handler (see remarks section).
[options.allowEmptyState=false] Boolean Allow clients to specify an empty state.
[options.authorizationCodeLifetime=300] Number Lifetime of generated authorization codes in seconds (default = 5 minutes).
[callback=undefined] Function Node-style callback to be used instead of the returned Promise.

Return value:

A Promise that resolves to the authorization code object returned from Model#saveAuthorizationCode(). In case of an error, the promise rejects with one of the error types derived from OAuthError.

Possible errors include but are not limited to:

AccessDeniedError
The resource owner denied the access request (i.e. request.query.allow was 'false').

The returned Promise must be ignored if callback is used.

Remarks:

If request.query.allowed equals the string 'false' the access request is denied and the returned promise is rejected with an AccessDeniedError.

In order to retrieve the user associated with the request, options.authenticateHandler should be supplied. The authenticateHandler has to be an object implementing a handle(request, response) function that returns a user object. If there is no associated user (i.e. the user is not logged in) a falsy value should be returned.

let authenticateHandler = {
  handle: function(request, response) {
    return /* get authenticated user */;
  }
};

When working with a session-based login mechanism, the handler can simply look like this:

let authenticateHandler = {
  handle: function(request, response) {
    return request.session.user;
  }
};

Todo

Move authenticateHandler to it’s own section.

const oauth = new OAuth2Server({model: ...});

function authorizeHandler(options) {
  return function(req, res, next) {
    let request = new Request(req);
    let response = new Response(res);
    return oauth.authorize(request, response, options)
      .then(function(code) {
        res.locals.oauth = {code: code};
        next();
      })
      .catch(function(err) {
        // handle error condition
      });
  }
}

token(request, response, [options], [callback])

Retrieves a new token for an authorized token request.

Arguments:

Name Type Description
request Request Request object.
response Response Response object.
[options={}] Object Handler options.
[options.accessTokenLifetime=3600] Number Lifetime of generated access tokens in seconds (default = 1 hour).
[options.refreshTokenLifetime=1209600] Number Lifetime of generated refresh tokens in seconds (default = 2 weeks).
[options.allowExtendedTokenAttributes=false] Boolean Allow extended attributes to be set on the returned token (see remarks section).
[options.requireClientAuthentication={}] Object Require a client secret (see remarks section). Defaults to true for all grant types.
[options.alwaysIssueNewRefreshToken=true] Boolean Always revoke the used refresh token and issue a new one for the refresh_token grant.
[options.extendedGrantTypes={}] Object Additional supported grant types.
[callback=undefined] Function Node-style callback to be used instead of the returned Promise.

Return value:

A Promise that resolves to the token object returned from Model#saveToken(). In case of an error, the promise rejects with one of the error types derived from OAuthError.

Possible errors include but are not limited to:

InvalidGrantError:
The access token request was invalid or not authorized.

The returned Promise must be ignored if callback is used.

Remarks:

If options.allowExtendedTokenAttributes is true any additional properties set on the object returned from Model#saveToken() are copied to the token response sent to the client.

By default all grant types require the client to send it’s client_secret with the token request. options.requireClientAuthentication can be used to disable this check for selected grants. If used, this server option must be an object containing properties set to true or false. Possible keys for the object include all supported values for the token request’s grant_type field (authorization_code, client_credentials, password and refresh_token). Grants that are not specified default to true which enables verification of the client_secret.

let options = {
  // ...
  // Allow token requests using the password grant to not include a client_secret.
  requireClientAuthentication: {password: false}
};

options.extendedGrantTypes is an object mapping extension grant URIs to handler types, for example:

let options = {
  // ...
  extendedGrantTypes: {
    'urn:foo:bar:baz': MyGrantType
  }
};

For information on how to implement a handler for a custom grant type see Extension Grants.

const oauth = new OAuth2Server({model: ...});

function tokenHandler(options) {
  return function(req, res, next) {
    let request = new Request(req);
    let response = new Response(res);
    return oauth.token(request, response, options)
      .then(function(code) {
        res.locals.oauth = {token: token};
        next();
      })
      .catch(function(err) {
        // handle error condition
      });
  }
}