diff --git a/.travis.yml b/.travis.yml index 44c950beb..1ba9eefaa 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,5 +7,7 @@ node_js: - 6.0 - 7 - 7.0 + - 8 + - 8.0 sudo: false diff --git a/CHANGELOG.md b/CHANGELOG.md index dbd25a6a4..2d784f6e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ ## Changelog +### 3.0.0 +* Complete re-write, with Promises and callback support +* Dropped support for node v0.8, v0.10, v0.12 +* Supports Node v4, v6, v7, and v8. Will continue support for node current and active LTS versions +* For migration guide, see https://oauth2-server.readthedocs.io/en/latest/misc/migrating-v2-to-v3.html + ### 2.4.1 - Fix header setting syntax diff --git a/README.md b/README.md index 63ed08fd9..b2a04b185 100644 --- a/README.md +++ b/README.md @@ -36,20 +36,13 @@ The *oauth2-server* module is framework-agnostic but there are several officiall Most users should refer to our [Express](https://github.com/oauthjs/express-oauth-server/tree/master/examples) or [Koa](https://github.com/oauthjs/koa-oauth-server/tree/master/examples) examples. -Examples for v3 are yet to be made. Examples for v2 can still be found [here](https://github.com/oauthjs/node-oauth2-server/tree/b36a06b445ad0a676e6175d68a8bd0b2f3353dbf/examples). - -~~(If you're implementing a custom server, we have many examples available:)~~ - -~~(- A simple **password** grant [example](https://github.com/oauthjs/node-oauth2-server/tree/master/examples/password).)~~ -~~(- A more complex **password** and **refresh_token** grant [example](https://github.com/oauthjs/node-oauth2-server/tree/master/examples/refresh-token).)~~ -~~(- An advanced **password**, **refresh_token** and **authorization_code** grant [example](https://github.com/oauthjs/node-oauth2-server/tree/master/examples/authorization-code) with scopes.)~~ - +Examples for v3 are yet to be made. ## Upgrading from 2.x -This module has been rewritten using a promise-based approach, introducing changes to the API and model specification. +This module has been rewritten using a promise-based approach, introducing changes to the API and model specification. v2.x is no longer supported. -Please refer to our [3.0 migration guide](https://github.com/oauthjs/node-oauth2-server/wiki/Migrating-from-2-x-to-3-x) for more information. +Please refer to our [3.0 migration guide](https://oauth2-server.readthedocs.io/en/latest/misc/migrating-v2-to-v3.html) for more information. ## Tests diff --git a/docs/misc/migrating-v2-to-v3.rst b/docs/misc/migrating-v2-to-v3.rst index 5e777115e..5a3ec6431 100644 --- a/docs/misc/migrating-v2-to-v3.rst +++ b/docs/misc/migrating-v2-to-v3.rst @@ -2,99 +2,115 @@ 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. +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 +----------- +Middlewares +----------- - The naming of the exposed middlewares has changed to match the OAuth2 _RFC_ more closely. Please refer to the table below: +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) | ++-------------------+------------------------------------------------+ +| lockdown | **removed** (specific to *Express* middleware) | ++-------------------+------------------------------------------------+ -## Server options +-------------- +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 milliseconds that the authorization code is active for - * `accessTokenLifetime`: **default 3600** Default number of milliseconds that an access token is valid for - * `refreshTokenLifetime`: **default 1209600** Default number of milliseconds 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. +* `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 milliseconds that the authorization code is active for +* `accessTokenLifetime`: **default 3600** Default number of milliseconds that an access token is valid for +* `refreshTokenLifetime`: **default 1209600** Default number of milliseconds 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 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). +* `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 +------------------- +Model specification +------------------- - * `generateAccessToken(client, user, scope)` is **optional** and should return a _String. +* `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`) - * `generateAuthorizationCode()` is **optional** and should return a _String. +* `getAuthCode()` was renamed to `getAuthorizationCode(code)` and should return: - * `generateRefreshToken(client, user, scope)` is **optional** and should return a _String. + * `client` (`Object`), containing at least an `id` property that matches the supplied client + * `expiresAt` (`Date`) + * `redirectUri` (optional `String`) + * `user` (`Object`) - * `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_) +* `getClient(clientId, clientSecret)` should return an object with, at minimum: + + * `redirectUris` (`Array`) + * `grants` (`Array`) - * `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_) +* `getRefreshToken(token)` should return an object with: - * `getClient(clientId, clientSecret)` should return an object with, at minimum: - * `redirectUris` (_Array_) - * `grants` (_Array_) + * `refreshToken` (`String`) + * `client` (`Object`), containing at least an `id` property that matches the supplied client + * `refreshTokenExpiresAt` (optional `Date`) + * `scope` (optional `String`) + * `user` (`Object`) - * `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. - * `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. - * `getUserFromClient(client)` should return an object: - * No longer requires that `id` be returned. +* `grantTypeAllowed()` was **removed**. You can instead: - * `grantTypeAllowed()` was **removed**. You can instead: - * Return _falsy_ in your `getClient()` - * Throw an error in your `getClient()` + * Return *falsy* in your `getClient()` + * Throw an error in your `getClient()` - * `revokeAuthorizationCode(code)` is **required** and should return true +* `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: - * `revokeToken(token)` is **required** and should return true + * `accessToken` (`String`) + * `accessTokenExpiresAt` (`Date`) + * `client` (`Object`) + * `refreshToken` (optional `String`) + * `refreshTokenExpiresAt` (optional `Date`) + * `user` (`Object`) - * `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: - * `saveAuthCode()` was renamed to `saveAuthorizationCode(code, client, user)` and should return: - * `authorizationCode` (_String_) + * `authorizationCode` (`String`) - * `validateScope(user, client, scope)` should return a _Boolean_. +* `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). diff --git a/package.json b/package.json index d6c303778..6992ef15e 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "oauth2-server", "description": "Complete, framework-agnostic, compliant and well tested module for implementing an OAuth2 Server in node.js", - "version": "3.0.0-b4", + "version": "3.0.0", "keywords": [ "oauth", "oauth2"