In this guide, you will learn...
- Brief overview of OAuth 2.0
- How to set-up OAuth 2.0 for a Connector
- OAuth 2.0 Authentication types within Tulip
Before reading this article, you should first read "An Overview of HTTP Connectors" to get a full understanding of the capabilities of HTTP connectors within Tulip.
Overview of OAuth 2.0
Open Authorization 2.0, or OAuth 2.0, is a widely used authorization protocol. It allows you to build out a simplified authorization code flow, granting access to third party apps (Tulip) to access the data from the HTTP service on behalf of the user.
Tulip supports OAuth 2.0 for the authentication of connectors. It's important to note this article is not for Tulip account login.
For more background on OAuth 2.0, check out this article.
Setting up OAuth 2.0
- Create a new connector function, or navigate to the one you wish to enable OAuth 2.0 for
- Open the 'Edit Connection Details' modal by clicking on the connector. Note: If you have multiple server environments (ex: Production, Testing & Development), you'll need to authenticate both
3. In the 'Edit Connection Details' modal, click on 'Edit Headers'
4. Select one of the three OAuth 2.0 types:
OAuth 2 (Admin)
- Requires the authentication of one person only during the test of the connector function (You will be redirected through authentication flow when you test the connector)
- After authentication, a new token flow will only happen if the access token or refresh token is expired
- Intended to be set-up by someone with account admin access of the system you wish to connect to
- One token per account: anytime anyone in the account makes a call via the connector, they will use the one stored authentication token
OAuth 2 (Operator)
- Requires the authentication of every operator/user from within the player (Each operator will be redirected through authentication flow when they run connector in Player)
- Every user will have their own authentication token stored
- One token per user: when a call is made via the api, the user's own authentication token will be used
OAuth 2 (Bearer Token)
- Requires you to manually enter your token to set-up
- Tulip will not initiate an authorization flow in this case
- For information on how to get your token, reference the documentation of the system you're trying to connect to
5. Fill out the following information within the Authentication & Headers section of the modal:
For details on how to find this information, reference the documentation of the system you're trying to connect to, or contact Tulip Support at email@example.com or via Live Chat.
- Redirect URL: Where the Tulip user is redirected to grant permission
- Authorization Code URL: Where the Tulip server exchanged the one-time authorization grant obtained by the user after granting Tulip permission. This response contains the OAuth 2.0 access and refresh tokens
- Access Token URL: Where refresh tokens are enhanced for new access tokens, replacing expired tokens
- Client ID
- Client Secret
- Scope: Define the scope of the connectors functionality. (Please note the formatting of your scope will depend on the system you're connecting to).
- Send token request data as query params: If you'd like to send your request data as query params, enable this button. (Reference the documentation of the system you're connecting to see if the system requires the data to be in the query params).
Tokens are scope specific, and it's important to note that scope is defined at the connector level, not the connector function level. For example, if you wish to have both read and write access within this connector, then you need to define both within your scope.
OAuth 2.0 System Integration
- Microsoft 365
- Google (G Suite)
Note: To turn this feature on, contact support at firstname.lastname@example.org, or via live chat.