Configure Authentication

Configure user authentication, admin credentials, and optional OAuth providers.

Note

For a feature overview of authentication and authorization, see Access Control.

Architecture

The framework uses two components for access control:

Component	Purpose
Better Auth	User authentication, sessions, and OAuth providers
SpiceDB	Fine-grained authorization and permission checks

Better Auth handles user sign-in and supports many authentication plugins including GitHub, Microsoft, SAML, passkeys, and more. See the Better Auth documentation to add additional sign-in methods.

SpiceDB manages organization and project-level permissions using a relationship-based access control model.

Prerequisites

Docker Compose environment running (see Local Development)
At least one AI provider API key configured

Environment Variables Reference

Authentication

Variable	Required	Description
`BETTER_AUTH_SECRET`	Yes	Secret for session encryption (32+ chars)
`INKEEP_AGENTS_MANAGE_UI_USERNAME`	Yes	Initial admin email address
`INKEEP_AGENTS_MANAGE_UI_PASSWORD`	Yes	Initial admin password (8+ chars)

Authorization

Variable	Required	Description
`SPICEDB_ENDPOINT`	Yes	SpiceDB gRPC endpoint (default: `localhost:50051`)
`SPICEDB_PRESHARED_KEY`	Yes	SpiceDB preshared key for authentication

OAuth Providers (Optional)

Variable	Required	Description
`PUBLIC_GOOGLE_CLIENT_ID`	No	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret
`PUBLIC_MICROSOFT_CLIENT_ID`	No	Microsoft Entra ID application (client) ID
`MICROSOFT_CLIENT_SECRET`	No	Microsoft Entra ID client secret

Configuring Authentication

Authentication is enabled by default. Configure the required environment variables to set up your admin credentials and session security.

Generate a secret

Create a secure secret for session encryption:

openssl rand -base64 32

Configure environment variables

Add these to your .env file:

.env

# Authentication secret (paste your generated secret)
BETTER_AUTH_SECRET=<your-generated-secret>

# Initial admin credentials
INKEEP_AGENTS_MANAGE_UI_USERNAME=admin@example.com
INKEEP_AGENTS_MANAGE_UI_PASSWORD=<secure-password-8-chars-min>

# Authorization (SpiceDB)
SPICEDB_ENDPOINT=localhost:50051
SPICEDB_PRESHARED_KEY=dev-secret-key

Restart services

docker compose up -d

Open http://localhost:3000. When using pnpm dev, you'll be signed in automatically using the credentials configured above. For Docker deployments, sign in manually with your admin credentials.

Adding OAuth Providers

Create OAuth application

Go to the Google Cloud Console
Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Select Web application

Configure redirect URI

Add this authorized redirect URI:

{your-app-url}/api/auth/callback/google

For local development: http://localhost:3002/api/auth/callback/google

Add credentials to environment

.env

PUBLIC_GOOGLE_CLIENT_ID=<your-client-id>
GOOGLE_CLIENT_SECRET=<your-client-secret>

Restart services

docker compose up -d

The Google sign-in option will now appear on the login page.

Register an application

Go to the Azure Portal
Navigate to Microsoft Entra ID → App registrations → New registration
Give the app a name (e.g. Inkeep Agents)
Under Supported account types, choose the audience you want to allow:
- Accounts in this organizational directory only — restricts sign-in to your Entra tenant
- Accounts in any organizational directory — any Entra tenant
- Accounts in any organizational directory and personal Microsoft accounts — matches the default (common) tenant behavior used by the framework

Configure redirect URI

Under Authentication → Platform configurations → Add a platform → Web, add this redirect URI:

{your-app-url}/api/auth/callback/microsoft

For local development: http://localhost:3002/api/auth/callback/microsoft

Create a client secret

Under Certificates & secrets → Client secrets → New client secret, create a secret and copy the Value (not the Secret ID) — it is only shown once.

Add credentials to environment

Copy the Application (client) ID from the app's Overview page and the client secret you just created:

.env

PUBLIC_MICROSOFT_CLIENT_ID=<your-application-client-id>
MICROSOFT_CLIENT_SECRET=<your-client-secret-value>

By default, the framework uses Microsoft's common tenant, which allows any work, school, or personal Microsoft account to sign in. To restrict sign-in to a specific Entra tenant, pass tenantId through your createAgentsAuth() configuration in code — there is no env var for tenant scoping.

Restart services

docker compose up -d

The Microsoft sign-in option will now appear on the login page.

Troubleshooting

Verify these environment variables are set correctly:

INKEEP_AGENTS_MANAGE_UI_USERNAME — must be a valid email format
INKEEP_AGENTS_MANAGE_UI_PASSWORD — must be at least 8 characters

Ensure both PUBLIC_GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set
Verify the redirect URI in Google Cloud Console matches your app URL exactly

Ensure both PUBLIC_MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET are set
Verify the redirect URI in the Azure Portal app registration matches your app URL exactly (path must be /api/auth/callback/microsoft)
If a user belonging to your Entra tenant is refused, confirm the app registration's Supported account types setting permits their account kind
Ensure you copied the client secret's Value, not its Secret ID

Users can't see projects

Organization Members need explicit project-level roles to access projects. Either:

Assign them a project role via Project Settings → Members
Promote them to organization Admin (gives access to all projects)

On this page