@trutify/oauth-client

OAuth Client Library geared towards Protected Resources that need to do token introspection RFC 7662, or to obtain and refresh client tokens for their own HTTP calls.

Install

$ npm install @trutify/oauth-client

Configuration

The library requires some upfront setup to be able to work as magically as it does. At the minute, it does so by looking into your environment variables (process.env), but we are planning on adding a better way to configure the library soon.

Variables

Options	Description	Default	Required
OAUTH_SERVER	The URL to reach the root of the OAuth server you're using (e.g. https://oauth.google.com)	-	✅
CLIENT_ID	The client ID of your application	-	✅
CLIENT_SECRET	The client secret of your application (required for client_secret_basic or client_secret_post authorization methods )	-	-
TOKEN_AUTH_METHOD	The authorization method used at the OAuth server by your application. Currently only supports client_secret_basic and client_secret_post	client_secret_post	-
INTROSPECTION_AUTH_METHOD	The authorization method used at the OAuth server by your application. Follows RFC 7662 and supports both bearer_token and client_secret_basic	bearer_token	-

Usage

In general, the library can be used by importing/requiring the main export of the library, then calling the desired function.

Because most of the functions make HTTP calls, they are all asynchronous functions. You can run them by either using async/await or by treating the function as a Promise.

When asking the library to obtain a client token for your application, the library will also store the token, refresh token (if it gets one) and the time of expiration in your environment variables.

This means you won't need to store them yourself or send them back to the library for refresh or validation, because the library will just load the information it needs by itself.

const oauth = require('@trutify/oauth-client'); // For commonJS
import oauth from '@trutify/oauth-client'; // For ES6

// Obtain a token client
await oauth.getClientToken();

// Validate current client token - treated as a promise here
oauth
  .validateClientToken()
  .then(token => {
    console.log('Token is valid');
  })
  .catch(error => console.error(`Something went wrong: ${error.message}`));

// Revoke client token
await oauth.revokeClientToken();

// Introspect token
await oauth.introspect('123', 'access_token');

// Run token introspection (Express Middleware)
router.get(
  '/',
  oauth.authorisation(['scope1', 'scope2'], ['authorization_code']) // Further request handlers
);

Limitations

Currently, the library only supports a single OAuth server at a time. Therefore, if you need to handle connections to multiple OAuth servers, you won't be able to use this library. We might eventually add support for multiple OAuth servers if there's enough demand for it.

Error Classes

ConfigurationError - Error thrown due to a bad configuration of the package

IntrospectionError - Error thrown due to an error in an introspection call

Tokens - Error thrown due to an error in a token request

Functions

authorisation(scopes, grantTypes, domains, [optional]) ⇒ function

Allows the server to define the particular scopes and grant types that a particular endpoint accepts. When a request reaches the server, the utility will perform an Introspection request at the OAuth server to make sure that the token is valid before making sure that the token is authorised for the endpoint, as per the rules declared.

introspect(token, tokenTypeHint) ⇒ IntrospectionResponse

Allows the client to make sure that a token that is sent to them is valid according to the OAuth Server rules, therefore facilitating more accurate authentication and authorization.

getClientToken() ⇒ OAuthTokenResponse

Obtains an OAuth Client Credentials Grant token that the client can use for requests against other protected resources or for specific interactions with the OAuth server.
The function will save the token in process.env.CLIENT_TOKEN, the potential refresh token in process.env.REFRESH_TOKEN and the date and time of token expiration in process.env.TOKEN_EXPIRATION.
Please note that the function will also return the OAuth Token response back to you, so you can deal with the token as you please.

refreshToken() ⇒ OAuthTokenResponse

Refreshes the current OAuth Client Credentials Grant token that the client had previously obtained.
The function will save the token in process.env.CLIENT_TOKEN, the potential refresh token in process.env.REFRESH_TOKEN and the date and time of token expiration in process.env.TOKEN_EXPIRATION.
Please note that the function will also return the OAuth Token response back to you, so you can deal with the token as you please.

validateToken() ⇒ OAuthTokenResponse

Validates the current OAuth Client Credentials Grant token that the client had previously obtained.
The function will not only check that the token is valid, but will also refresh or obtain a token as needed.
The function will save the token in process.env.CLIENT_TOKEN, the potential refresh token in process.env.REFRESH_TOKEN and the date and time of token expiration in process.env.TOKEN_EXPIRATION.
Please note that the function will also return the OAuth Token response back to you, so you can deal with the token as you please.

revokeToken() ⇒ OAuthTokenResponse

