OAuth 2.0 credentials

10 minute read

Overview

Services that use OAuth 2.0 authorization require that requests present an access_token to prove they can access the resources they are requesting. For security reasons, these access tokens are often short-lived, expiry times of 1 hour are common. This presents an issue to services that are trying to consume the resources; after an hour, the access token expires, preventing access to the resources. This makes the use of a static credential like API Key or HTTP Basic infeasible.

API Builder solves this by managing the refresh of access tokens and ensuring that there is always a valid access token available for use within the flows. To achieve this, API Builder performs a refresh token grant before the expiration of the access token to ensure it always has a valid access token. Each third-party service that wish to access will have their own policies and processes for enabling and configuring OAuth support. It is necessary to read the third-party documentation and configure the access correctly in their application, and also configure it correctly in API Builder.

Authorization code credentials

API Builder supports managing credentials for the OAuth 2.0 authorization code grant.

Configuring the Redirect URI

When configuring your external service to support OAuth, it will request a redirect URI. After the user has authorized API Builder access, this is the URI to which the browser is redirected with the authorization code. Where you configure this in your OAuth application is highly dependent on the service provider you are using. For example, if you are creating a Microsoft Application (https://apps.dev.microsoft.com), it is configured as a Platform setting.

If you are configuring a Google Application (https://console.developers.google.com), it is configured under the Restrictions.

The default Redirect URL for API Builder is http://localhost:8080/auth/callback.

As this is the URL that the user’s browser will be redirected to after they perform the authorization in the popup window, it is important to note that the Redirect URI is relative to the browser from which the authorization is performed. So by default, authorization will only work when your browser is running on the same host as the API Builder service.

There may be scenarios where the default localhost Redirect URI is not sufficient for access requirements; for example, if the developer is working on a machine that is remote to the API Builder service. The default Redirect URL is generated from the configuration values of baseurl, port, and authorization.callback. Alternatively, the redirect_uri can be set explicitly on each credential in the configuration.

However, be aware that most services require the use of HTTPs when the Redirect URI is something other than localhost. For more information on enabling HTTPs in API Builder, see Enabling TLS/SSL.

Example

Depending on the deployment scenario, not all settings may be required, but any setting that is not required must be set to null. The following is an example configuration for a credential that is accessing Google’s Gmail API:

// default.js

authorization: {
  credentials: {
    mygmail: {
      type: 'oauth2',
      flow: 'accessCode',
      authentication_url: 'https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent',
      token_url: 'https://accounts.google.com/o/oauth2/token',
      client_id: 'myid.apps.googleusercontent.com',
      client_secret: 'mysecret',
      scope: 'https://mail.google.com/',
      access_token: null,
      refresh_token: null
    }
  }
}

Many services will not issue a refresh_token by default, consult your service providers OAuth documentation for information on how to ensure that a refresh token is issued. Generally, it requires custom query parameters on the authentication URL or a custom scope setting. In this example case, the authentication_url has access_type=offline&prompt=consent, which tells Google to issue a refresh token.

Client credentials (client password)

API Builder supports managing credentials for the OAuth 2.0 client credentials grant. These tokens are automatically obtained on startup, and also refreshed before they expire.

Client password example

Depending on the deployment scenario, not all settings may be required, but any setting that is not required must be set to null. The following is an example configuration for a credential that uses a client_id and client_secret for client credentials grant.

// default.js

authorization: {
  credentials: {
    example: {
      type: 'oauth2',
      flow: 'clientCredentials',
      token_url: 'http://authz.io/token',
      client_id: 'example',
      client_secret: 'mysecret',
      scope: 'read',
      access_token: null
    }
  }
}

Client credentials (JWT client authentication)

API Builder supports managing credentials for OAuth 2.0 client credentials extention grant using JWT for client authentication. These tokens are automatically obtained on startup, and also refreshed before they expire.

JWT client authentication example

Depending on the deployment scenario, not all settings may be required, but any setting that is not required must be set to null. The following is an example configuration for a credential that uses JWT for client authentication.

// default.js

authorization: {
  credentials: {
    example: {
      type: 'oauth2',
      flow: 'clientCredentials',
      assertion_type: 'jwtClientAuth',
      token_url: 'http://authz.io/token',
      client_id: 'example',
      private_key: require('fs').readFileSync('./private.pem').toString(),
      passphrase: 'secret',
      scope: 'read',
      access_token: null
    }
  }
}

Client credentials (JWT authorization grant)

API Builder supports managing credentials for OAuth 2.0 client credentials extention grant using JWT for client authentication. These tokens are automatically obtained on startup, and also refreshed before they expire.

JWT authorization grant example

Depending on the deployment scenario, not all settings may be required, but any setting that is not required must be set to null. The following is an example configuration for a credential that uses JWT for authorization grant.

// default.js

authorization: {
  credentials: {
    example: {
      type: 'oauth2',
      flow: 'clientCredentials',
      assertion_type: 'jwtAuthGrant',
      token_url: 'http://authz.io/token',
      client_id: 'example',
      private_key: require('fs').readFileSync('./private.pem').toString(),
      passphrase: 'secret',
      scope: 'read',
      access_token: null
    }
  }
}

Managing token refresh schedule

As mentioned previously, API Builder solves the problem of expiring access tokens by refreshing them before expiration. The default behavior is for API Builder to refresh the access token on startup and then to continually refresh the access token 1 minute before the access token’s expiration. The default behavior should be sufficient for the majority of scenarios; however, finer-grained control over the refresh schedule is available by adjusting the refresh settings in the credential configuration.

Initial token grant

A common scenario that you may encounter is where you have the configuration information but no access or refresh tokens. This can happen as a result of you manually configuring a credential or when you install a Swagger document, which creates a default credential configuration. In this case, if the service supports the authorization code grant, it is possible to perform authorization from the API Builder Console UI to get the initial access token and refresh token.

In the above screenshot, the Gmail App credential and the My Onedrive credential are both OAuth 2.0 credentials that have not been authorized. Click Authorize to start the authorization process.

Once authorization is completed, the status of the credential will be updated, and the credential will be available for use in a flow.

If the service supports refresh, and the credential is configured to request a refresh token, API Builder will keep the access token valid by refreshing it before its expiry. However, these tokens are not persistent, and if API Builder is restarted, the authorization process will need to be repeated. This makes this Initial Token Grant approach only suitable for development; once in production, the tokens need to be environmentalized. For more information, see Environmentalizing Credentials.

Additional information

For additional credential management information, refer to API Builder credential management. For how-to information on accessing Gmail using a Swagger flow-node, refer to Access Gmail using a Swagger flow-node. For how-to information on accessing Microsoft OneDrive using a REST flow-node, refer to Access Microsoft OneDrive using a REST flow-node.