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