OIDC Configuration

Anchor supports OpenID Connect (OIDC) authentication, enabling single sign-on with external identity providers like Keycloak, Auth0, Okta, Google, Azure AD, and more.

Overview

OIDC authentication provides:

Single Sign-On: Users authenticate through your identity provider
Automatic Account Linking: Matches users by email and links OIDC identity
Profile Sync: Name and avatar are synchronized from the provider
PKCE Support: Works with public clients (no client secret required)
Flexible Configuration: Configure via environment variables or admin UI

Configuration Methods

Environment Variables
Admin Panel

Configure OIDC using environment variables in your .env file:

.env

# Application URL for callbacks
APP_URL=http://localhost:3000

# OIDC Configuration
OIDC_ENABLED=true
OIDC_PROVIDER_NAME="Pocket ID"
OIDC_ISSUER_URL=https://auth.example.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret  # Optional for PKCE

# Optional: Hide local login form
DISABLE_INTERNAL_AUTH=false

When OIDC settings are configured via environment variables, they cannot be changed through the admin UI.

Configure OIDC through the admin panel when environment variables are not set:

Navigate to Admin Settings

Enable OIDC

Toggle OIDC authentication and fill in the provider details

Save Configuration

Save the settings. Changes take effect immediately.

If any OIDC environment variable is set (OIDC_ENABLED, OIDC_ISSUER_URL, or OIDC_CLIENT_ID), the admin UI will be locked.

Required Configuration

Parameter	Description	Required
`OIDC_ENABLED`	Enable/disable OIDC authentication	Yes
`OIDC_ISSUER_URL`	Your identity provider’s issuer URL	Yes
`OIDC_CLIENT_ID`	OAuth 2.0 client ID	Yes
`OIDC_CLIENT_SECRET`	OAuth 2.0 client secret	No*
`OIDC_PROVIDER_NAME`	Display name for the provider	No
`DISABLE_INTERNAL_AUTH`	Hide local login form	No
`APP_URL`	Base URL for callbacks	Yes

*Client secret is optional when using PKCE (Proof Key for Code Exchange) for public clients like mobile apps.

Callback URL

Configure your identity provider with this callback URL:

{APP_URL}/api/auth/oidc/callback

Examples:

Development: http://localhost:3000/api/auth/oidc/callback
Production: https://anchor.yourdomain.com/api/auth/oidc/callback

Provider-Specific Setup

Pocket ID
Keycloak
Auth0
Google

Create OAuth Application

In Pocket ID, navigate to Applications and create a new OAuth application.

Configure Redirect URI

Add the callback URL:

http://localhost:3000/api/auth/oidc/callback

Get Credentials

Copy the Client ID and optionally the Client Secret.

Configure Anchor

.env

OIDC_ENABLED=true
OIDC_PROVIDER_NAME="Pocket ID"
OIDC_ISSUER_URL=https://auth.pocketid.app
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret

Create Realm Client

In Keycloak admin console, create a new OpenID Connect client.

Configure Client Settings

Client Protocol: openid-connect
Access Type: confidential (or public for PKCE)
Valid Redirect URIs: http://localhost:3000/api/auth/oidc/callback
Standard Flow Enabled: ON

Get Issuer URL

The issuer URL format:

https://keycloak.example.com/realms/{realm-name}

Configure Anchor

.env

OIDC_ENABLED=true
OIDC_PROVIDER_NAME="Keycloak"
OIDC_ISSUER_URL=https://keycloak.example.com/realms/master
OIDC_CLIENT_ID=anchor
OIDC_CLIENT_SECRET=your-client-secret

Create Application

In Auth0 dashboard, create a Regular Web Application.

Configure URLs

Allowed Callback URLs: http://localhost:3000/api/auth/oidc/callback
Allowed Logout URLs: http://localhost:3000

Get Domain and Client ID

Find these in your application settings.

Configure Anchor

.env

OIDC_ENABLED=true
OIDC_PROVIDER_NAME="Auth0"
OIDC_ISSUER_URL=https://your-tenant.auth0.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret

Create OAuth 2.0 Client

In Google Cloud Console, create OAuth 2.0 credentials.

Configure Authorized Redirect URIs

Add: http://localhost:3000/api/auth/oidc/callback

Configure Anchor

.env

OIDC_ENABLED=true
OIDC_PROVIDER_NAME="Google"
OIDC_ISSUER_URL=https://accounts.google.com
OIDC_CLIENT_ID=your-client-id.apps.googleusercontent.com
OIDC_CLIENT_SECRET=your-client-secret

Authentication Flow

User initiates OIDC login

The user clicks “Sign in with [Provider]” button, which redirects to:

GET /api/auth/oidc/initiate?redirect=/dashboard

Optional redirect parameter specifies where to redirect after successful login.

Authorization request

Anchor generates:

CSRF protection state token
PKCE code challenge (if no client secret)
Stores state in memory with redirect URL

User is redirected to the identity provider’s authorization endpoint.

User authenticates

