Quickstart

This guide will help you get Heimdall, a passwordless OpenID Connect (OIDC) authentication server, up and running locally using Docker. We’ll cover how to set up Heimdall with MongoDB, configure it using environment variables, and make your first OIDC request to verify the setup. By the end, you’ll be ready to explore Heimdall’s powerful features for secure, multi-tenant authentication.

Set Up Your Environment

To run Heimdall locally, you’ll need Docker to manage the Heimdall and MongoDB containers. Follow these steps to prepare your environment.

Step 1: Install Docker

Ensure Docker is installed on your machine. You can verify this by running:

docker --version

If Docker is not installed, follow the Docker installation guide.

Step 2: Generate RSA Keys

Heimdall requires RSA keys for signing and verifying tokens. Generate a key pair using openssl.

openssl genrsa -out private.pem 2048

Step 3: Configure Heimdall

Create an .env file with the minimal required configuration. Use the base64-encoded RSA keys from the previous step.

# Required Variables
MONGODB_URI=mongodb://localhost:27017
JWT_SECRET=
RSA_PRIVATE_KEY_BASE64=
RSA_PUBLIC_KEY_BASE64=

# Optional Variables
DATABASE_NAME=heimdall_db
BASE_URL=http://localhost:8080
PORT=8080

# Test Client
OIDC_CLIENT_ID_1=test_client
OIDC_CLIENT_1_SECRET=test_secret
OIDC_CLIENT_1_REDIRECT_URIS=http://localhost:3000/callback
OIDC_CLIENT_1_SCOPES=openid,profile
OIDC_CLIENT_1_GRANT_TYPES=authorization_code
OIDC_CLIENT_1_RESPONSE_TYPES=code
OIDC_CLIENT_1_TOKEN_AUTH_METHOD=client_secret_basic

Replace <your_secure_random_string> with a strong, random string (e.g., generated using a password manager). Refer to the Configuration Guide for all configuration options.

Run Heimdall Locally

Use Docker Compose to run Heimdall and MongoDB together for simplicity.

Step 1: Create Docker Compose File

Create a docker-compose.yml file to define the services.

version: '3.8'
services:
  heimdall:
    image: heimdall-auth/heimdall:latest
    env_file:
      - .env
    ports:
      - "8080:8080"
    depends_on:
      - mongodb
    networks:
      - heimdall-net

  mongodb:
    image: mongo:latest
    ports:
      - "27017:27017"
    networks:
      - heimdall-net

networks:
  heimdall-net:
    driver: bridge

Step 2: Start the Services

Run the containers to start Heimdall and MongoDB.

docker-compose up -d

This starts MongoDB on port 27017 and Heimdall on port 8080.

Making Your First OIDC Request

With Heimdall running, verify the setup by querying the OIDC discovery endpoint. This endpoint provides metadata about Heimdall’s OIDC configuration.

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

You should receive a JSON response like:

{
  "issuer": "http://localhost:8080",
  "authorization_endpoint": "http://localhost:8080/authorize",
  "token_endpoint": "http://localhost:8080/token",
  "userinfo_endpoint": "http://localhost:8080/userinfo",
  "jwks_uri": "http://localhost:8080/jwks",
  ...
}

This confirms Heimdall is running and configured correctly.

What’s Next?

You’ve successfully set up Heimdall locally and verified its OIDC configuration. Here are some next steps to dive deeper:

• Configure Heimdall with advanced environment variables.
• Run Heimdall Locally for detailed setup instructions.
• Integrate with OIDC to connect your application to Heimdall.
• Deploy Heimdall for production environments.
• Visit the Heimdall Repository for source code and contributions.