Revokes the current OAuth Client Credentials Grant token that the client had previously obtained.
The function will try to revoke a refresh token if present (so it completely invalidates the client access), or will fall back to revoking the access token.
The function will also delete the environment variables where tokens were stored.
This function would be useful as part of a server shutdown.

ConfigurationError - Error thrown due to a bad configuration of the package

Kind: global class

IntrospectionError - Error thrown due to an error in an introspection call

Kind: global class

Tokens - Error thrown due to an error in a token request

Kind: global class

authorisation(scopes, grantTypes, domains, [optional]) ⇒ function

Allows the server to define the particular scopes and grant types that a particular endpoint accepts. When a request reaches the server, the utility will perform an Introspection request at the OAuth server to make sure that the token is valid before making sure that the token is authorised for the endpoint, as per the rules declared.

Kind: global function Summary: Express.js Authorization Middleware
Returns: function - An Express.js middleware that will handle authorization for your route Throws:

• ConfigurationError
• IntrospectionError

Param	Type	Default	Description
scopes	Array.<string>		A list of scopes accepted by the endpoint
grantTypes	Array.<string>		A list of OAuth Grant Types accepted by the endpoint. Currently supports authorization_code, client_credentials and password
domains	Array.<string>		A list of user domains the endpoint supports
[optional]	boolean	false	Whether the authorization is optional. Defaults to false

introspect(token, tokenTypeHint) ⇒ IntrospectionResponse

Allows the client to make sure that a token that is sent to them is valid according to the OAuth Server rules, therefore facilitating more accurate authentication and authorization.

Kind: global function Summary: Performs an introspection request at the OAuth Server
Returns: IntrospectionResponse - The response provided by the OAuth Server. Would normally follow the RFC 7662 Introspection Response
Throws:

• ConfigurationError
• IntrospectionError

Param	Type	Description
token	string	The token you want to introspect
tokenTypeHint	string	(Optional) The type of token you want to introspect. Follows the OAuth Token Type Hints registry initial data

getClientToken() ⇒ OAuthTokenResponse

Obtains an OAuth Client Credentials Grant token that the client can use for requests against other protected resources or for specific interactions with the OAuth server.
The function will save the token in process.env.CLIENT_TOKEN, the potential refresh token in process.env.REFRESH_TOKEN and the date and time of token expiration in process.env.TOKEN_EXPIRATION.
Please note that the function will also return the OAuth Token response back to you, so you can deal with the token as you please.

Kind: global function Summary: Obtains an OAuth Client Credentials Grant token
Returns: OAuthTokenResponse - Returns the HTTP Response from the OAuth Token Endpoint as per RFC 6749
Throws:

• ConfigurationError
• TokensError

refreshToken() ⇒ OAuthTokenResponse

Refreshes the current OAuth Client Credentials Grant token that the client had previously obtained.
The function will save the token in process.env.CLIENT_TOKEN, the potential refresh token in process.env.REFRESH_TOKEN and the date and time of token expiration in process.env.TOKEN_EXPIRATION.
Please note that the function will also return the OAuth Token response back to you, so you can deal with the token as you please.

Kind: global function Summary: Refreshes the current Client Credentials Grant Token
Returns: OAuthTokenResponse - Returns the HTTP Response from the OAuth Token Endpoint as per RFC 6749
Throws:

• ConfigurationError
• TokensError

validateToken() ⇒ OAuthTokenResponse

Validates the current OAuth Client Credentials Grant token that the client had previously obtained.
The function will not only check that the token is valid, but will also refresh or obtain a token as needed.
The function will save the token in process.env.CLIENT_TOKEN, the potential refresh token in process.env.REFRESH_TOKEN and the date and time of token expiration in process.env.TOKEN_EXPIRATION.
Please note that the function will also return the OAuth Token response back to you, so you can deal with the token as you please.

Kind: global function Summary: Validates the current Client Credentials Grant Token
Returns: OAuthTokenResponse - Returns the HTTP Response from the OAuth Token Endpoint as per RFC 6749
Throws:

• ConfigurationError
• TokensError

revokeToken() ⇒ OAuthTokenResponse

Revokes the current OAuth Client Credentials Grant token that the client had previously obtained.
The function will try to revoke a refresh token if present (so it completely invalidates the client access), or will fall back to revoking the access token.
The function will also delete the environment variables where tokens were stored.
This function would be useful as part of a server shutdown.

Kind: global function Summary: Revokes the current Client Credentials Grant Token
Returns: OAuthTokenResponse - Returns the HTTP Response from the OAuth Token Endpoint as per RFC 6749
Throws:

• ConfigurationError
• TokensError