OAuth2.0 Configuration and Technical Details

Within this article, we will be digging deep into the technical details of how Tulip implements OAuth for Connector Authentication. OAuth is powerful, but this comes with some added complexity. This guide is intended to address any technical questions around what Tulip supports, and how it is integrated.

Note: The Client Credentials flow differs some from the authorization code flow. Steps 1 and 2 are not relevant for the Client Credential flow.

Tulip Authorization Code Flow

Tulip initiates the authentication process when testing a Connector or running a Connector Function within an application.

1. Redirect to Authorization Server:

Tulip application redirects the user to the Authorization Server (AS) along with specific parameters, including the response_type (set to "code" for Authorization Code Flow), client_id (assigned in the connector UI), redirect_uri (predefined by Tulip), scope and audience (set in UI), and state (a random string to protect against Cross-Site Request Forgery attacks).

Example:

GET /authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE&audience=AUDIENCE&state=STATE

2. User grants consent:

The Authorization Server authenticates the user and presents them with a consent screen. The user can review the requested permissions and decide whether to grant or deny access to the third-party application.

3. Authorization Code:

If the user grants consent, the Authorization Server generates an authorization code and redirects the user back to Tulip along with the authorization code. The state parameter is also included, allowing the client to verify the integrity of the response. This state parameter must match the state parameter passed at Step 1.

Example redirect to the client's redirect URI:

REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE

4. Token Request:

The client now has the authorization code and uses it to make a secure, server-to-server request to the Authorization Server's token endpoint. The client includes the grant_type (set to "authorization_code"), client_id, client_secret (a secret known only to the client and the Authorization Server), redirect_uri, and the authorization code.

Example token request:

POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

5. Access Token Response:

If the authorization code is valid, the Authorization Server responds with an access token and, optionally, a refresh token. The access token is used by the client to authenticate itself when making requests to the protected API on behalf of the user.

Example token response:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "SCOPE"
}

6. Accessing the Resource Server:

Tulip can now use the obtained access token to make authorized requests to the Resource Server (API) on behalf of the user. The access token is usually included in the Authorization header of the HTTP request.

Example API request:

GET /api/resource
Authorization: Bearer ACCESS_TOKEN

Managing Token Expiration with Refresh Tokens

Authorization servers typically set expiration dates for tokens to regulate access, with varying expiration windows depending on the interfaced system. However, short-lived tokens pose a challenge as constant user authentication disrupts the user experience in Tulip applications.

To address this issue, OAuth supports refresh tokens. While optional, they are highly recommended as they streamline the user experience by allowing Tulip to refresh tokens seamlessly without requiring manual input from operators.

How Tulip Manages Token Refresh

When Tulip detects that an access token has expired, it automatically attempts to use the associated refresh token to obtain a new token. The primary objective is to minimize user reauthentication. The following steps outline the logic executed by Tulip:

1. Expiration Detection:

   • Tulip identifies an expired token based on its expires_in attribute received in step 5 of the authentication flow.

2. Token Flow Attempt:

   • Tulip initiates the token flow using the refresh_token grant type, replacing the authorization_code grant type used in the initial authentication flow.

3. Token Validation:

   • If a new token is obtained, Tulip stores it and proceeds to execute the user-requested connector function.
     • If successful, data is provided to the Tulip app runtime.
     • If the new token fails with an OAuth error, Tulip retries the process up to 5 times, reverting to step 1 each time.
     • If the new token fails with any other error, an error is displayed in the player runtime.

4. Handling Token Absence:

   • If a new token is not provided, Tulip prompts the user in the player to undergo authentication, initiating the entire authentication process.
   • Upon completion, the connector function is executed, and data is returned.

By implementing refresh tokens, Tulip ensures a smoother user experience by intelligently managing token expiration and renewal, minimizing disruptions in workflow.

Further Reading

• Introduction to Tulip Connector Hosts
• Connector Snapshotting
• OAuth2.0 Explained