# How to Set Up OAuth Authentication with OmniRoute Providers

> Learn to set up OAuth authentication with OmniRoute providers like Claude, Gemini, and GitHub Copilot. Leverage its three-layer architecture for seamless AI integration and enterprise control.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/provider_connections.ts)). The `tokenRefresh` service in [`src/sse/services/tokenRefresh.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```dotenv

# .env

NEXT_PUBLIC_BASE_URL=https://omniroute.example.com

```

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

```dotenv
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/oauth/constants/oauth.ts).

### Initiate the Login Flow

**Via CLI:**

```bash
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:

```bash
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):

```bash
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:

```ts
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts)) uses `hasUsableOAuthToken(providerId)` from [`src/lib/oauth/helpers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```dotenv
OMNIROUTE_CIRCUIT_BREAKER_OAUTH_THRESHOLD=5
OMNIROUTE_CIRCUIT_BREAKER_OAUTH_RESET_MS=60000

```

These values in [`open-sse/config/constants.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/constants.ts) control circuit-breaking for failing OAuth endpoints.

## Summary

- **Provider registration** happens in [`src/shared/constants/providers/oauth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/provider_connections.ts).
- **Automatic refresh** is handled by [`src/sse/services/tokenRefresh.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.