How to Set Up OAuth Authentication with OmniRoute Providers

OmniRoute implements a three-layer OAuth architecture that enables out-of-the-box authentication with AI providers like Claude, Gemini, and GitHub Copilot while allowing enterprise overrides via environment variables.

Setting up OAuth authentication in the OmniRoute open-source routing platform requires understanding how the provider registry, encrypted token storage, and API orchestration work together. This guide covers the complete configuration process using the actual source implementation from the diegosouzapw/OmniRoute repository, including CLI commands, environment variables, and programmatic token retrieval.

Understanding OmniRoute's OAuth Architecture

OmniRoute treats every OAuth-enabled provider as a first-class connection through three tightly-coupled layers defined in the source code.

Provider Registration Layer

The static provider list in src/shared/constants/providers/oauth.ts registers every supported OAuth provider (Claude, Gemini, GitHub, GitLab Duo, etc.). Each entry contains a public client_id embedded via resolvePublicCred() in src/lib/oauth/constants/oauth.ts, enabling zero-config installations while supporting environment overrides.

OAuth Credential Handling Layer

Access and refresh tokens are encrypted using AES-256-GCM and persisted in the SQLite provider_connections table (see src/lib/db/provider_connections.ts). The tokenRefresh service in src/sse/services/tokenRefresh.ts runs background health checks to detect tokens nearing expiry and refreshes them automatically via provider-specific implementations.

API and UI Orchestration Layer

Dynamic API routes in src/app/api/oauth/[provider]/[action]/route.ts expose endpoints for login, callback, refresh, and logout actions. These handle the OAuth flow validation, state parameter verification, and token exchange before storage.

Prerequisites and Environment Configuration

Before initiating OAuth flows, you must configure the callback URL base and optional credential overrides.

Set the public base URL to ensure providers can redirect back to your OmniRoute instance:

# .env

NEXT_PUBLIC_BASE_URL=https://omniroute.example.com

Optionally override default OAuth credentials if using your own app registration:

GITLAB_DUO_OAUTH_CLIENT_ID=your-gitlab-app-id
GITLAB_DUO_OAUTH_CLIENT_SECRET=your-gitlab-app-secret
GITHUB_COPILOT_OAUTH_CLIENT_ID=your-github-app-id

Step-by-Step OAuth Setup Guide

Configure the Base URL

The NEXT_PUBLIC_BASE_URL environment variable determines where providers redirect after consent. This value is documented in docs/reference/ENVIRONMENT.md and must be accessible to your users' browsers.

Override Default Credentials (Optional)

OmniRoute bakes public OAuth credentials into the binary for convenience, but enterprise deployments should override these via environment variables matching the pattern <PROVIDER>_OAUTH_CLIENT_ID and <PROVIDER>_OAUTH_CLIENT_SECRET as defined in src/lib/oauth/constants/oauth.ts.

Initiate the Login Flow

Via CLI:

omniroute oauth login claude
omniroute oauth login gitlab-duo

Via Dashboard:

1. Navigate to Providers → Add Provider.
2. Select your OAuth-enabled provider (e.g., GitLab Duo).
3. Click Login to launch the browser consent flow.
4. After authorization, OmniRoute exchanges the code for tokens and stores them encrypted.

The provider redirects to <BASE_URL>/callback?code=...&state=..., where the route validates state and persists credentials.

Verify Your Connection

Confirm successful authentication using the CLI:

omniroute oauth list

This displays the provider ID, associated user/email, and token expiry status by querying the provider_connections table.

Token Management and Automatic Refresh

OmniRoute handles token lifecycle automatically through the tokenRefresh service. The system:

• Detects tokens approaching expiry using TOKEN_EXPIRY_BUFFER_MS
• Calls provider-specific refresh endpoints atomically to prevent race conditions
• Updates the SQLite store via rotation maps

Manual refresh (if needed):

omniroute oauth refresh gitlab-duo

This forces tokenRefresh.refreshGitLabDuoToken() to execute immediately.

Programmatic Token Access (Node.js/TypeScript)

Access fresh tokens programmatically using the internal service layer:

import { getAccessToken } from '@omniroute/open-sse/services/tokenRefresh';

// Retrieve valid access token for GitHub Copilot
const token = await getAccessToken(
  'github', 
  { refreshToken: undefined }, 
  /*forceRefresh=*/false
);

console.log('Authorization: Bearer', token);

The routing layer (open-sse/services/combo.ts) uses hasUsableOAuthToken(providerId) from src/lib/oauth/helpers.ts to filter connections with valid tokens during request processing.

Troubleshooting and Resilience Configuration

OAuth connections participate in OmniRoute's three-layer resilience system. Configure thresholds via:

OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD=5
OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS=60000

These values in open-sse/config/constants.ts control circuit-breaking for failing OAuth endpoints.

Summary

• Provider registration happens in src/shared/constants/providers/oauth.ts with baked-in public credentials via resolvePublicCred().
• Token storage uses AES-256-GCM encryption in the SQLite provider_connections table managed by src/lib/db/provider_connections.ts.
• Automatic refresh is handled by src/sse/services/tokenRefresh.ts with configurable expiry buffers.
• Environment overrides follow the pattern <PROVIDER>_OAUTH_CLIENT_ID for enterprise OAuth apps.
• CLI workflow uses omniroute oauth login <provider>, list, and refresh commands defined in bin/cli/commands/oauth.mjs.

Frequently Asked Questions

How does OmniRoute handle OAuth token security?

OmniRoute encrypts all OAuth tokens at rest using AES-256-GCM before storing them in the SQLite provider_connections table. The encryption happens in the database layer (src/lib/db/provider_connections.ts), and tokens are only decrypted momentarily during API calls or refresh operations performed by the tokenRefresh service.

Can I use my own OAuth app instead of OmniRoute's default credentials?

Yes. While OmniRoute includes public client_id values baked into the binary via resolvePublicCred() in src/lib/oauth/constants/oauth.ts, you can override these by setting environment variables like GITLAB_DUO_OAUTH_CLIENT_ID and GITLAB_DUO_OAUTH_CLIENT_SECRET in your .env file. This is recommended for enterprise deployments requiring restricted scopes or internal OAuth apps.

What happens when an OAuth token expires?

The tokenRefresh service (src/sse/services/tokenRefresh.ts) runs background health checks that detect tokens nearing expiry based on TOKEN_EXPIRY_BUFFER_MS. It automatically calls the provider-specific refresh endpoint (e.g., refreshGitLabDuoToken()), atomically updates the stored credentials to prevent race conditions, and maintains service continuity without manual intervention.

How do I troubleshoot OAuth connection failures?

Check the circuit breaker thresholds configured in open-sse/config/constants.ts via OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD and OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS. Verify your NEXT_PUBLIC_BASE_URL matches the callback URL registered with your OAuth provider, and use omniroute oauth list to inspect token expiry states and connection metadata.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}