Referencia de OpenID Connect

Notificaciones de token de OIDC

Para ver todas las reclamaciones admitidas por el proveedor de OIDC de GitHub, revisa las entradas claims_supported en https://token.actions.githubusercontent.com/.well-known/openid-configuration.

El token OIDC incluye las siguientes notificaciones.

Las notificaciones de público estándar, emisor y asunto

Notificación	Tipo de notificación	Descripción
aud	Público	De manera predeterminada, es la URL del propietario del repositorio, por ejemplo, la organización propietaria del repositorio. Puede establecer un público personalizado con un comando del kit de herramientas: core.getIDToken(audience)
iss	Emisor	El emisor del token de OIDC: https://token.actions.githubusercontent.com
sub	Asunto	Define la notificación de asunto que debe validar el proveedor de nube. Este ajuste es esencial para asegurarse de que los tokens de acceso solo se asignan de forma predecible.

Parámetros de encabezado JOSE y notificaciones estándar adicionales

Parámetro de encabezado	Tipo de parámetro	Descripción
alg	Algoritmo	El algoritmo que utiliza el proveedor de OIDC.
kid	Identificador de clave	Clave única para el token de OIDC.
typ	Tipo	Describe el tipo del token. Este es un Token Web de JSON (JWT).

Notificación	Tipo de notificación	Descripción
exp	Expira a las	Identifica la hora de expiración del JWT.
iat	Emitido a las	La hora a la que se generó el token JWT.
jti	Identificador de token JWT	Identificador único del token OIDC.
nbf	No antes de	El JTW no es válido para utilizarse antes de esta hora.

Notificaciones personalizadas proporcionadas por GitHub

Reclamar	Descripción
actor	La cuenta personal que ha iniciado la ejecución del flujo de trabajo.
actor_id	El Id. de la cuenta personal que ha iniciado la ejecución del flujo de trabajo.
base_ref	La rama destino de la solicitud de cambios en una ejecución de flujo de trabajo.
environment	El nombre del ambiente que utiliza el job. Si se incluye la notificación environment (también a través de include_claim_keys), se requiere un entorno y se debe proporcionar.
event_name	El nombre del evento que activó la ejecución del flujo de trabajo.
head_ref	La rama fuente de la solicitud de cambios en una ejecución de flujo de trabajo.
job_workflow_ref	Para los trabajos que usan un flujo de trabajo reutilizable, la ruta de acceso de referencia al flujo de trabajo reutilizable. Para más información, consulta Utilizar OpenID Connect con flujos de trabajo reutilizables.
job_workflow_sha	En el caso de los trabajos que usan un flujo de trabajo reutilizable, el SHA de confirmación para el archivo de flujo de trabajo reutilizable.
ref	(Referencia) La referencia de Git que ha desencadenado la ejecución del flujo de trabajo.
ref_type	Tipo de ref, por ejemplo: "rama".
repository_visibility	La visibilidad del repositorio donde se está ejecutando el flujo de trabajo. Acepta uno de los siguientes valores: internal, private o public.
repository	El repositorio desde donde se está ejecutando el flujo de trabajo.
repository_id	El Id. del repositorio desde donde se está ejecutando el flujo de trabajo.
repository_owner	Nombre de la organización en la que se almacena repository.
repository_owner_id	El Id. de la organización en la que está almacenado repository.
run_id	La ID de la ejecución de flujo de trabajo que lo activó.
run_number	La cantidad de veces que se ha ejecutado este flujo de trabajo.
run_attempt	La cantidad de veces que esta ejecución de flujo de trabajo se ha retirado.
runner_environment	El tipo de ejecutor usado por el trabajo. Acepta los siguientes valores: github-hosted o self-hosted.
workflow	El nombre del flujo de trabajo.
workflow_ref	La ruta de acceso de referencia al flujo de trabajo. Por ejemplo, octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch.
workflow_sha	El SHA de confirmación para el archivo de flujo de trabajo.

