Skip to content

Latest commit

 

History

History
129 lines (89 loc) · 8.04 KB

API.md

File metadata and controls

129 lines (89 loc) · 8.04 KB
Raw

API

Node.js client library for OAuth2. OAuth2 allows users to grant access to restricted resources by third party applications, giving them the possibility to enable and disable those accesses whenever they want.

Options

Simple OAuth2 grant classes accept an object with the following params.

  • client - required object with the following properties:

    • id - Service registered client id. When required by the spec this value will be automatically encoded. Required
    • secret - Service registered client secret. When required by the spec this value will be automatically encoded. Required
    • idParamName - Parameter name used to send the client id. Defaults to client_id
    • secretParamName - Parameter name used to send the client secret. Defaults to client_secret

  • auth - required object with the following properties:

    • tokenHost - Base URL used to obtain access tokens. Required
    • tokenPath - URL path to obtain access tokens (See url resolution notes). Defaults to /oauth/token
    • refreshPath - URL path to refresh access tokens (See url resolution notes). Defaults to auth.tokenPath
    • revokePath - URL path to revoke access tokens (See url resolution notes). Defaults to /oauth/revoke
    • authorizeHost - Base URL used to request an authorization code. Only valid for AuthorizationCode. Defaults to auth.tokenHost value
    • authorizePath - URL path to request an authorization code (See url resolution notes). Only valid for AuthorizationCode. Defaults to /oauth/authorize

  • http optional object used to set default options to the internal http library (wreck). All options except baseUrl are allowed

    • json: JSON response parsing mode. Defaults to strict
    • redirects Number or redirects to follow. Defaults to false (no redirects)
    • headers Http headers
      • accept Acceptable http response content type. Defaults to application/json
      • authorization Always overriden by the library to properly send the required credentials on each scenario

  • options additional options to setup how the module perform requests

    • scopeSeparator Scope separator character. Some providers may require a different separator. Defaults to empty space
    • credentialsEncodingMode Setup how credentials are encoded when options.authorizationMethod is header. Use loose if your provider doesn't conform to the OAuth 2.0 specification. Defaults to strict
    • bodyFormat - Request's body data format. Valid options are form or json. Defaults to form
    • authorizationMethod - Method used to send the client.id/client.secret authorization params at the token request. Valid options are header or body. If set to body, the bodyFormat option will be used to format the credentials. Defaults to header

URL resolution

URL paths are relatively resolved to their corresponding host property using the Node WHATWG URL resolution algorithm.

Grant Types

new AuthorizationCode(options)

This submodule provides support for the OAuth2 Authorization Code grant type.

.authorizeURL([authorizeOptions]) => String

Creates the authorization URL from the client configuration and the authorize options. The following are supported authorize options:

  • redirectURI String representing the registered application URI where the user is redirected after authentication
  • scope String or array of strings representing the application privileges
  • state String representing an opaque value used by the client to main the state between the request and the callback

Additional options will be automatically serialized as query params in the resulting URL.

await .getToken(params, [httpOptions]) => AccessToken

Get a new access token using the current grant type.

  • params
    • code Authorization code received by the callback URL
    • redirectURI Application callback URL
    • [scope] Optional string or array including a subset of the original client scopes to request

Additional options will be automatically serialized as params for the token request.

  • httpOptions All wreck options can be overriden as documented by the module http options.

.createToken(token) => AccessToken

Creates a new access token by providing a token object as specified by RFC6750.

new ResourceOwnerPassword(options)

This submodule provides support for the OAuth2 Resource Owner Password Credentials grant type.

await .getToken(params, [httpOptions]) => AccessToken

Get a new access token using the current grant type.

  • params
    • username User identifier
    • password User password
    • [scope] Optional string or array including a subset of the original client scopes to request

Additional options will be automatically serialized as params for the token request.

  • httpOptions All wreck options can be overriden as documented by the module http options.

.createToken(token) => AccessToken

Creates a new access token by providing a token object as specified by RFC6750.

new ClientCredentials(options)

This submodule provides support for the OAuth2 Client Credentials grant type.

await .getToken(params, [httpOptions]) => AccessToken

Get a new access token using the current grant type.

  • params
    • [scope] Optional string or array including a subset of the original client scopes to request

Additional options will be automatically serialized as params for the token request.

  • httpOptions All wreck options can be overriden as documented by the module http options.

.createToken(token) => AccessToken

Creates a new access token by providing a token object as specified by RFC6750.

AccessToken

.expired([expirationWindowSeconds]) => Boolean

Determines if the current access token is definitely expired or not

  • expirationWindowSeconds Window of time before the actual expiration to refresh the token. Defaults to 0.

await .refresh(params, [httpOptions]) => AccessToken

Refreshes the current access token. The following params are allowed:

  • params
    • [scope] Optional string or array including a subset of the original token scopes to request
  • httpOptions All wreck options can be overriden as documented by the module http options.

Additional options will be automatically serialized as query params for the token request.

await .revoke(tokenType, [httpOptions])

Revokes either the access or refresh token depending on the {tokenType} value. Token type can be one of: access_token or refresh_token.

  • httpOptions All wreck options can be overriden as documented by the module http options.

await .revokeAll([httpOptions])

Revokes both the current access and refresh tokens

  • httpOptions All wreck options can be overriden as documented by the module http options.

.token

Immutable object containing the token object provided while constructing a new access token instance. This property will usually have the schema as specified by RFC6750, but the exact properties may vary between authorization servers.

Please also note, that the current implementation will always add an expires_at property regardless of the authorization server response, as we require it to to provide the refresh token functionality.