OAuth 2.0 credentials

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.

Configuration

Each third-party service you are accessing will have their own policies and processes for enabling and configuring OAuth support. For API Builder to be able to connect to the third-party service and obtain and manage tokens, it uses the following:

Key Description
flow This is the OAuth flow required for this credential. Currently, the only supported flow is accessCode.
authentication_url This is the URL of the authorization endpoint. If API Builder does not have a refresh_token configured and the authentication URL has been specified, then you can perform an initial token grant to get the initial access token.
token_url This is the URL of the token endpoint. API Builder will call this endpoint to redeem an authorization code or refresh token and retrieve a new access token.
client_id This is the OAuth application ID as configured in the third party service.
client_secret This is the OAuth application secret as configured in the third party service.
scope The space-separated list of OAuth scopes for which authorization is requested.
redirect_uri

This is an override to allow customizing the redirect URI for the credential. When performing an authorization code grant, this is the URI that the authorization server will redirect to with the authorization code. In general, the default value should be sufficient, and there will be no need to set this.

Default: http://localhost:8080/auth/callback

access_token

Although most services provide short-lived access tokens, there are a few exceptions that supply long-lived access tokens.

When deploying to production, there will be no user interaction to authorize manually. Instead, the pre-obtained tokens should be provided.

refresh_token

This is the refresh token that API Builder will use to ensure that it always has a valid access token.

When deploying to production, there will be no user interaction to authorize manually. Instead, the pre-obtained tokens should be provided.

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.

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're using. For example, if you are creating a Microsoft Application (https://apps.dev.microsoft.com), it is configured as a Platform setting.

If you're 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 Enable a secure HTTPS listener.

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.

Name Value Description
refreshPolicy beforeexpiry

This is the default refresh behavior, API Builder will begin attempting to refresh the access token a configured number of seconds (refreshOffset) before the token expiry.

onexpiry Some services may not allow refresh before token expiry. API Builder will only begin attempting to refresh the access token once it has expired. This may mean there is a window where API Builder does not have an access token for the credential.
periodic Periodic refresh tells API Builder to refresh the access token on a fixed interval (refreshPeriod), independent of the token's expiration.
refreshOffest number

Set the seconds before token expiry (beforeexpiry) to perform the token refresh. Default: 60 seconds

refreshPeriod number Set the periodic interval (periodic) between token refreshes. Default: 3600 seconds

API Builder 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.

Icon

Tokens issued in this manner are not persisted and so this only suitable for use during development. When deploying to production, the tokens should be provided as environmentalized values.

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 Standalone 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.

Related Links