simple-oauth2

To handle long-lived applications, you can refresh expired access tokens.

1. Persistence: You can serialize an AccessToken to JSON to store it in a database.
2. Rehydration: Use client.createToken(parsedJson) to recreate the AccessToken instance from stored data.
3. Expiration Check: Use accessToken.expired() to check if the token is invalid. To avoid race conditions caused by network latency, pass a window in seconds (e.g., accessToken.expired(300)) to refresh the token preemptively.
4. Refresh: Call await accessToken.refresh(refreshParams) to obtain a new token.

Warning: Tokens obtained via the ClientCredentials grant may not be refreshable. You should fetch a new token instead.

// Rehydrating and refreshing a token
async function run() {
  const accessTokenJSONString = await getPersistedAccessTokenJSON();

  let accessToken = client.createToken(JSON.parse(accessTokenJSONString));

  const EXPIRATION_WINDOW_IN_SECONDS = 300;

  if (accessToken.expired(EXPIRATION_WINDOW_IN_SECONDS)) {
    try {
      const refreshParams = {
        scope: '<scope>',
      };

      accessToken = await accessToken.refresh(refreshParams);
    } catch (error) {
      console.log('Error refreshing access token: ', error.message);
    }
  }
}

All grant classes (AuthorizationCode, ResourceOwnerPassword, ClientCredentials) accept a configuration object containing client, auth, http, and options properties.

client (Required)

• id: Service registered client ID.
• secret: Service registered client secret.
• idParamName: Parameter name for client ID (defaults to client_id).
• secretParamName: Parameter name for client secret (defaults to client_secret).

auth (Required)

• tokenHost: Base URL for obtaining access tokens.
• tokenPath: URL path for tokens (defaults to /oauth/token).
• refreshPath: URL path for refreshing tokens (defaults to auth.tokenPath).
• revokePath: URL path for revoking tokens (defaults to /oauth/revoke).
• authorizeHost: Base URL for authorization codes (only for AuthorizationCode, defaults to auth.tokenHost).
• authorizePath: URL path for authorization codes (only for AuthorizationCode, defaults to /oauth/authorize).

http (Optional)

Sets default options for the internal wreck library. All options except baseUrl are allowed.

• json: JSON response parsing mode (defaults to strict).
• redirects: Number of redirects to follow (defaults to false).
• headers: HTTP headers (e.g., accept defaults to application/json). Note that authorization is managed by the library.

options (Optional)

• scopeSeparator: Character used to separate scopes (defaults to empty space).
• credentialsEncodingMode: Encoding for header authorization. Use loose if the provider is non-compliant with OAuth 2.0 spec (defaults to strict).
• bodyFormat: Request body format. Valid values: form or json (defaults to form).
• authorizationMethod: How to send credentials. Valid values: header or body (defaults to header). If body is used, bodyFormat determines the format.

The Authorization Code grant is used by confidential and public clients to exchange an authorization code for an access token.

1. Use client.authorizeURL() to generate the URL for redirecting the user to the authorization server.
2. After the user redirects back with a code, use client.getToken() to exchange that code for an access token.

async function run() {
  const client = new AuthorizationCode(config);

  const authorizationUri = client.authorizeURL({
    redirect_uri: 'http://localhost:3000/callback',
    scope: '<scope>',
    state: '<state>',
    
    customParam: 'foo', // non-standard oauth params may be passed as well
  });

  // Redirect example using Express (see http://expressjs.com/api.html#res.redirect)
  res.redirect(authorizationUri);

  const tokenParams = {
    code: '<code>',
    redirect_uri: 'http://localhost:3000/callback',
    scope: '<scope>',
  };

  try {
    const accessToken = await client.getToken(tokenParams);
  } catch (error) {
    console.log('Access Token Error', error.message);
  }
}

run();