Configure Authentik OAuth for Keyloom authentication - setup, scopes, and self-hosted identity provider integration.

Authentik Provider

Enable Authentik OAuth authentication in your Keyloom application for self-hosted identity provider integration.

Prerequisites

Authentik instance running and accessible
Authentik application configured for OAuth2/OpenID Connect
Keyloom handler configured at /api/auth/[...keyloom]

Setup

1. Configure Authentik Application

Log into your Authentik admin interface
Go to Applications → Applications
Click Create to create a new application
Fill in the application details:
- Name: Your application name
- Slug: URL-friendly identifier
- Provider: Create a new OAuth2/OpenID Provider

2. Create OAuth2/OpenID Provider

In the application creation form, click Create next to Provider
Choose OAuth2/OpenID Provider
Configure the provider:
- Name: Provider name
- Authorization flow: Choose appropriate flow (usually "default-authorization-flow")
- Client type: Confidential
- Client ID: Auto-generated or custom
- Client Secret: Auto-generated or custom
- Redirect URIs: ${YOUR_APP_URL}/api/auth/oauth/authentik/callback
- Scopes: openid profile email (minimum recommended)

3. Get Credentials and URLs

From your Authentik provider settings:

Client ID: Your OAuth2 client ID
Client Secret: Your OAuth2 client secret
Authentik Base URL: Your Authentik instance URL (e.g., https://auth.example.com)

4. Environment Variables

.env.local

AUTHENTIK_CLIENT_ID=your_authentik_client_id
AUTHENTIK_CLIENT_SECRET=your_authentik_client_secret
AUTHENTIK_BASE_URL=https://your-authentik-instance.com

5. Configure Provider

keyloom.config.ts

import { defineKeyloom } from "@keyloom/core";
import { authentik } from "@keyloom/providers";

export default defineKeyloom({
  providers: [
    authentik({
      clientId: process.env.AUTHENTIK_CLIENT_ID!,
      clientSecret: process.env.AUTHENTIK_CLIENT_SECRET!,
      baseUrl: process.env.AUTHENTIK_BASE_URL!, // e.g., "https://auth.example.com"
    }),
  ],
  // ... other config
});

Configuration Options

authentik({
  clientId: string;
  clientSecret: string;
  baseUrl: string; // Your Authentik instance URL
  scopes?: string[]; // Default: ["openid", "profile", "email"]
})

Available Scopes

Authentik supports standard OpenID Connect scopes:

Standard Scopes

openid - Required for OpenID Connect
profile - Basic profile information (name, username, etc.)
email - Email address
groups - User group memberships
offline_access - Refresh token support

Custom Scopes

Authentik allows you to define custom scopes based on your needs:

Custom attribute scopes
Application-specific scopes
Role-based scopes

Default Scopes: openid profile email

User Profile

Authentik returns the following user information (based on configured scopes):

{
  id: string;           // Authentik user ID (sub claim)
  email: string | null; // Email address
  name: string | null;  // Full name or preferred username
  image: string | null; // Avatar URL (if configured)
  // Additional custom claims available based on Authentik configuration
}

Usage Example

components/AuthentikSignIn.tsx

import { useLogin } from "@keyloom/react";

export function AuthentikSignIn() {
  const { login, loading } = useLogin();

  const handleAuthentikLogin = async () => {
    await login({
      provider: "authentik",
      callbackUrl: "/dashboard",
    });
  };

  return (
    <button onClick={handleAuthentikLogin} disabled={loading}>
      {loading ? "Connecting..." : "Sign in with Authentik"}
    </button>
  );
}