Dex OIDC Provider

intermediate

Federated OpenID Connect provider.

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

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

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

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

Usage Notes

1Docs: https://dexidp.io/docs/
2OIDC discovery at http://localhost:5556/.well-known/openid-configuration
3gRPC API on port 5557 for programmatic client management
4Configure connectors in dex-config.yaml (LDAP, GitHub, SAML, etc.)
5Lightweight IdP - ideal for Kubernetes authentication
6Static 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 notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

dex

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download