$docker.recipes

Dex OIDC Provider

intermediate

Federated OpenID Connect provider.

[i]Overview

Dex is a lightweight, production-ready OpenID Connect (OIDC) identity provider originally developed by CoreOS and now maintained by the Linux Foundation. It acts as a federation layer that connects your applications to existing identity providers like LDAP, GitHub, Google, SAML providers, or other OIDC providers, eliminating the need to build custom authentication integrations. Dex implements the OIDC specification with OAuth 2.0 extensions, providing JWT tokens that applications can verify without callback dependencies. This Docker stack deploys a complete Dex instance with persistent storage and exposes both the web interface for authentication flows and the gRPC API for programmatic client management. The configuration allows Dex to serve as a bridge between your applications and upstream identity sources, standardizing authentication across heterogeneous environments while maintaining security isolation. Organizations adopting cloud-native architectures particularly benefit from Dex because it integrates natively with Kubernetes RBAC, enabling centralized authentication for kubectl access, dashboard logins, and service-to-service communication without vendor lock-in to specific cloud providers.

[*]Key Features

  • [+]Multiple connector support for LDAP, Active Directory, GitHub, Google, SAML, and other OIDC providers in a single instance
  • [+]Kubernetes-native authentication with built-in support for kubectl credential plugins and RBAC integration
  • [+]gRPC API on port 5557 for dynamic client registration and management without configuration file changes
  • [+]JWT token signing with configurable key rotation and multiple signing algorithms (RS256, ES256, PS256)
  • [+]Connector-agnostic group mapping that translates upstream identity provider groups to OIDC claims
  • [+]PKCE (Proof Key for Code Exchange) support for secure public client authentication flows
  • [+]Custom theme support for white-labeling authentication pages with organization branding
  • [+]Offline token refresh capabilities for long-lived application access without user re-authentication

[#]Common Use Cases

  • [1]Kubernetes cluster authentication where developers and operators need unified access across multiple clusters
  • [2]Multi-tenant SaaS applications requiring integration with customer LDAP directories and cloud identity providers
  • [3]Development teams consolidating authentication across internal tools like GitLab, Grafana, and custom applications
  • [4]Organizations migrating from proprietary identity solutions to open standards-based authentication
  • [5]Hybrid cloud deployments needing consistent identity federation across on-premises and cloud resources
  • [6]Startups building applications that must integrate with enterprise customer identity systems
  • [7]CI/CD pipeline authentication where build systems need programmatic access to multiple services with centralized identity

[!]Prerequisites

  • [!]Domain name with SSL certificate for production deployments (Dex requires HTTPS for security)
  • [!]At least 256MB RAM allocated to the container for handling authentication flows and token generation
  • [!]Network access to upstream identity providers (LDAP servers, cloud APIs) on required ports
  • [!]Understanding of OIDC/OAuth 2.0 flows and JWT token validation for application integration
  • [!]Prepared dex-config.yaml file with at least one configured connector and static client definition
  • [!]Ports 5556 and 5557 available on the host system for web interface and gRPC API respectively
[!]

WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

[$]docker-compose.yml

[docker-compose.yml]
1services: 
2  dex: 
3    image: ghcr.io/dexidp/dex:latest
4    container_name: dex
5    restart: unless-stopped
6    command: dex serve /etc/dex/config.yaml
7    volumes: 
8      - ./dex-config.yaml:/etc/dex/config.yaml:ro
9      - dex_data:/data
10    ports: 
11      - "5556:5556"
12      - "5557:5557"
13
14volumes: 
15  dex_data:

[$].env Template

[.env]
1# Create dex-config.yaml with connectors
2# See dexidp.io/docs for configuration

[i]Usage Notes

  1. [1]Docs: https://dexidp.io/docs/
  2. [2]OIDC discovery at http://localhost:5556/.well-known/openid-configuration
  3. [3]gRPC API on port 5557 for programmatic client management
  4. [4]Configure connectors in dex-config.yaml (LDAP, GitHub, SAML, etc.)
  5. [5]Lightweight IdP - ideal for Kubernetes authentication
  6. [6]Static clients defined in config, or use gRPC API for dynamic

[>]Quick Start

[terminal]
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  dex:
5    image: ghcr.io/dexidp/dex:latest
6    container_name: dex
7    restart: unless-stopped
8    command: dex serve /etc/dex/config.yaml
9    volumes:
10      - ./dex-config.yaml:/etc/dex/config.yaml:ro
11      - dex_data:/data
12    ports:
13      - "5556:5556"
14      - "5557:5557"
15
16volumes:
17  dex_data:
18EOF
19
20# 2. Create the .env file
21cat > .env << 'EOF'
22# Create dex-config.yaml with connectors
23# See dexidp.io/docs for configuration
24EOF
25
26# 3. Start the services
27docker compose up -d
28
29# 4. View logs
30docker compose logs -f

[>]One-Liner

Run this command to download and set up the recipe in one step:

[terminal]
1curl -fsSL https://docker.recipes/api/recipes/dex/run | bash

[?]Troubleshooting

  • [!]Error 'failed to initialize storage': Ensure the dex_data volume has correct permissions and the container can write to /data directory
  • [!]OIDC discovery endpoint returns 404: Verify dex-config.yaml is properly mounted and contains valid YAML syntax with required issuer field
  • [!]Connector authentication fails: Check network connectivity to upstream providers and verify credentials in connector configuration
  • [!]JWT signature verification errors: Ensure client applications are fetching current signing keys from http://localhost:5556/keys endpoint
  • [!]gRPC API connection refused on port 5557: Confirm grpc configuration section exists in dex-config.yaml and reflection is enabled if needed
  • [!]Memory usage continuously growing: Enable token garbage collection in config and set appropriate token expiration times for your use case

Community Notes

Loading...
Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

## Components

dex

## Tags

#dex#oidc#oauth#federation

## Category

Security & Networking

## Related