Migrating from 2.x to 3.x

This module is now promise-based but allows for ES6 generators, async/await (using [babel](https://babeljs.io) or node v7.6+), node-style callbacks and promises in your model.

Middlewares

The naming of the exposed middlewares has changed to match the OAuth2 _RFC_ more closely. Please refer to the table below:

oauth2-server 2.x oauth2-server 3.x
authorise authenticate
authCodeGrant authorize
grant token
errorHandler removed (now handled by external wrappers)
lockdown removed (specific to Express middleware)

Server options

The following server options can be set when instantiating the OAuth service:

  • addAcceptedScopesHeader: default true Add the X-Accepted-OAuth-Scopes header with a list of scopes that will be accepted
  • addAuthorizedScopesHeader: default true Add the X-OAuth-Scopes header with a list of scopes that the user is authorized for
  • allowBearerTokensInQueryString: default false Determine if the bearer token can be included in the query string (i.e. ?access_token=) for validation calls
  • allowEmptyState: default false If true, state can be empty or not passed. If false, state is required.
  • authorizationCodeLifetime: default 300 Default number of seconds that the authorization code is active for
  • accessTokenLifetime: default 3600 Default number of seconds that an access token is valid for
  • refreshTokenLifetime: default 1209600 Default number of seconds that a refresh token is valid for
  • allowExtendedTokenAttributes: default false Allows additional attributes (such as id_token) to be included in token responses.
  • requireClientAuthentication: default true for all grant types Allow ability to set client/secret authentication to false for a specific grant type.

The following server options have changed behavior in v3.0.0:

  • accessTokenLifetime can no longer be set to null to indicate a non-expiring token. The recommend alternative is to set accessTokenLifetime to a high value.

The following server options have been removed in v3.0.0:

  • grants: removed (now returned by the getClient method).
  • debug: removed (not the responsibility of this module).
  • clientIdRegex: removed (the getClient method can return undefined or throw an error).
  • passthroughErrors: removed (not the responsibility of this module).
  • continueAfterResponse: removed (not the responsibility of this module).

Model specification

  • generateAccessToken(client, user, scope) is optional and should return a String.
  • generateAuthorizationCode() is optional and should return a String.
  • generateRefreshToken(client, user, scope) is optional and should return a String.
  • getAccessToken(token) should return an object with:
    • accessToken (String)
    • accessTokenExpiresAt (Date)
    • client (Object), containing at least an id property that matches the supplied client
    • scope (optional String)
    • user (Object)
  • getAuthCode() was renamed to getAuthorizationCode(code) and should return:
    • client (Object), containing at least an id property that matches the supplied client
    • expiresAt (Date)
    • redirectUri (optional String)
    • user (Object)
  • getClient(clientId, clientSecret) should return an object with, at minimum:
    • redirectUris (Array)
    • grants (Array)
  • getRefreshToken(token) should return an object with:
    • refreshToken (String)
    • client (Object), containing at least an id property that matches the supplied client
    • refreshTokenExpiresAt (optional Date)
    • scope (optional String)
    • user (Object)
  • getUser(username, password) should return an object:
    • No longer requires that id be returned.
  • getUserFromClient(client) should return an object:
    • No longer requires that id be returned.
  • grantTypeAllowed() was removed. You can instead:
    • Return falsy in your getClient()
    • Throw an error in your getClient()
  • revokeAuthorizationCode(code) is required and should return true
  • revokeToken(token) is required and should return true
  • saveAccessToken() was renamed to saveToken(token, client, user) and should return:
    • accessToken (String)
    • accessTokenExpiresAt (Date)
    • client (Object)
    • refreshToken (optional String)
    • refreshTokenExpiresAt (optional Date)
    • user (Object)
  • saveAuthCode() was renamed to saveAuthorizationCode(code, client, user) and should return:
    • authorizationCode (String)
  • validateScope(user, client, scope) should return a Boolean.

The full model specification is [also available](https://oauth2-server.readthedocs.io/en/latest/model/spec.html).