Simular servicios OAuth en pruebas con Dex

Dex es un proveedor de identidad de código abierto compatible con OpenID Connect (OIDC) y OAuth 2.0 que se puede configurar para autenticar contra varios proveedores de identidad backend, como LDAP, SAML y OAuth. Ejecutar Dex en un contenedor Docker te deja simular un servidor OAuth 2.0 para pruebas y desarrollo. Esta guía te muestra cómo configurar Dex como un servidor de simulacro (mock) de OAuth utilizando contenedores Docker.

Hoy en día, OAuth es la opción preferida para autenticarse en servicios web; la gran mayoría de ellos ofrece la posibilidad de acceder utilizando servicios OAuth populares como GitHub, Google o Apple. El uso de OAuth garantiza un mayor nivel de seguridad y simplificación, ya que no es necesario crear nuevos perfiles para cada servicio. Esto significa que, al dejar que las aplicaciones accedan a los recursos en nombre de los usuarios sin compartir contraseñas, OAuth minimiza el riesgo de exposición de credenciales.

En esta guía, aprenderás a:

• Utilizar Docker para iniciar un contenedor de Dex.
• Utilizar un simulacro de OAuth en GitHub Actions (GHA) sin depender de un proveedor de OAuth externo.

Uso de Dex con Docker

La imagen oficial de Docker para Dex proporciona una forma conveniente de desplegar y gestionar instancias de Dex. Dex está disponible para varias arquitecturas de CPU, incluyendo amd64, armv7 y arm64, lo que garantiza la compatibilidad con diferentes dispositivos y plataformas. Puedes obtener más información sobre Dex independiente en el sitio de documentación de Dex.

Requisitos previos

Docker Compose: Recomendado para gestionar aplicaciones Docker de múltiples contenedores.

Configuración de Dex con Docker

Comienza creando un directorio para tu proyecto de Dex:

mkdir dex-mock-server
cd dex-mock-server

Organiza tu proyecto con la siguiente estructura:

dex-mock-server/
├── config.yaml
└── compose.yaml

Crea el archivo de configuración de Dex: El archivo config.yaml define la configuración de Dex, incluyendo conectores, clientes y almacenamiento. Para configurar un servidor de simulacro, puedes utilizar la siguiente configuración mínima:

# config.yaml
issuer: http://localhost:5556/dex
storage:
  type: memory
web:
  http: 0.0.0.0:5556
staticClients:
  - id: example-app
    redirectURIs:
      - 'http://localhost:5555/callback'
    name: 'Example App'
    secret: ZXhhbXBsZS1hcHAtc2VjcmV0
enablePasswordDB: true
staticPasswords:
  - email: "[email protected]"
    hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
    username: "admin"
    userID: "1234"

Explicación:

• issuer: La URL pública de Dex.

• storage: Uso de almacenamiento en memoria por simplicidad.

• web: Dex escuchará en el puerto 5556.

• staticClients: Define una aplicación cliente (example-app) con su URI de redirección y secreto.

• enablePasswordDB: Habilita la autenticación por contraseña estática.

• staticPasswords: Define un usuario estático para la autenticación. El hash es un hash bcrypt de la contraseña.

Note

Asegúrate de que el hash sea un hash bcrypt válido de la contraseña que desees. Puedes generarlo utilizando herramientas como bcrypt-generator.com. O utiliza herramientas de CLI como htpasswd como en el siguiente ejemplo: echo password | htpasswd -BinC 10 admin | cut -d: -f2

Con Docker Compose configurado, inicia Dex:

# compose.yaml

services:
  dex:
    image: dexidp/dex:latest
    container_name: dex
    ports:
      - "5556:5556"
    volumes:
      - ./config.yaml:/etc/dex/config.yaml
    command: ["dex", "serve", "/etc/dex/config.yaml"]

Ahora puedes ejecutar el contenedor utilizando el comando docker compose.

docker compose up -d

Este comando descargará la imagen de Docker de Dex (si no está disponible) e iniciará el contenedor en modo detached (segundo plano).

Para verificar que Dex se está ejecutando, comprueba los registros (logs) para asegurarte de que se inició correctamente:

docker compose logs -f dex

Deberías ver una salida que indique que Dex está escuchando en el puerto especificado.

Uso de Dex para pruebas de OAuth en GHA

Para probar el flujo de OAuth, necesitarás una aplicación cliente configurada para autenticarse contra Dex. Uno de los casos de uso más típicos es utilizarlo dentro de GitHub Actions. Dado que Dex admite autenticación simulada (mock), puedes predefinir usuarios de prueba como se sugiere en la documentación. El archivo config.yaml debería verse así:

issuer: http://127.0.0.1:5556/dex

storage:
  type: memory

web:
  http: 0.0.0.0:5556

oauth2:
  skipApprovalScreen: true

staticClients:
  - name: TestClient
    id: client_test_id
    secret: client_test_secret
    redirectURIs:
      - http://{ip-your-app}/path/to/callback/ # ejemplo: http://localhost:5555/callback

connectors:
# El conector mockCallback siempre devuelve el usuario '[email protected]'.
- type: mockCallback
  id: mock
  name: Mock

Ahora puedes insertar el servicio Dex dentro de tu archivo .github/workflows/ci.yaml:

[...]
jobs:
  test-oauth:
    runs-on: ubuntu-latest
    steps:
      - name: Install Dex
        run: |
          curl -L https://github.com/dexidp/dex/releases/download/v2.37.0/dex_linux_amd64 -o dex
          chmod +x dex

      - name: Start Dex Server
        run: |
          nohup ./dex serve config.yaml > dex.log 2>&1 &
          sleep 5  # Dar tiempo a Dex para iniciarse
[...]

Conclusión

Al seguir esta guía, has configurado Dex como un servidor de simulacro de OAuth utilizando Docker. Esta configuración es invaluable para las pruebas y el desarrollo, ya que te deja simular flujos de OAuth sin depender de proveedores de identidad externos. Para configuraciones e integraciones más avanzadas, consulta la documentación de Dex.