Skip to main content

OAuth 2

Setting up OAuth 2 in your connector can be hard, as it involves multiple moving parts. The following guide aims to simplify the process, depending on your goal.

Goal 1 - Testing OAuth 2 locally​

When adding an OAuth 2 authorization to your connector, you probably want to test it locally first. To do so, you can use the oauth2 command of the CLI, but first you need to setup things in your provider;

  1. Follow the instructions of the provider to obtain a clientId and clientSecret.
  2. When asked for a redirectUrl, put https://integrations-platform.unito.io/credentials/new/oauth2/callback-cli.
  3. Read the documentation of the provider to obtain 3 pieces of information: the token url, the authorization url and the scopes to access information on behalf of the user.

At this point you should have the following information:

CLIENT_ID = 'myBeautifulClientId';
CLIENT_SECRET = 'myBeatifulClientSecret';
PROVIDER_TOKEN_URL = 'https://app.myConnector.com/api';
PROVIDER_AUTHORIZATION_URL='https://app.myConnector.com/api';
warning

Behind the scenes, the oauth2 command uses ngrok to receive the provider's response. Make sure you've setup your ngrok account and follow the Ngrok setup guide. Using an account subject to rate limits may induces slowness, errors and headaches.

Obtaining a refresh_token and an access_token​

You can now start an OAuth 2 workflow locally with:

integration-cli oauth2

The command will auth flow with your provider to collect an access and a refresh tokens that will be stored in your .unito.json for subsequent use.

warning

The node server will run on port 9002 by default. If the port is already in use, you can use the OAUTH2_PORT env variable to change it.

OAUTH2_PORT=9999 integration-cli oauth2

Refreshing a token​

You can re-execute the oauth2 command to refresh your access_token, provided a refresh_token is present in the corresponding test account.

Alternatively, you can trigger a new auth flow to enter your credentials again by using the --reauth argument;

integration-cli oauth2 --reauth

Goal 2 - Testing OAuth 2 in Unito​

Once your OAuth 2 authorization works locally, it is time to bring it to the Unito platform, there are 2 possibilities:

Option 1​

If your provider allow multiple redirect URLs for the same application

  1. Add https://integrations-platform.unito.io/credentials/new/oauth2/callback to the authorized redirectUrl list.
  2. Make sure the corresponding authorization in your .unito.json is not for developement only (i.e. without the development keyword).
  3. Publish your connector.

Option 2​

Your provider support only 1 redirect URL

  1. Follow the instructions of the provider to obtain another pair of clientId and clientSecret meant for production.
  2. When asked for a redirectUrl, put https://integrations-platform.unito.io/credentials/new/oauth2/callback.
  3. Create another authorization entry in your .unito.json meant for production (i.e. without the development keyword).
  4. Publish your connector.