Integrate with OIDC

Heimdall is a passwordless OpenID Connect (OIDC) authentication server designed for secure, multi-tenant applications. This guide explains how to integrate your application with Heimdall’s OIDC endpoints to enable passwordless authentication, manage user sessions, and leverage its organizational hierarchy (users, teams, organizations). You’ll learn how to configure a client, perform the Authorization Code flow, and use Heimdall’s SDKs for Next.js, Nuxt, and Remix to simplify integration.

Overview

Heimdall supports standard OIDC flows, including Authorization Code, Implicit, and Client Credentials, with a focus on the secure Authorization Code flow. Key features include:

• Passwordless Authentication: Eliminates passwords, using secure OIDC flows for user authentication.
• Multi-Tenant Design: Organizes users into teams and organizations, with a guided onboarding flow for setup.
• OIDC Endpoints: Provides standard endpoints (e.g., /authorize, /token, /userinfo) for authentication and user data.

To integrate, you’ll:

1. Configure a client in Heimdall’s environment variables.
2. Use the Authorization Code flow to authenticate users and obtain tokens.
3. Optionally, use Heimdall’s SDKs for framework-specific integration (Next.js, Nuxt, Remix).

Configure Your Client

To authenticate with Heimdall, your application must be registered as a client. Add client details to Heimdall’s .env file, as described in the Configuration Guide. Below is an example client configuration:

# Example Client (Confidential Client)
OIDC_CLIENT_ID_1=my_client_1
OIDC_CLIENT_1_SECRET=client1_secret_value
OIDC_CLIENT_1_REDIRECT_URIS=https://app1.example.com/callback
OIDC_CLIENT_1_SCOPES=openid,profile,email
OIDC_CLIENT_1_GRANT_TYPES=authorization_code,refresh_token
OIDC_CLIENT_1_RESPONSE_TYPES=code
OIDC_CLIENT_1_TOKEN_AUTH_METHOD=client_secret_basic

Key Configuration Notes

• Client ID and Secret: Unique identifier and secret for your application. Keep the secret secure.
• Redirect URIs: Must match the callback URL in your application (e.g., https://app1.example.com/callback). Use HTTPS in production.
• Scopes: Request openid for OIDC authentication, plus optional scopes like profile and email.
• Grant Types: Use authorization_code for the Authorization Code flow. Add refresh_token for token refresh.
• Response Types: Set to code for the Authorization Code flow.
• Token Auth Method: Use client_secret_basic for confidential clients or none for public clients (e.g., SPAs).

Verify Heimdall’s OIDC configuration by querying the discovery endpoint:

curl http://localhost:8080/.well-known/openid-configuration

This returns a JSON response with endpoints like authorization_endpoint, token_endpoint, and userinfo_endpoint.

Authorization Code Flow

The Authorization Code flow is the recommended way to authenticate users with Heimdall. It involves:

1. Redirecting users to the authorization endpoint to initiate authentication.
2. Exchanging an authorization code for an access token and ID token.
3. Using the access token to fetch user information.

Step 1: Redirect to Authorization Endpoint

Redirect users to Heimdall’s /authorize endpoint with query parameters:

https://auth.yourdomain.com/authorize?client_id=my_client_1&response_type=code&scope=openid%20profile%20email&redirect_uri=https://app1.example.com/callback&state=xyz123

• client_id: Your client’s ID (e.g., my_client_1).
• response_type: Set to code for the Authorization Code flow.
• scope: Space-separated list including openid and optional scopes (e.g., profile, email).
• redirect_uri: Must match a registered URI in the client configuration.
• state: A random string to prevent CSRF attacks.

Users will authenticate (passwordlessly) and complete Heimdall’s onboarding flow (e.g., creating organizations, accepting Terms of Use). Heimdall redirects back to your redirect_uri with a code and state parameter:

https://app1.example.com/callback?code=abc123&state=xyz123

Step 2: Exchange Code for Tokens

Exchange the authorization code for an access token and ID token by sending a POST request to the /token endpoint:

curl -X POST https://auth.yourdomain.com/token   -H "Authorization: Basic $(echo -n 'my_client_1:client1_secret_value' | base64)"   -d "grant_type=authorization_code"   -d "code=abc123"   -d "redirect_uri=https://app1.example.com/callback"

• Authorization: Basic auth with client_id:client_secret base64-encoded.
• grant_type: Set to authorization_code.
• code: The code received from the redirect.
• redirect_uri: Must match the one used in the authorization request.

The response includes an access token, ID token, and optionally a refresh token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def456..."
}

Step 3: Fetch User Information

Use the access token to query the /userinfo endpoint for user details:

curl https://auth.yourdomain.com/userinfo   -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

The response includes user data based on the requested scopes (e.g., sub, name, email):

{
  "sub": "user123",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "organization": "org456",
  "team": "team789"
}

Using SDKs

For a streamlined integration, use Heimdall’s official SDKs for Next.js, Nuxt, or Remix. These SDKs provide utilities for:

• Handling OIDC redirects and token exchanges.
• Validating JWTs and managing sessions.
• Protecting routes with middleware.

Example: Next.js SDK

Install the Next.js SDK:

npm install @heimdall-auth/next

Configure middleware to protect routes:

// middleware.ts
import { withHeimdall } from '@heimdall-auth/next';

export default withHeimdall({
  clientId: 'my_client_1',
  clientSecret: 'client1_secret_value',
  issuer: 'https://auth.yourdomain.com',
  redirectUri: 'https://app1.example.com/callback',
  scopes: ['openid', 'profile', 'email'],
});

Use the SDK to fetch user data:

// pages/api/user.ts
import { getAccessToken, getUserInfo } from '@heimdall-auth/next';

export default async function handler(req, res) {
  const accessToken = await getAccessToken(req);
  const userInfo = await getUserInfo(accessToken);
  res.json(userInfo);
}

For Nuxt and Remix, similar SDKs (@heimdall-auth/nuxt, @heimdall-auth/remix) provide equivalent functionality. See the SDKs Guide for details.

Next Steps

• Quickstart: Set up Heimdall locally to test your integration.
• Configuration Guide: Configure additional clients or customize Heimdall settings.
• SDKs Guide: Explore Heimdall’s SDKs for Next.js, Nuxt, and Remix.
• Running Locally: Run Heimdall for development.
• Deploy Heimdall: Deploy Heimdall to production.
• Visit the Heimdall Repository for source code and contributions.