Skip to content

OAuth

This document provides comprehensive instructions for configuring OAuth within the Custom Connector interface.

Steps to set up an OAuth profile

  1. Manage OAuths Click on Manage OAuth in the custom connector endpoint page. This action will take you to the OAuths page.
  2. Add OAuth: On the OAuths page, you can add a new OAuth connection by clicking the Add OAuth button.
  3. Grant type: Choose the appropriate grant type from the dropdown menu. The Custom Connector supports two types of grants:
    • Client Credentials: Use this grant type if your OAuth setup involves exchanging client credentials (Client ID and Client Secret) for an access token.
    • Authorization Code: Select this grant type when your OAuth setup requires the Authorization Code flow, which involves user interaction for obtaining access.
  4. Client ID: Enter the Client ID provided by the OAuth provider. This is a unique identifier for your application.
  5. Client Secret: Input the Client Secret provided by the OAuth provider. This secret is a confidential key used for secure communication between Matillion and the authorization server.
  6. Access token URL: Specify the Access Token URL. This URL is used for requesting an access token from the authorization server. It typically follows the format: https://your_domain/oauth2/token
  7. Authorization URL (Authorization Code grant type): If you selected the Authorization Code grant type, provide the Authorization URL. This URL is used for initiating the authorization code flow, which involves user authentication and consent.
  8. Token parameter (Client Credentials grant type): By default, there is a predefined set of parameters automatically included in the access token request. However, for added flexibility, you can include additional parameters based on your specific needs.
  9. Auth parameter (Authorization Code grant type): You have default set of parameters that are automatically included in authorization requests. However, for added flexibility, you can include additional parameters based on your specific needs.
  10. Authorize: After completing the setup, click on the Authorize button. This action will save your OAuth configuration within the custom connector.

:::info{title='Note'} In specific situations, including of certain parameters in authorization requests causes issues. The Custom Connector interface has introduced the ability to selectively include or exclude parameters as needed. This enhancement is specific to the authorization request process when you opt for the Authorization Code grant type. :::

When you subsequently add the connector endpoint, you'll be able to select the created OAuth configuration from the Authentication Type dropdown menu.

How it works

  • OAuth relies on an access token, which serves as a secure key used by the custom connector for communication with the API endpoint.
  • To obtain an access token, connector needs to obtain a client ID and client secret from the authorization server. This process typically involves navigating a portal provided by the authorization server.
  • Access tokens in OAuth often have a specific scope, specifying which resources the connector is permitted to access. Scope values and associated resources are determined by the resource server.
  • In a OAuth process, there are three parties involved: custom connector (the OAuth client), the authorization server, and the resource server. The Connector dashboard initiates a request with the authorization server, receives an access token, and uses it to access protected resources on the resource server.

The process by which a client obtains authorization is referred to as a grant. Custom connector supports various grant types:

Client Credentials: The authorization server issues an access token after connector authenticates itself using the client ID and secret obtained during OAuth setup.

Authorization Code: In this flow, the authorization server provides connector with a one-time authorization code. The connector exchanges this code for an access token securely on the server side.

For security reasons, access tokens have a limited lifespan and expire after a short period of time. Some authorization servers also issue refresh tokens, which have longer validity periods and can be used to obtain new access tokens once the old ones expire. These refresh tokens, if issued, are securely managed within the Custom Connectors dashboard.