Integrations

UniAuth connects with external services for email delivery, SMS, social login providers, event notifications, user provisioning, and caching. This page walks through each integration point with setup instructions and configuration examples.

Email (SMTP)

UniAuth sends transactional emails for account verification, password resets, two-factor OTP codes, and welcome messages. Email delivery is powered by SMTP and works with any provider that supports the standard SMTP protocol.

Configuration

You can configure SMTP in two ways: through environment variables or through the Admin Panel.

Option 1: Environment variables

# .env.local
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=SG.xxxxxxxxxxxxxxxxxxxxx
SMTP_SECURE=false
[email protected]

Option 2: Admin Panel

Ask your administrator to configure SMTP settings via the Admin Panel. Settings saved there are stored in the database and take precedence over environment variables.

Supported Providers

Console Fallback

When SMTP is not configured, UniAuth falls back to logging email contents to the server console. This is useful during local development — you can see verification links and OTP codes in your terminal output without setting up an email provider.

SMS (Twilio)

SMS delivery is required for SMS-based two-factor authentication. UniAuth uses the Twilio API to send OTP codes via text message.

Setup

1. Create a Twilio account at twilio.com.
2. Purchase a phone number with SMS capability from the Twilio console.
3. Copy your Account SID and Auth Token from the Twilio dashboard.
4. Add the following environment variables:

# .env.local
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

How It Works

When a user with SMS 2FA enabled signs in, UniAuth generates a 6-digit OTP code, encrypts it with AES-256-GCM, stores it in the database, and sends it to the user's verified phone number via Twilio. The code expires after a short validity window.

Users must verify their phone number before enabling SMS 2FA. Phone verification uses the same OTP mechanism — a code is sent to the provided number, and the user enters it to confirm ownership.

Social Login — Google

Allow users to sign in with their Google account. UniAuth handles the full OAuth 2.0 flow with PKCE (S256 code challenge) for security.

Setup

1. Go to the Google Cloud Console → APIs & Services → Credentials.
2. Click Create Credentials → OAuth client ID.
3. Select Web application as the application type.
4. Under Authorized redirect URIs, add:
   https://uniauth.id/api/auth/oauth/callback
5. Configure the OAuth consent screen with your app name, logo, and authorized domains.
6. Copy the Client ID and Client Secret.

# .env.local
GOOGLE_CLIENT_ID=123456789-abcdefghijklmnop.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxx

Once configured, the "Sign in with Google" button appears automatically on the login and registration pages. When a user signs in with Google for the first time, a new UniAuth account is created and linked. Subsequent sign-ins match the Google email to the existing account.

Social Login — GitHub

Allow users to sign in with their GitHub account. Like Google, this uses OAuth 2.0 with PKCE for secure token exchange.

Setup

1. Go to GitHub Settings → Developer settings → OAuth Apps.
2. Click New OAuth App.
3. Set the Homepage URL to your UniAuth instance URL (e.g., https://uniauth.id).
4. Set the Authorization callback URL to:
   https://uniauth.id/api/auth/oauth/callback
5. Copy the Client ID and generate a Client Secret.

# .env.local
GITHUB_CLIENT_ID=Iv1.abcdef1234567890
GITHUB_CLIENT_SECRET=abcdef1234567890abcdef1234567890abcdef12

The "Sign in with GitHub" button appears on the login page once credentials are configured. GitHub provides the user's name, email, and avatar, which are used to populate the UniAuth profile on first sign-in.

Webhooks

Webhooks allow UniAuth to send real-time HTTP notifications to your services when events occur, such as user registration, login, password changes, and 2FA status changes.

Overview

Each webhook subscription targets a URL and listens for one or more event types. When a matching event occurs, UniAuth sends a POST request to the URL with a JSON payload and an HMAC-SHA256 signature header for verification.

For complete webhook documentation, including event types, payload formats, signature verification, and retry behavior, see the Webhooks Guide.

Quick Example

// Incoming webhook payload
POST https://your-app.com/webhooks/uniauth
Content-Type: application/json
X-Webhook-Signature: sha256=7d38cdd689735b008b3c702edd92eea23791c5f6...

{
  "event": "user.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "firstName": "Alex",
    "lastName": "Johnson"
  }
}

SCIM Provisioning

SCIM (System for Cross-domain Identity Management) enables automatic user provisioning and deprovisioning from external identity providers such as Okta, Azure AD, and OneLogin.

Overview

When SCIM is configured for an OAuth client, the external IdP can automatically create, update, and deactivate user accounts in UniAuth. This eliminates manual account management for organizations using a centralized identity provider.

UniAuth implements the SCIM 2.0 protocol at the /api/scim/* endpoints. SCIM tokens are configured per OAuth client from the admin panel. For full SCIM documentation, consult the API Reference.

Supported Operations

• Create User — Provision a new account when a user is assigned in the external IdP
• Update User — Sync profile changes (name, email) from the external IdP
• Deactivate User — Disable the account when the user is unassigned or removed
• List Users — Enumerate provisioned users for sync verification

Redis

By default, UniAuth uses in-memory rate limiting, which works well for single-instance deployments. For multi-instance or high-availability setups, you can enable Redis-backed distributed rate limiting.

Configuration

# .env.local
REDIS_URL=redis://localhost:6379

# With authentication:
REDIS_URL=redis://:[email protected]:6379

# With TLS (e.g., AWS ElastiCache, Upstash):
REDIS_URL=rediss://:[email protected]:6380

What Redis Provides

• Distributed rate limiting — Rate limit counters are shared across all UniAuth instances, ensuring consistent enforcement
• Persistence across restarts — In-memory rate limit counters reset when the server restarts; Redis-backed counters survive restarts
• Horizontal scaling — Required if you run multiple UniAuth instances behind a load balancer

OAuth Clients (Sign in with UniAuth)

UniAuth is a full OAuth 2.0 Authorization Server and OpenID Connect Provider. Third-party applications can integrate "Sign in with UniAuth" to authenticate their users.

Registering an Application

Developers can register their own OAuth applications from the Account → Developer Console (up to 10 apps per user).

When registering a client, you provide:

• Application name — Displayed on the consent screen
• Redirect URIs — Allowed callback URLs after authorization
• Scopes — Which user data the app can request (openid, profile, email, phone, address)
• Grant types — Supported flows (authorization code, refresh token, client credentials, device code)

Integration Flow

Once registered, use the standard OAuth 2.0 Authorization Code flow with PKCE:

// 1. Redirect user to UniAuth authorization endpoint
https://uniauth.id/api/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  scope=openid profile email&
  state=RANDOM_STATE&
  code_challenge=PKCE_CHALLENGE&
  code_challenge_method=S256

// 2. User authenticates and consents
// 3. UniAuth redirects back with an authorization code
https://your-app.com/callback?code=AUTH_CODE&state=RANDOM_STATE

// 4. Exchange the code for tokens
POST https://uniauth.id/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://your-app.com/callback&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=PKCE_VERIFIER

For comprehensive OAuth/OIDC documentation including discovery endpoints, token formats, pairwise subject identifiers, and SDK integration guides, see the OAuth2 / OIDC documentation and SDK documentation.

Integration Summary

UniAuth is designed to work with minimal configuration. Only PostgreSQL and the core environment variables (DB_*, JWT_SECRET, ENCRYPTION_KEY) are required to get started. All other integrations can be added incrementally as your needs grow.