Notificaciones de OIDC usadas para definir condiciones de confianza en los roles de la nube

Las notificaciones de asunto y público habitualmente se utilizan combinadas mientras se configuran las condiciones en el rol o recursos de la nube para dar el alcance a su acceso a los flujos de trabajo de GitHub.

• Público: de manera predeterminada, este valor utiliza la URL del propietario de la organización o el repositorio. Esta puede utilizarse para configurar una condición en la que solo los flujos de trabajo de una organización específica puedan acceder al rol en la nube.
• Asunto: de forma predeterminada, tiene un formato predefinido y es una concatenación de algunos de los metadatos clave del flujo de trabajo, como la organización de GitHub, el repositorio, la rama o el entorno job asociado. Consulta Notificaciones de asunto de ejemplo para ver cómo se crea la notificación del asunto a partir de metadatos concatenados.

Si necesita condiciones de confianza más granulares, puede personalizar el sujeto (sub) de la notificación que se incluye con el JWT. Para obtener más información, consulta Personalización de las notificaciones de token.

También hay muchas notificaciones adicionales compatibles en el token de OIDC que pueden utilizarse para configurar estas condiciones. Adicionalmente, tu proveedor de servicios en la nube podría permitirte asignar un rol a los tokens de acceso, lo cual te permite especificar permisos aún más granulares.

Ejemplos de notificación de asunto

Los siguientes ejemplos demuestran cómo utilizar el "Asunto" como una condición y explican como este se ensambla desde los metadatos concatenados. El asunto usa información del contexto job e indica al proveedor de nube que las solicitudes de token de acceso solo se pueden conceder para solicitudes de flujos de trabajo que se ejecutan en ramas y entornos específicos. Las siguientes secciones describen algunos temas comunes que puedes utilizar.

Filtrar por un ambiente específico

La notificación de asunto incluye el nombre de ambiente cuando el job hace referencia a uno de ellos.

Puede configurar un asunto que filtre por un nombre de entorno específico. En este ejemplo, la ejecución del flujo de trabajo debe haberse originado en un trabajo con un entorno denominado Production, en un repositorio denominado octo-repo que sea propiedad de la organización octo-org:

• Sintaxis: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
• Ejemplo: repo:octo-org/octo-repo:environment:Production

Filtrado de eventos pull_request

La solicitud de asunto incluye la cadena pull_request cuando el flujo de trabajo se desencadena mediante un evento de solicitud de incorporación de cambios, pero solo si el trabajo no hace referencia a un entorno.

Puede configurar un asunto que filtre por el evento pull_request. En este ejemplo, la ejecución del flujo de trabajo debe haberse desencadenado mediante un evento pull_request en un repositorio denominado octo-repo que pertenece a la organización octo-org:

• Sintaxis: repo:ORG-NAME/REPO-NAME:pull_request
• Ejemplo: repo:octo-org/octo-repo:pull_request

Filtrar por una rama específica

La reivindicación del asunto incluye el nombre de rama del flujo de trabajo, pero solo si el job no hace referencia a un ambiente y el flujo de trabajo no se activa con un evento de solicitud de cambios.

Puedes configurar un asunto que filtre por un nombre de rama específica. En este ejemplo, la ejecución del flujo de trabajo debe haberse desencadenado desde una rama denominada demo-branch, en un repositorio denominado octo-repo que pertenece a la organización octo-org:

• Sintaxis: repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME
• Ejemplo: repo:octo-org/octo-repo:ref:refs/heads/demo-branch

Filtrar por una etiqueta específica

La reivindicación del asunto incluye el nombre de etiqueta del flujo de trabajo, pero únicamente si el job no hace referencia a un ambiente y el flujo de trabajo no se activa con un evento de solicitud de cambios.

Puedes crear un asunte que filtre por una etiqueta específica. En este ejemplo, la ejecución del flujo de trabajo debe haberse desencadenado con una etiqueta denominada demo-tag, en un repositorio denominado octo-repo que pertenece a la organización octo-org:

