Skip to main content

External Authentication

Manage OAuth2 tokens for third-party service connectors​

The External Authentication module provides a unified way to handle OAuth2 authentication flows for third-party services like Google Drive, Google Calendar, and other OAuth-enabled connectors. It manages authorization codes, access tokens, and automatic token refresh, providing a secure and seamless authentication experience for your users.

Overview​

External Auth handles the token lifecycle for OAuth2-based connectors:

  • Secure token storage: Tokens are encrypted and stored securely per user
  • Automatic refresh: Access tokens are automatically refreshed when they expire
  • Multi-user support: Each user's tokens are isolated using unique identifiers
  • Connector agnostic: Works with any OAuth2-compliant service

Understanding OAuth2 authentication​

The OAuth2 authentication flow consists of three main steps:

  1. User Authorization: Direct users to the third-party OAuth consent screen where they authorize your application. This returns an authorization code after user consent.
  2. Token Exchange: Save the authorization code to Squid, which will exchange it for access and refresh tokens.
  3. Automatic Token Management: Squid securely stores the tokens per-user using a unique identifier (e.g. user id). Tokens are automatically refreshed when they expire.

You will implement step 1, and Squid will take care of steps 2 and 3.

Basic usage​

Prerequisites​

Before using External Auth, you need:

  1. A configured connector in the Squid Console that requires OAuth2 (e.g., Google Drive, Google Calendar)
  2. OAuth2 credentials from the third-party service (Client ID, Client Secret)
  3. Proper OAuth2 scopes for the required permissions
  4. A unique identifier for each user (e.g., user ID)

Initialize External Auth​

import { Squid } from '@squidcloud/client';

const squid = new Squid({
  appId: 'your-app-id',
  apiKey: 'your-api-key',  // Required for External Auth
  region: 'us-east-1.aws',
  environmentId: 'prod',
});

// Get the external auth client for your connector
const externalAuth = squid.externalAuth('your_connector_id');
API Key Required

External Auth requires Squid to be initialized with an API key. This provides the necessary permissions to securely store and retrieve tokens.

Obtain an Authorization Code from the Third-Party Service​

Direct users to the third-party OAuth2 consent screen, where they can authorize your application with necessary permissions.

  1. Construct the authorization URL with your OAuth2 parameters

    • Client/App ID: Your application's identifier from the OAuth provider
    • Redirect URI: The URL where users return after authorization
    • Response Type: Set to code for authorization code flow
    • Scopes: The permissions your application needs
    • Access Type: Set to offline to receive refresh tokens (provider-specific)

  2. Direct users to the authorization URL, where they'll see the OAuth consent screen requesting their approval for the requested permissions

  3. Handle the redirect after user consent, and save the auth code on success.

Provider Variations

Each OAuth2 provider may have slightly different requirements, the above is just an example. Always consult your provider's OAuth2 documentation for exact requirements.

The authorization code is single-use and typically expires within minutes, so exchange it promptly using the next steps.

Save authorization code​

After the user completes the OAuth flow and you receive an authorization code:

// Exchange authorization code for tokens and store them
const response = await externalAuth.saveAuthCode(
  authCode,    // The authorization code from the auth provider's callback
  userId   // User that the authorization code belongs to
);

console.log('Access token:', response.accessToken);
console.log('Expires at:', response.expirationTime);

The saveAuthCode method:

  • Takes an auth code and exchanges it with the external API for access and refresh tokens
  • Stores the tokens securely in Squid's storage
  • Returns the access token and expiration time
  • Associates tokens with the user id to allow multiple users to connect their accounts
  • Only needs to be called once per user

Retrieve access token​

Get a valid access token for API calls. Squid handles token refresh automatically.

const response = await externalAuth.getAccessToken(userId);

console.log('Access token:', response.accessToken);
console.log('Expires at:', response.expirationTime);

// Use the token for API calls
const apiResponse = await fetch('https://api.example.com/data', {
  headers: {
    'Authorization': `Bearer ${response.accessToken}`
  }
});

The getAccessToken method:

  • Retrieves a valid access token for the connector
  • Automatically refreshes the token if it has expired or is about to expire

Best practices​

  1. User identifier management: Use consistent, unique identifiers across your application
  2. HTTPS Only: Always use HTTPS in production for OAuth flows
  3. Scope Minimization: Only request the minimum OAuth scopes needed for your application
  4. Token caching: Let External Auth handle caching; don't store tokens in your application
  5. Rate limiting: Be aware of third-party API rate limits when using tokens

Supported connectors​

External Auth currently supports: