Skip to content

README.md

Latest commit

 

History

History
256 lines (198 loc) · 8.1 KB

README.md

File metadata and controls

256 lines (198 loc) · 8.1 KB

OIDC Mock Provider

A mock OpenID Connect (OIDC) provider for development and testing purposes, packaged as a Docker container.

Overview

This project consists of:

  • Backend: An Express.js server implementing the OIDC provider using oidc-provider
  • Frontend: A Vue.js/Quasar application providing a user interface for login and consent screens

Features

  • Complete OIDC authentication flow with authorization code grant
  • Customizable user claims
  • Customizable server configuration
  • Configurable token lifetimes
  • Dark mode support
  • Docker containerization for easy deployment

Quick Start

Using the Pre-built Container Image

The easiest way to get started is to use the pre-built Docker image from GitHub Container Registry:

# Pull the latest image
docker pull ghcr.io/juliancissen/oidc-mock:latest

# Run the container
docker run -p 8443:8443 -e PORT=8443 ghcr.io/juliancissen/oidc-mock:latest

You can also use a specific version:

# Pull a specific version
docker pull ghcr.io/juliancissen/oidc-mock:1.0.0

# Run the container with a specific version
docker run -p 8443:8443 -e PORT=8443 ghcr.io/juliancissen/oidc-mock:1.0.0

The OIDC Mock Provider will now be available at https://localhost:8443.

Running in Development Mode

# Clone the repository
git clone https://github.com/JulianCissen/oidc-mock.git
cd oidc-mock

# Start development servers and Docker container
./bin/run_dev.sh 8443

This starts:

  1. Frontend development server
  2. Backend development server
  3. Docker container with Nginx reverse proxy

Running in Production Mode

# Build and run the production Docker container
./bin/run_prod.sh 8443

Configuration

Custom Claims

You can provide a custom claims file during runtime by mounting it to the container and setting the CUSTOM_CLAIMS_PATH environment variable.

Example:

docker run -p 8443:8443 \
    -v /path/to/custom_claims.json:/app/backend/config/custom_claims.json \
    -e CUSTOM_CLAIMS_PATH=/app/backend/config/custom_claims.json \
    oidc-mock:1.0.0

Default claims structure:

[
    {
        "sub": "admin",
        "username": "admin"
    },
    {
        "sub": "foo",
        "roles": ["user"]
    }
]

Custom Server Configuration

You can provide a custom server configuration file during runtime by mounting it to the container and setting the CUSTOM_SERVER_CONFIG_PATH environment variable.

Example:

docker run -p 8443:8443 \
    -v /path/to/custom_server_config.json:/app/backend/config/custom_server_config.json \
    -e CUSTOM_SERVER_CONFIG_PATH=/app/backend/config/custom_server_config.json \
    oidc-mock:1.0.0

Server Configuration Format

The server configuration file should be a JSON file with the following structure:

{
  "provider": {
    "iss": "https://localhost:8443",
    "tokenLifetimes": {
      "accessToken": 3600,
      "authorizationCode": 60,
      "backchannelAuthenticationRequest": 600,
      "clientCredentials": 600,
      "deviceCode": 600,
      "grant": 1209600,
      "idToken": 3600,
      "interaction": 3600,
      "refreshToken": 604800,
      "session": 86400
    }
  },
  "clients": [
    {
      "client_id": "my-client",
      "client_secret": "my-secret",
      "application_type": "web",
      "redirect_uris": ["https://my-app.example.com/callback"],
      "post_logout_redirect_uris": ["https://my-app.example.com"],
      "grant_types": ["authorization_code", "refresh_token"],
      "response_types": ["code"],
      "token_endpoint_auth_method": "client_secret_basic",
      "tokenLifetimes": {
        "accessToken": 7200,
        "authorizationCode": 600
      }
    }
  ],
  "cookies": {
    "keys": ["optional-cookie-encryption-key"]
  }
}

  • provider: Configuration settings for the OIDC provider

    • iss: The issuer URL of your OIDC provider (required)
    • tokenLifetimes: Global default token lifetimes that apply to all clients

  • clients: An array of client configurations

    • client_id: The client identifier (required)
    • client_secret: The client secret (required)
    • application_type: The type of application (optional, defaults to "web")
      • web: Server-side web applications that can maintain client secrets
      • native: Native applications (mobile, desktop) that can't securely store client secrets
    • redirect_uris: Array of valid redirect URIs after authentication (required)
    • post_logout_redirect_uris: Array of valid redirect URIs after logout (required)
    • grant_types: Array of grant types (optional, defaults to ["authorization_code", "refresh_token"])
    • response_types: Array of response types (optional, defaults to ["code"])
    • token_endpoint_auth_method: Authentication method for the token endpoint (optional, defaults to "client_secret_basic")
    • tokenLifetimes: Client-specific token lifetimes - these override the global defaults (all optional)

  • cookies: Configuration for cookie handling

    • keys: Encryption keys for cookies (optional, auto-generated if not provided)

All token lifetimes are specified in seconds:

Token Type Default Value Description
accessToken 3600 Access token lifetime (1 hour)
authorizationCode 60 Authorization code lifetime (1 minute)
backchannelAuthenticationRequest 600 Backchannel authentication request (10 minutes)
clientCredentials 600 Client credentials token lifetime (10 minutes)
deviceCode 600 Device code lifetime (10 minutes)
grant 1209600 Grant lifetime (14 days)
idToken 3600 ID token lifetime (1 hour)
interaction 3600 Interaction lifetime (1 hour)
refreshToken 604800 Refresh token lifetime (7 days)
session 86400 Session lifetime (24 hours)

You can use environment variables in your configuration file using ${VARIABLE_NAME} syntax. For example:

{
  "provider": {
    "iss": "https://${DOMAIN}:${PORT}"
  }
}

Custom Port Configuration

You can specify a custom port for the Nginx server by setting the PORT environment variable:

docker run -p 9000:9000 \
    -e PORT=9000 \
    oidc-mock:1.0.0

If no port is specified, the default port 8443 will be used.

HTTPS Configuration

The OIDC Mock Provider uses HTTPS by default. You can configure it in the following ways:

Using Self-Signed Certificates

By default, the server generates self-signed certificates for localhost. You can specify a custom domain:

docker run -p 8443:8443 \
    -e DOMAIN=my-domain.example.com \
    oidc-mock:1.0.0

Using Custom Certificates

You can provide your own certificates by mounting them to the container:

docker run -p 8443:8443 \
    -v /path/to/certificates:/custom-certs \
    oidc-mock:1.0.0

The certificate files must be named:

  • cert.pem - The SSL certificate
  • key.pem - The private key

Project Structure

  • /packages/backend: OIDC provider implementation
  • /packages/frontend: Quasar UI for login and consent screens
  • /bin: Helper scripts for building and running the application
  • /nginx.*.conf: Nginx configuration files for development and production

Attributions

This project uses the Twitter Emoji (Twemoji) for its favicon:

AI Assistance Disclaimer

This project was created with assistance from artificial intelligence tools, specifically GitHub Copilot. The AI tools helped with code generation, documentation, and project structure.

License

MIT