OAuth2Server

Represents an OAuth2 server instance.

const OAuth2Server = require('@node-oauth/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])

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.

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.

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])

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

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

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])

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.

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.

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
      });
  }
}