The user logs in at the identity provider and grants consent.

Callback with authorization code

Provider redirects back to:

GET /api/auth/oidc/callback?code=...&state=...

Token exchange

Anchor:

Validates the state parameter
Exchanges authorization code for tokens
Fetches user information from provider
Extracts claims (email, name, subject, picture)

User provisioning

Anchor finds or creates the user:

Existing User by Subject
Existing User by Email
New User

User with matching oidcSubject is found and updated with latest profile info.

Generate app tokens

Anchor creates its own access and refresh tokens for the user.

Redirect to frontend

User is redirected to:

{APP_URL}/login?code={exchange_code}&redirect=/dashboard

The frontend exchanges the one-time code for actual tokens.

Frontend token exchange

Frontend Exchange

POST /api/auth/oidc/exchange
Content-Type: application/json

{
  "code": "exchange-code-from-url"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "a8f5d234b9c1e7f3a2d6...",
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe",
    "profileImage": "/uploads/profiles/uuid-oidc-123.jpg",
    "isAdmin": false,
    "status": "active"
  },
  "redirectUrl": "/dashboard"
}

Mobile Authentication

For mobile apps, use the direct token exchange endpoint:

Mobile Login

POST /api/auth/oidc/exchange/mobile
Content-Type: application/json

{
  "access_token": "idp-access-token-from-mobile-sdk"
}

This endpoint accepts the identity provider’s access token directly and returns Anchor tokens.

Account Linking Behavior

Automatic Linking

When a user logs in with OIDC and an account with the same email exists:

If the account has no OIDC subject → Link is created automatically
If the account has a different OIDC subject → Error (email already linked)
User can now authenticate with either local credentials or OIDC

Password Management

Users created via OIDC have no password:

Cannot use local authentication endpoint
Password change endpoint returns error
Must authenticate through OIDC provider
Linked accounts retain their password capability

Profile Synchronization

On each OIDC login:

Display name is updated from provider
Profile picture is downloaded if provided
Old OIDC-downloaded avatars are replaced
Manually uploaded avatars are preserved

Disabling Local Authentication

For SSO-only deployments, disable the local login form:

.env

DISABLE_INTERNAL_AUTH=true

Ensure OIDC is properly configured before disabling local auth, or you may lock yourself out.

Required OIDC Claims

Anchor requires these standard OIDC claims:

Claim	Source	Usage
`sub`	ID token or userinfo	Unique user identifier
`email`	ID token or userinfo	User’s email address
`name`	ID token or userinfo	Display name (fallback to username or email)
`picture`	ID token or userinfo	Profile avatar URL (optional)

Checking OIDC Configuration

Get current OIDC settings:

Check Config

curl http://localhost:3000/api/auth/oidc/config

Response:

{
  "enabled": true,
  "providerName": "Pocket ID",
  "issuerUrl": "https://auth.example.com",
  "clientId": "your-client-id",
  "disableInternalAuth": false
}

Troubleshooting

Invalid or expired state

Cause: State token expired (60 seconds) or invalidSolution: Try logging in again. Ensure system clocks are synchronized.

Invalid or expired login code

Email already linked to different account

Cause: Email exists with different OIDC subjectSolution: Use the original OIDC provider or contact administrator to unlink.

OIDC provider did not return required claims

Cause: Provider missing email or sub claimSolution: Check identity provider configuration. Ensure email scope is requested.

Implementation Reference

The OIDC implementation can be found in:

Controller: server/src/auth/oidc/oidc.controller.ts
Service: server/src/auth/oidc/oidc.service.ts
Config: server/src/auth/oidc/oidc-config.service.ts
User linking: server/src/auth/oidc/oidc-user.service.ts

Next Steps

User Management

Configure registration modes for OIDC users

Local Auth

Configure local authentication alongside OIDC

Get Started

Self-Hosting

Authentication

Features

Mobile App

Administration

OIDC Configuration

Overview

Configuration Methods

Required Configuration

Callback URL

Provider-Specific Setup

Authentication Flow

Mobile Authentication

Account Linking Behavior

Disabling Local Authentication

Required OIDC Claims

Checking OIDC Configuration

Troubleshooting

Implementation Reference

Next Steps

User Management

Local Auth

Build docs developers (and LLMs) love

Get Started

Self-Hosting

Authentication

Features

Mobile App

Administration

​Overview

​Configuration Methods

​Required Configuration

​Callback URL

​Provider-Specific Setup

​Authentication Flow

​Mobile Authentication

​Account Linking Behavior

​Disabling Local Authentication

​Required OIDC Claims

​Checking OIDC Configuration

​Troubleshooting

​Implementation Reference

​Next Steps

User Management

Local Auth

Build docs developers (and LLMs) love

Overview

Configuration Methods

Required Configuration

Callback URL

Provider-Specific Setup

Authentication Flow

Mobile Authentication

Account Linking Behavior

Disabling Local Authentication

Required OIDC Claims

Checking OIDC Configuration

Troubleshooting

Implementation Reference

Next Steps