What is OAuth2.0?

Exploring OAuth2.0

Welcome to an exploration of OAuth2.0, a powerful yet often misunderstood authentication protocol within the Tulip-verse. In this article, we will unravel the fundamentals, guide you through Tulip's supported authentication flows, demystify the configuration of your initial connector, and share quick tips for a seamless start.

OAuth2.0 can be intricate, and to keep things concise, we've omitted some detailed technical aspects from this article. If you're eager for a deeper dive into Tulip's handling of refresh tokens, scope and audience management, and custom connector configurations, we recommend checking out this in-depth OAuth2.0 technical guide.

Authentication Types

Tulip supports three OAuth2.0 authentication types: OAuth2.0 (Service Account), OAuth2.0 (User Credentials), and OAuth2.0 (Client Credentials). The key distinction lies in how credentials are shared across users and the flow that is executed against the OAuth spec. A complete list and description of the unique OAuth flows is available here: https://frontegg.com/blog/oauth-flows.

Authorization Code Flow:

• OAuth2.0 (Service Account): Uses credentials provided during connector testing for all users in the Tulip Player. Ideal for shared credentials across your organization. Admin reauthentication is required if credentials expire.
• OAuth2.0 (User Credentials): Segments authentication based on the user logged into Tulip Player. If a user hasn't authenticated or authentication expires, the user undergoes the OAuth flow within the Tulip Player.

Client Credentials Flow:

• OAuth2.0 (Client Credentials): This grant type is used by Tulip to obtain an access token by authenticating with the authorization server using the client’s credentials (client ID and client secret), typically for accessing resources on behalf of themselves rather than on behalf of a user.

Unveiling the Basics

Before delving into the specifics, we suggest acquainting yourself with Environments and gaining an overview of Connector Hosts and their functions.

OAuth2.0 serves as a mechanism for Tulip (the client) to establish its identity with your business systems.

Authorization Code Flow

Access is granted through a handshake, and Tulip primarily supports the Authorization Code Flow, the most common OAuth flow. Here's a condensed overview of how this flow unfolds:

1. User initiates the flow by clicking the Test button before saving a Connector.
2. Tulip communicates with the authorization server from your OAuth provider, sharing specific parameters such as client identity, scopes (what you're attempting to access), and other relevant details.
3. The authorization server prompts the user to grant access, exemplified below:

4. Upon user consent, the authorization server generates an authorization code and concludes the authentication window.
5. Armed with an authorization code, Tulip securely requests a token by reaching out to the token endpoint, providing the authorization code, client ID, client secret, and additional properties.
6. After validating the authorization code, the server responds with a token, and optionally, a refresh token. This token serves for user-authorized requests.
7. Tulip can now execute requests on behalf of users, with the provided token for authorization.

See the diagrams below to understand the path of execution:

Client Credentials Flow

The client credential flow is primarily used for two business systems to interact. This flow is configured once, then shared by all users.

1. User initiates the flow by clicking the Test button before saving a Connector.
2. Tulip communicates with the authorization server from your OAuth provider, sharing specific parameters such as client identity, scopes (what you're attempting to access), and other relevant details.
3. The authorization server returns an access token, assuming the Client ID and Client Secret are accurate. Optionally, a refresh token can also be returned. This token serves for user-authorized requests.
4. Tulip can now execute requests on behalf of users, with the provided token for authorization.

Configuring OAuth

Authorization Code URL

This is the URL Tulip contacts in step 2 of the authentication code flow. Found in your OAuth provider's API documentation, it typically ends in /auth or /authorize.

Note: This field is not present for Client Credentials.

Access Token URL

After the authorization server response, a request is made to the Access Token URL to obtain a token for authentication. Generally ends in /token.

Note: This field is not present for Client Credentials.

Client ID and Client Secret

Generated from your OAuth provider's UI, the Client ID is passed with the initial request for an authorization code. The Client ID and Client Secret accompany all token requests.

Default Expiration Time (seconds)

This field specifies the default time (in seconds) after which tokens will be refreshed if no expiration time is explicitly provided or defined through another mechanism outside the expires_in field.

Audience and Scope

Audience specifies the specific assets your user seeks access to, while Scope defines the actions desired on these assets. Both are conveyed during the authorization code request in step 2.

Additional Options

• Send token request data as JSON: Changes encoding type for the request sent to the token URL. Enable if needed for specific integrations.
• Send Authentication Header for refresh request: Adds an extra header to refresh requests when enabled.
• Skip User Consent Prompt: Controls the prompt attribute of the authentication code request. Disabled sets it to consent, while enabled sets it to login, letting the OAuth provider decide on the login screen to display.

Digging Deeper

Eager for more insights? Explore these articles:

• OAuth2.0 Configuration and Technical Details
• How To Run A Connector Function in Multiple Environments