Configuración de OpenID Connect en Docker

Overview

OpenID Connect (OIDC) permite que GitHub Actionssus flujos de trabajo se autentiquen con Docker para acceder a Docker Hub y Docker Build Cloud sin almacenar contraseñas de Docker, personal access tokenssecretos o tokens de acceso de la organización (OAT) en GitHub.

En lugar de administrar credenciales de larga duración, configure una relación de confianza entre su GitHub organización y su organización de Docker. Cuando se ejecuta un flujo de trabajo, GitHub emite un token de OIDC de corta duración que Docker valida con los conjuntos de reglas configurados y, a continuación, emite un token de acceso con ámbito para el flujo de trabajo.

En esta guía se proporciona información general sobre cómo configurar Docker para confiar en el OIDC de GitHub como identidad federada y se muestra cómo usar esta configuración en un flujo de trabajo de GitHub Actions.

Para más información, consulte Conexiones OIDC en la documentación de Docker.

Prerequisites

• Para obtener información sobre los conceptos básicos sobre cómo GitHub usa OpenID Connect (OIDC) y su arquitectura y ventajas, consulte OpenID Connect.

• Antes de proceder, debes planear tu estrategia de seguridad para garantizar que los tokens de acceso solo se asignen de forma predecible. Para controlar la forma en que el proveedor de servicios en la nube emite tokens de acceso, tendrá que definir al menos una condición, para que los repositorios no confiables no puedan solicitar tokens de acceso para los recursos en la nube. Para obtener más información, vea Referencia de OpenID Connect.

• Los tokens OIDC solicitados para trabajos de actualización Dependabot tienen una declaración event_name de dynamic. Si la directiva de confianza tiene por objeto autorizar únicamente los flujos de trabajo GitHub Actions y su proveedor de servicios en la nube admite condiciones en event_name, permita únicamente los nombres de evento previstos por sus flujos de trabajo. Para obtener más información, vea Referencia de OpenID Connect.

• Su organización de Docker debe usar Docker Business, Docker Team o Docker Hardened Images, o inscribirse en el programa de código abierto patrocinado por Docker.

• Debe ser propietario o editor de su organización de Docker.

• Debe planear qué repositorios, ramas y flujos de trabajo necesitan acceso a Docker y configurar conjuntos de reglas en consecuencia.

Añadir el proveedor de identidad a Docker

Para usar OIDC con Docker, establezca una relación de confianza entre GitHub Actions y Docker mediante la creación de una conexión OIDC. Para más información sobre este proceso, consulte Creación y administración de conexiones OIDC en la documentación de Docker.

1. Inicie sesión en Docker Home y vaya a su organización.
2. Vaya a Identidad y autenticación**** > .
3. Seleccione Crear conexión OIDC.
4. Configure al menos un conjunto de reglas para definir qué GitHub repositorios, ramas o flujos de trabajo pueden autenticarse. Cada conjunto de reglas especifica:
   • Reglas: condiciones coincidentes con claims del token OIDC (repositorio, rama, ruta de flujo de trabajo). Se admiten patrones comodín como repo:my-org/*.
   • Recursos: repositorios de Docker Hub o proyectos de Docker Build Cloud a los que puede acceder el flujo de trabajo.
   • Ámbitos: niveles de permiso (read, write).
5. Guarde la conexión y copie el identificador de conexión para usarlo en el flujo de trabajo.

Actualizando tu GitHub Actions flujo de trabajo

Una vez que haya creado una conexión OIDC en Docker, actualice el flujo de trabajo para autenticarse mediante la acción docker/login-action.

En el ejemplo siguiente se usa el marcador de posición YOUR-CONNECTION-ID para el identificador de conexión que copió de Docker y el marcador de posición YOUR-DOCKER-ORG para el nombre de su organización de Docker.

# Este flujo de trabajo usa acciones que no GitHub no certifica.
# Estas las proporcionan entidades terceras y las gobiernan
# condiciones de servicio, políticas de privacidad y documentación de soporte
# en línea.
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Sign in to Docker Hub with OIDC
        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
        with:
          username: YOUR-DOCKER-ORG
        env:
          DOCKERHUB_OIDC_CONNECTIONID: YOUR-CONNECTION-ID

      - name: Build and push
        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
        with:
          push: true
          tags: YOUR-DOCKER-ORG/my-image:latest

Configuración clave del flujo de trabajo

• permissions.id-token: write es necesario para que GitHub pueda emitir un token OIDC para el flujo de trabajo.
• docker/login-action gestiona el intercambio de tokens de OIDC y el inicio de sesión de Docker en un solo paso cuando DOCKERHUB_OIDC_CONNECTIONID se establece y password se omite.
• El username campo debe ser el nombre de la organización de Docker.

Coincidencia de la reclamación del sujeto

Docker evalúa la sub declaración del GitHub token de OIDC con los conjuntos de reglas que configuró. El formato predeterminado de la declaración de asunto es:

repo:<owner>/<repo>:ref:refs/heads/<branch>

Los distintos desencadenadores de flujo de trabajo producen declaraciones del sujeto diferentes. Por ejemplo:

Trigger	Formato de la declaración del asunto
push de rama	repo:my-org/my-repo:ref:refs/heads/main
Solicitud de incorporación de cambios	repo:my-org/my-repo:pull_request
Etiqueta	repo:my-org/my-repo:ref:refs/tags/v1.0
Medio ambiente	repo:my-org/my-repo:environment:production

Puede usar patrones comodín en los conjuntos de reglas para que coincidan con varios repositorios o ramas. En el caso de los claims de asunto heredados, repo:my-org/* coincide con todos los repositorios de la organización. Para las claims de asunto inmutables, use repo:my-org@OWNER-ID/*; si la organización contiene repositorios con ambos formatos, configure ambos patrones.

Para más información, consulte Conjuntos de reglas y claims del asunto en la documentación de Docker.