@node-oauth/oauth2-server

The @node-oauth/oauth2-server is a complete, RFC 6749 and RFC 6750 compliant module for implementing an OAuth2 server in Node.js.

Key capabilities include:

• Grant Types: Supports authorization_code, client_credentials, refresh_token, and password grants, as well as extension grants with scopes.
• PKCE Support: Includes support for Proof Key for Code Exchange (PKCE).
• Asynchronous API: Uses Promises and async/await (requires Babel for older environments).
• Storage Agnostic: Can be used with any storage backend such as PostgreSQL, MySQL, MongoDB, or Redis.

The Request class is a wrapper for a webserver's request object. It is used to decouple the @node-oauth/oauth2-server package from the specific request signature of your chosen webserver (e.g., Express, Koa, or native Node.js HTTP). By wrapping your server's request in this class, you ensure the OAuth2 server can interact with incoming data in a standardized way.

// Example of wrapping a standard webserver request
function (req, res, next) {
  const oauthRequest = new Request(req.headers, req.method, req.query, req.body);
}

The model is the bridge between the OAuth2 server logic and your specific system. While the library handles the overall OAuth2 workflows and RFC compliance, the model is responsible for:

• Implementing storage (e.g., PostgreSQL, MySQL, MongoDB, Redis, or In-Memory).
• Managing clients and tokens.
• Handling specific grant type requirements.

Different OAuth2 workflows (grants) require different model implementations. Refer to the model overview documentation for specific requirements per grant type.

The Model class provides the interface for abstracting storage, retrieval, and custom validation within the OAuth2 server. It acts as the bridge between the server logic and your underlying data store (e.g., a database).

Key characteristics:

• Asynchronous by default: Every model function is resolved asynchronously. This means you can use async/await, standard synchronous functions, or generators to implement the required methods.
• Extensibility: The model allows you to implement custom validation logic and manage how different OAuth2 entities are persisted and retrieved.

PKCE only protects the initial exchange of an authorization code for an access token. The code_verifier is verified exactly once during the authorization_code grant.

It is not used during the refresh_token grant. A client that used PKCE to get its initial tokens refreshes them using the standard refresh_token flow (presenting the refresh_token and, if the client is confidential, its client_secret).

When implementing model methods, you will work with several specific data object types. These objects represent the state of tokens and codes in your system.

• AccessTokenData: An object representing an access token and its associated metadata.
• RefreshTokenData: An object representing a refresh token and its associated metadata.
• AuthorizationCodeData: An object representing an authorization code and its associated metadata.

Note on custom properties: For all token types, the token.client and token.user properties can carry additional custom properties. These extra properties will be ignored by the oauth2-server core logic but can be used by your own application logic.

The OAuth2Server requires a model object to function. This object acts as an abstraction layer for storage, retrieval, and custom validation logic. Instead of the server managing a database directly, you implement a model that provides the necessary methods to interact with your data store (e.g., clients, tokens, authorization codes, and users).

Each method in your model can return either a synchronous value or a Promise (async).

Defined in RFC 6749 Section 4.3. This grant is suitable for clients that can securely obtain the resource owner's username and password.

Warning: This grant type is deprecated and considered inherently unsafe. Use it only for legacy support.

The library manages the following protocol requirements:

• Grant Flows: authorization_code, client_credentials, refresh_token, password, and extension grants.
• Validation: Authorization codes, refresh tokens, and access tokens (existence, ownership, expiry), and enforcing single-use of authorization codes.
• Security Logic: Scope parsing/validation and PKCE verification.
• Request Parsing: Reading parameters from both the query string and the request body.
• Endpoint Constraints: Enforcing that the token endpoint uses POST with Content-Type: application/x-www-form-urlencoded.
• RFC-Compliant Responses:
  • error / error_description bodies on failures.
  • Cache-Control: no-store and Pragma: no-cache on token responses.
  • WWW-Authenticate header on 401 responses.