• Sintaxis: repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME
• Ejemplo: repo:octo-org/octo-repo:ref:refs/tags/demo-tag

Configurar el asunto en tu proveedor de servicios en la red

Para configurar el asunto en la relación de confianza de tu proveedor de servicios en la nube, debes agregar la secuencia del asunto a su configuración de confianza. En los ejemplos siguientes se muestra cómo varios proveedores de nube pueden aceptar el mismo asunto repo:octo-org/octo-repo:ref:refs/heads/demo-branch de maneras diferentes:

Proveedor de nube	Ejemplo
Amazon Web Services	"token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch"
Azure	repo:octo-org/octo-repo:ref:refs/heads/demo-branch
Google Cloud Platform	(assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch')
HashiCorp Vault	bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"

Para más información sobre cómo configurar proveedores de nube específicos, consulta las guías que aparecen en Fortalecer la seguridad de tus despliegues.

Personalización de las notificaciones de token

Puedes mejorar la seguridad de la configuración de OIDC mediante la personalización de las notificaciones que se incluyen con el JWT. Estas personalizaciones te permiten definir condiciones de confianza más pormenorizadas en los roles de nube al permitir que tus flujos de trabajo accedan a los recursos hospedados en la nube:

• Puedes personalizar los valores de las notificaciones audience. Consulta Personalización del valor audience.
• Puedes personalizar el formato de la configuración de OIDC mediante el establecimiento de condiciones en la notificación de asunto (sub) que requieren que los tokens JWT se originen en un repositorio específico, un flujo de trabajo reutilizable u otro origen.
• Puedes definir directivas OIDC pormenorizadas mediante notificaciones de token de OIDC adicionales, como repository_id y repository_visibility. Consulta OpenID Connect.

Personalización del valor audience

Al usar acciones personalizadas en los flujos de trabajo, esas acciones pueden utilizar el kit de herramientas de GitHub Actions para permitirte proporcionar un valor personalizado para la notificación audience. Algunos proveedores de nube también lo usan en sus acciones de inicio de sesión oficiales para aplicar un valor predeterminado a la notificación audience. Por ejemplo, la acción de GitHub para el inicio de sesión de Azure proporciona un valor aud predeterminado de api://AzureADTokenExchange, o bien permite establecer un valor aud personalizado en los flujos de trabajo. Para más información sobre el kit de herramientas de GitHub Actions, consulta la sección Token de OIDC en la documentación.

Si no quieres usar el valor aud predeterminado ofrecido por una acción, puedes proporcionar un valor personalizado para la notificación audience. Esto te permite establecer una condición en la que solo los flujos de trabajo de un repositorio u organización específicos puedan acceder al rol en la nube. Si la acción que usas admite esto, puedes utilizar la palabra clave with en el flujo de trabajo para pasar un valor aud personalizado a la acción. Para más información, consulta Referencia de sintaxis de metadatos.

Personalización de las notificaciones de asunto para una organización o repositorio

Para ayudar a mejorar la seguridad, el cumplimiento y la estandarización de toda la organización, puedes personalizar las notificaciones estándar para que se adapten a las condiciones de acceso necesarias. Si tu proveedor de nube admite condiciones en las notificaciones de asunto, puedes crear una condición que compruebe si el valor sub coincide con la ruta de acceso del flujo de trabajo reutilizable, como "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main". El formato exacto variará en función de la configuración de OIDC de tu proveedor de nube. Para configurar la condición de coincidencia en GitHub, puedes usar la API de REST para exigir que la notificación sub incluya siempre una notificación personalizada específica, como job_workflow_ref. Puedes usar la API de REST para aplicar una plantilla de personalización para la notificación del sujeto de OIDC; por ejemplo, puedes requerir que la notificación sub dentro del token de OIDC siempre incluya una notificación personalizada específica, como job_workflow_ref. Para más información, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC.

La personalización de las notificaciones da como resultado un nuevo formato para toda la notificación sub, que sustituye al formato predefinido predeterminado sub en el token que se describe en Ejemplos de notificaciones de asunto.

En las plantillas de ejemplo siguientes se muestran varias maneras de personalizar la notificación de asunto. Para configurar estas opciones en GitHub, los administradores usan la API REST para especificar una lista de notificaciones que se deben incluir en la notificación de asunto (sub).

Para aplicar esta configuración, envía una solicitud al punto de conexión de la API e incluye la configuración necesaria en el cuerpo de la solicitud. Para las organizaciones, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC, y para los repositorios, Puntos de conexión de API REST para Acciones de GitHub OIDC.

Para personalizar las notificaciones de asunto, debes crear una condición coincidente en la configuración de OIDC de tu proveedor de nube antes de personalizar la configuración mediante la API de REST. Una vez completada la configuración, cada vez que se ejecute un nuevo trabajo, el token de OIDC generado durante ese trabajo seguirá la nueva plantilla de personalización. Si la condición de coincidencia no existe en la configuración de OIDC del proveedor de nube antes de que se ejecute el trabajo, es posible que el proveedor de nube no acepte el token generado, ya que las condiciones de nube podrían no estar sincronizadas.

Ejemplo: Permitir el repositorio en función de la visibilidad y el propietario

Esta plantilla de ejemplo permite que la notificación sub tenga un nuevo formato, mediante repository_owner y repository_visibility:

{
   "include_claim_keys": [
       "repository_owner",
       "repository_visibility"
   ]
}

En la configuración de OIDC de tu proveedor de nube, configura la condición sub para exigir que las notificaciones incluyan valores específicos para repository_owner y repository_visibility. Por ejemplo: "sub": "repository_owner:monalisa:repository_visibility:private". El enfoque permite restringir el acceso de rol en la nube sólo a repositorios privados dentro de una organización o empresa.

Ejemplo: Permitir el acceso a todos los repositorios con un propietario específico

Esta plantilla de ejemplo permite que la notificación sub tenga un nuevo formato con el valor de repository_owner únicamente.

Para aplicar esta configuración, envía una solicitud al punto de conexión de la API e incluye la configuración necesaria en el cuerpo de la solicitud. Para las organizaciones, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC, y para los repositorios, Puntos de conexión de API REST para Acciones de GitHub OIDC.

{
   "include_claim_keys": [
       "repository_owner"
   ]
}

En la configuración de OIDC de tu proveedor de nube, configura la condición sub para exigir que las notificaciones incluyan valores específicos para repository_owner. Por ejemplo: "sub": "repository_owner:monalisa"

Ejemplo: Requerir un flujo de trabajo reutilizable

Esta plantilla de ejemplo permite que la notificación sub tenga un nuevo formato que contenga el valor de la notificación job_workflow_ref. Esto permite a una empresa usar flujos de trabajo reutilizables para aplicar implementaciones coherentes en sus organizaciones y repositorios.

Para aplicar esta configuración, envía una solicitud al punto de conexión de la API e incluye la configuración necesaria en el cuerpo de la solicitud. Para las organizaciones, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC, y para los repositorios, Puntos de conexión de API REST para Acciones de GitHub OIDC.

  {
     "include_claim_keys": [
         "job_workflow_ref"
     ]
  }

En la configuración de OIDC de tu proveedor de nube, configura la condición sub para exigir que las notificaciones incluyan valores específicos para job_workflow_ref. Por ejemplo: "sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main".

Ejemplo: Requerir un flujo de trabajo reutilizable y otras notificaciones

En la plantilla de ejemplo siguiente se combina el requisito de un flujo de trabajo reutilizable específico con notificaciones adicionales.

Para aplicar esta configuración, envía una solicitud al punto de conexión de la API e incluye la configuración necesaria en el cuerpo de la solicitud. Para las organizaciones, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC, y para los repositorios, Puntos de conexión de API REST para Acciones de GitHub OIDC.

En este ejemplo también se muestra cómo usar "context" para definir tus condiciones. Esta es la parte que sigue al repositorio en el formato sub predeterminado. Por ejemplo, cuando el trabajo hace referencia a un entorno, el contexto contiene: environment:ENVIRONMENT-NAME.

{
   "include_claim_keys": [
       "repo",
       "context",
       "job_workflow_ref"
   ]
}

En la configuración de OIDC de tu proveedor de nube, configura la condición sub para exigir que las notificaciones incluyan valores específicos para repo, context y job_workflow_ref.

Esta plantilla de personalización requiere que sub use el siguiente formato: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH. Por ejemplo: "sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"

Ejemplo: Conceder acceso a un repositorio específico

Esta plantilla de ejemplo te permite conceder acceso a la nube a todos los flujos de trabajo de un repositorio específico, en todas las ramas o etiquetas y todos los entornos.

Para aplicar esta configuración, envía una solicitud al punto de conexión de la API e incluye la configuración necesaria en el cuerpo de la solicitud. Para las organizaciones, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC, y para los repositorios, Puntos de conexión de API REST para Acciones de GitHub OIDC.

{
   "include_claim_keys": [
       "repo"
   ]
}

En la configuración de OIDC de tu proveedor de nube, configura la condición sub para exigir una notificación repo que coincida con el valor necesario.

Ejemplo: Usar GUID generados por el sistema

En esta plantilla de ejemplo se habilitan notificaciones OIDC predecibles con GUID generados por el sistema que no cambian al modificar el nombre de las entidades (por ejemplo, al modificar el nombre de un repositorio).

Para aplicar esta configuración, envía una solicitud al punto de conexión de la API e incluye la configuración necesaria en el cuerpo de la solicitud. Para las organizaciones, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC, y para los repositorios, Puntos de conexión de API REST para Acciones de GitHub OIDC.

  {
     "include_claim_keys": [
         "repository_id"
     ]
  }

En la configuración de OIDC de tu proveedor de nube, configura la condición sub para exigir una notificación repository_id que coincida con el valor necesario.

O bien

{
   "include_claim_keys": [
       "repository_owner_id"
   ]
}

En la configuración de OIDC de tu proveedor de nube, configura la condición sub para exigir una notificación repository_owner_id que coincida con el valor necesario.

Ejemplo: Valor de contexto con :

En este ejemplo se muestra cómo controlar el valor de contexto con :. Por ejemplo, cuando el trabajo hace referencia a un entorno denominado production:eastus.

Para aplicar esta configuración, envía una solicitud al punto de conexión de la API e incluye la configuración necesaria en el cuerpo de la solicitud. Para las organizaciones, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC, y para los repositorios, Puntos de conexión de API REST para Acciones de GitHub OIDC.

{
   "include_claim_keys": [
       "environment",
       "repository_owner"
   ]
}

En la configuración de OIDC de tu proveedor de servicios en la nube, configura la condición sub para requerir que las notificaciones incluyan un valor específico para environment y repository_owner. Por ejemplo: "sub": "environment:production%3Aeastus:repository_owner:octo-org".

Restablecimiento de personalizaciones de plantillas de organización

En esta plantilla de ejemplo se restablecen las notificaciones de asunto al formato predeterminado. Esta plantilla rechaza eficazmente cualquier directiva de personalización de nivel de organización.

Para aplicar esta configuración, envía una solicitud al punto de conexión de la API e incluye la configuración necesaria en el cuerpo de la solicitud. Para las organizaciones, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC, y para los repositorios, Puntos de conexión de API REST para Acciones de GitHub OIDC.

{
   "include_claim_keys": [
       "repo",
       "context"
   ]
}

En la configuración de OIDC de tu proveedor de nube, configura la condición sub para exigir que las notificaciones incluyan valores específicos para repo y context.

Restablecimiento de personalizaciones de plantillas de repositorio

Todos los repositorios de una organización tienen la capacidad de elegir usar o no plantillas de notificación sub personalizadas de nivel del repositorio y la organización.

Para rechazar un repositorio y restablecerlo al formato de notificación predeterminado sub, un administrador del repositorio debe usar el punto de conexión de la API sw REST en Puntos de conexión de API REST para Acciones de GitHub OIDC.

Para configurar los repositorios para que utilicen el formato de reclamación sub predeterminado, utiliza el punto de conexión de la API REST PUT /repos/{owner}/{repo}/actions/oidc/customization/sub con el siguiente cuerpo de solicitud.

{
   "use_default": true
}

Ejemplo: Configuración de un repositorio para usar una plantilla de organización

Una vez que la organización ha creado una plantilla de notificación sub personalizada, se puede usar la API REST para aplicar mediante programación la plantilla a los repositorios de la organización. El administrador del repositorio puede configurar su repositorio para que use la plantilla creada por el administrador de su organización.

Para configurar el repositorio para que use la plantilla de la organización, el administrador del repositorio debe usar el punto de conexión de la API REST PUT /repos/{owner}/{repo}/actions/oidc/customization/sub con el siguiente cuerpo de solicitud. Para más información, consulta Puntos de conexión de API REST para Acciones de GitHub OIDC.

{
   "use_default": false
}

Depuración de las notificaciones de OIDC

Puede usar la acción github/actions-oidc-debugger para visualizar las notificaciones que se enviarían antes de realizar la integración con un proveedor de servicios en la nube. Esta acción solicita un JWT e imprime las notificaciones incluidas en el JWT que se recibieron de GitHub Actions.

Permisos de flujo de trabajo para solicitar el token de OIDC

Permiso necesario

• El trabajo o el flujo de trabajo deben conceder el permiso id-token: write para permitir el proveedor de OIDC de GitHub crear una instancia de JSON Web Token (JWT):

  permissions:
    id-token: write
  

• Sin id-token: write, no se puede solicitar el token de id. de JWT de OIDC. Este valor solo permite capturar y establecer el token de OIDC; no concede acceso de escritura a otros recursos.

Establecer permisos

• A fin de capturar un token de OIDC para un flujo de trabajo, establece el permiso en el nivel de flujo de trabajo:

  permissions:
    id-token: write # This is required for requesting the JWT
    contents: read # This is required for actions/checkout
  

• A fin de capturar un token de OIDC para un único trabajo, establece el permiso dentro de ese trabajo:

  permissions:
    id-token: write # This is required for requesting the JWT
  

• Es posible que se necesiten permisos adicionales en función de las necesidades del flujo de trabajo.

Flujos de trabajo reutilizables

• Para flujos de trabajo reutilizables que son propiedad del mismo usuario, organización o empresa que el autor de la llamada, se puede acceder al token de OIDC generado en el flujo de trabajo reutilizable desde el contexto del autor de la llamada.
• Para flujos de trabajo reutilizables fuera de la empresa u organización, establece el valor permissions para id-token en write explícitamente en el nivel de flujo de trabajo del autor de la llamada o del trabajo. Esto garantiza que el token de OIDC solo esté disponible para los flujos de trabajo del autor de la llamada previstos.

Métodos para solicitar el token de OIDC

Las acciones personalizadas pueden solicitar el token de OIDC mediante lo siguiente:

• El método getIDToken() del kit de herramientas de Actions. Para más información, consulta Token de OIDC en la documentación del paquete npm.

• Las variables de entorno siguientes en el ejecutor.

  Variable	Descripción
  ACTIONS_ID_TOKEN_REQUEST_URL	La URL del proveedor de OIDC de GitHub.
  ACTIONS_ID_TOKEN_REQUEST_TOKEN	Token portador de la solicitud al proveedor de OIDC.

  Por ejemplo:

  Shell

  curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"