# Dex OIDC Provider

> Federated OpenID Connect provider.

- Category: Security & Networking
- Difficulty: intermediate
- Components: dex
- Tags: dex, oidc, oauth, federation
- Source: https://docker.recipes/security/dex

## 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.

## 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

## Use cases

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

## docker-compose.yml

```yaml
services:
  dex:
    image: ghcr.io/dexidp/dex:latest
    container_name: dex
    restart: unless-stopped
    command: dex serve /etc/dex/config.yaml
    volumes:
      - ./dex-config.yaml:/etc/dex/config.yaml:ro
      - dex_data:/data
    ports:
      - "5556:5556"
      - "5557:5557"

volumes:
  dex_data:
```

## .env

```bash
# Create dex-config.yaml with connectors
# See dexidp.io/docs for configuration
```

## Usage notes

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

## 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

