Informations de référence sur OpenID Connect

Demandes de jeton OIDC

Pour afficher toutes les revendications prises en charge par le fournisseur OIDC de GitHub, passez en revue les entrées claims_supported à l’adresse https://token.actions.githubusercontent.com/.well-known/openid-configuration.

Le jeton OIDC inclut les revendications suivantes.

Revendications standard d’audience, d’émetteur et d’objet

Revendication	Type de revendication	Description
aud	Public visé	Par défaut, il s’agit de l’URL du propriétaire du dépôt, par exemple l’organisation qui est propriétaire du dépôt. Vous pouvez définir une audience personnalisée avec une commande du kit de ressources : core.getIDToken(audience)
iss	Émetteur	Émetteur du jeton OIDC : https://token.actions.githubusercontent.com
sub	Objet	Définit la revendication d’objet qui doit être validée par le fournisseur de cloud. Ce paramètre est essentiel pour vous assurer que les jetons d’accès sont alloués uniquement de manière prévisible.

Paramètres d'en-tête et revendications standard JOSE supplémentaires

Paramètres d’en-tête	Type de paramètre	Description
alg	Algorithm	Algorithme utilisé par le fournisseur OIDC.
kid	Identificateur de clé	Clé unique du jeton OIDC.
typ	Type	Décrit le type de jeton. Il s’agit d’un jeton JSON Web Token (JWT).

Revendication	Type de revendication	Description
exp	Expire à	Identifie l’heure d’expiration du jeton JWT.
iat	Émis à	L’heure d’émission du jeton JWT.
jti	Identificateur de jeton JWT	Identificateur unique du jeton OIDC.
nbf	Pas avant	Le jeton JWT n’est pas valide pour une utilisation avant cette heure.

Des revendications personnalisées fournies par GitHub

Réclamation	Description
actor	Compte personnel qui a initié l’exécution du workflow.
actor_id	ID du compte personnel qui a lancé l’exécution du workflow.
base_ref	Branche cible de la demande de tirage (pull request) dans une exécution de workflow.
environment	Nom de l’environnement utilisé par le travail. Si la environment revendication est incluse (également via include_claim_keys), un environnement est requis et doit être fourni.
event_name	Nom de l’événement qui a déclenché l’exécution de workflow.
head_ref	Branche source de la demande de tirage (pull request) dans une exécution de workflow.
job_workflow_ref	Chemin de référence vers le workflow réutilisable (pour les travaux qui utilisent un workflow réutilisable). Pour plus d’informations, consultez « Using OpenID Connect with reusable workflows ».
job_workflow_sha	Pour les travaux utilisant un workflow réutilisable, SHA de commit pour le fichier de workflow réutilisable.
ref	(Référence) Référence git qui a déclenché l’exécution du workflow.
ref_type	Type de ref, par exemple : « branche ».
repository_visibility	Visibilité du dépôt dans lequel le workflow s’exécute. Accepte les valeurs suivantes : internal, private etpublic.
repository	Dépôt à partir duquel le workflow s’exécute.
repository_id	ID du dépôt à partir duquel le workflow s’exécute.
repository_owner	Nom de l’organisation dans laquelle repository est stocké.
repository_owner_id	ID de l’organisation dans laquelle repository est stocké.
run_id	ID de l’exécution de workflow qui a déclenché le workflow.
run_number	Nombre de fois que ce workflow a été exécuté.
run_attempt	Nombre de fois que cette exécution de workflow a été retentée.
runner_environment	Type d’exécuteur utilisé par le projet. Accepte les valeurs suivantes : github-hosted ou self-hosted.
workflow	Nom du workflow.
workflow_ref	Chemin de référence du workflow. Par exemple : octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch.
workflow_sha	SHA de commit pour le fichier de workflow.

Les revendications OIDC utilisées pour définir les conditions de confiance sur les rôles cloud

Les revendications d’audience et de sujet sont généralement utilisées conjointement, tout en définissant des conditions sur le rôle/les ressources cloud pour étendre son accès aux workflows GitHub.

• Audience : par défaut, cette valeur utilise l’URL du propriétaire du dépôt ou de l’organisation. Elle peut être utilisée pour définir une condition stipulant que seuls les workflows de l’organisation spécifique peuvent accéder au rôle cloud.
• Sujet : par défaut, possède un format prédéfini et constitue une concaténation de certaines des métadonnées clés concernant le workflow, telles que l’organisation, le dépôt, la branche ou l’environnement de job associé de GitHub. Consultez « Exemples de revendications de sujet » pour voir comment la revendication de sujet est assemblée à partir des métadonnées concaténées.

Si vous avez besoin de conditions de confiance plus granulaires, vous pouvez personnaliser le sujet (sub), revendiquer les qui est inclus avec le JWT. Pour plus d’informations, consultez « Personnalisation des revendications de jetons ».

Il existe également de nombreuses revendications supplémentaires prises en charge dans le jeton OIDC qui peuvent être utilisées pour définir ces conditions. De plus, votre fournisseur de cloud peut vous permettre d’attribuer un rôle aux jetons d’accès, ce qui vous permet de spécifier des autorisations encore plus précises.

Exemples de revendications de sujet

Les exemples suivants montrent comment utiliser le sujet comme condition et expliquent comment le sujet est rassemblé à partir des métadonnées concaténées. Le sujet utilise des informations issues du contexte job et indique à votre fournisseur de cloud que les demandes de jeton d’accès peuvent uniquement être accordées pour les demandes provenant des workflows s’exécutant dans des branches ou environnements spécifiques. Les sections suivantes décrivent certains sujets courants que vous pouvez utiliser.

Filtrage pour un environnement spécifique

La revendication de sujet inclut le nom de l’environnement lorsque le travail fait référence à un environnement.

Vous pouvez configurer un sujet qui filtre pour fournir un nom d’environnement spécifique. Dans cet exemple, l’exécution du workflow doit provenir d’un travail qui a un environnement nommé Production, dans un dépôt nommé octo-repo qui appartient à l’organisation octo-org:

• Syntaxe : repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
• Exemple : repo:octo-org/octo-repo:environment:Production

Filtrage pour fournir les événements pull_request

La revendication de sujet inclut la chaîne pull_request lorsque le workflow est déclenché par un événement de demande de tirage (pull request), mais uniquement si le travail ne fait pas référence à un environnement.

Vous pouvez configurer un sujet qui filtre pour fournir l’événement pull_request. Dans cet exemple, l’exécution du workflow doit avoir été déclenchée par un événement pull_request dans un dépôt nommé octo-repo appartenant à l’organisation octo-org :

• Syntaxe : repo:ORG-NAME/REPO-NAME:pull_request
• Exemple : repo:octo-org/octo-repo:pull_request

Filtrage pour fournir une branche spécifique

La revendication de sujet inclut le nom de branche du workflow, mais uniquement si le travail ne fait pas référence à un environnement et si le workflow n’est pas déclenché par un événement de demande de tirage.

Vous pouvez configurer un sujet qui filtre pour fournir un nom de branche spécifique. Dans cet exemple, l’exécution du workflow doit provenir d’une branche nommée demo-branch, dans un dépôt nommé octo-repo appartenant à l’organisation octo-org :

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

Filtrage pour fournir une étiquette spécifique

La revendication de sujet inclut le nom d’étiquette du workflow, mais uniquement si le travail ne fait pas référence à un environnement et si le workflow n’est pas déclenché par un événement de demande de tirage.

Vous pouvez créer un sujet qui filtre pour fournir une étiquette spécifique. Dans cet exemple, l’exécution du workflow doit provenir d’une étiquette nommée demo-tag, dans un dépôt nommé octo-repo appartenant à l’organisation octo-org :

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

Configuration du sujet dans votre fournisseur de cloud

Pour configurer le sujet dans la relation d’approbation de votre fournisseur de cloud, vous devez ajouter la chaîne de sujet à sa configuration d’approbation. Les exemples suivants montrent comment différents fournisseurs de cloud peuvent accepter le même sujet repo:octo-org/octo-repo:ref:refs/heads/demo-branch de différentes manières :

Fournisseur de cloud	Exemple
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"

Pour plus d’informations sur la configuration de fournisseurs de cloud spécifiques, consultez les guides répertoriés dans Renforcement de la sécurité de vos déploiements.

Personnalisation des revendications de jetons

Vous pouvez durcir la sécurité de votre configuration OIDC en personnalisant les revendications qui sont incluses dans le JWT. Ces personnalisations permettent de définir des conditions d’approbation plus précises pour vos rôles cloud quand vous autorisez vos workflows à accéder aux ressources hébergées dans le cloud :

• Vous pouvez personnaliser les valeurs pour les revendications audience. Consultez « Personnalisation de la valeur audience ».
• Vous pouvez personnaliser le format de votre configuration OIDC en définissant des conditions pour la revendication de l’objet (sub) qui exigent des jetons JWT provenant d’un référentiel spécifique, d’un workflow réutilisable ou d’une autre source.
• Vous pouvez définir des stratégies OIDC précises à l’aide de revendications de jeton OIDC supplémentaires, comme repository_id et repository_visibility. Consultez OpenID Connect.

Personnalisation de la valeur audience

Quand vous utilisez des actions personnalisées dans vos workflows, ces actions peuvent utiliser le kit de ressources GitHub Actions pour vous permettre de fournir une valeur personnalisée pour la revendication audience. Certains fournisseurs de cloud l’utilisent également dans leurs actions de connexion officielles pour appliquer une valeur par défaut pour la revendication audience. GitHub Action pour la connexion à Azure fournit par exemple la valeur par défaut aud pour api://AzureADTokenExchange , ou vous permet de définir une valeur personnalisée aud dans vos workflows. Pour plus d’informations sur le kit de ressources GitHub Actions, consultez la section jeton OIDC dans la documentation.

Si vous ne souhaitez pas utiliser la valeur par défaut aud d’une action, vous pouvez fournir une valeur personnalisée pour la revendication audience. Cela permet de définir une condition stipulant que seuls les workflows d’un référentiel ou d’une organisation spécifique peuvent accéder au rôle cloud. Si l’action que vous utilisez prend en charge cette fonction, vous pouvez utiliser le mot clé with dans votre workflow pour transmettre une valeur aud personnalisée à l’action. Pour plus d’informations, consultez « Référence syntaxique des métadonnées ».

Personnalisation des revendications d’objet pour une organisation ou un référentiel

Pour aider à améliorer la sécurité, la conformité et la normalisation, vous pouvez personnaliser les revendications standard en fonction des conditions d’accès exigées. Si votre fournisseur de cloud prend en charge l’application de conditions aux revendications d’objet, vous pouvez créer une condition qui vérifie si la valeur sub correspond au chemin du workflow réutilisable, par exemple "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main". Le format exact varie en fonction de la configuration OIDC de votre fournisseur de cloud. Pour configurer la condition de correspondance de GitHub, vous pouvez utiliser l’API REST pour exiger que la revendication sub comprenne toujours une revendication personnalisée spécifique, telle que job_workflow_ref. Vous pouvez utiliser l’API REST pour appliquer un modèle de personnalisation à la revendication d’objet OIDC ; par exemple, vous pouvez exiger que la revendication sub dans le jeton OIDC inclue toujours une revendication personnalisée spécifique, telle que job_workflow_ref. Pour plus d’informations, consultez « Points de terminaison REST pour OIDC GitHub Actions ».

La personnalisation des revendications applique un nouveau format pour l’intégralité de la revendication sub, qui remplace le format prédéfini sub par défaut dans le jeton décrit dans Exemples de revendications d’objet.

Les exemples de modèles suivants illustrent différentes façons de personnaliser la revendication d’objet. Pour configurer ces paramètres dans GitHub, les administrateurs utilisent l’API REST pour spécifier la liste des revendications qui doivent être incluses dans la revendication d’objet (sub).

Pour appliquer cette configuration, envoyez une requête au point de terminaison d’API et incluez la configuration nécessaire dans le corps de la demande. Pour les organisations, consultez Points de terminaison REST pour OIDC GitHub Actions, et pour les référentiels, consultez Points de terminaison REST pour OIDC GitHub Actions.

Pour personnaliser vos revendications d’objet, vous devez d’abord créer une condition correspondante dans la configuration OIDC de votre fournisseur de cloud, avant de personnaliser la configuration à l’aide de l’API REST. Une fois la configuration terminée, chaque fois qu’un nouveau travail s’exécute, le jeton OIDC généré pendant ce travail suit le nouveau modèle de personnalisation. Si la condition de correspondance n’existe pas dans la configuration OIDC du fournisseur de cloud avant l’exécution du travail, le jeton généré risque de ne pas être accepté par le fournisseur de cloud, car les conditions cloud peuvent ne pas être synchronisées.

Exemple : Autorisation d’un dépôt en fonction de la visibilité et du propriétaire

Cet exemple de modèle permet à la revendication sub d’avoir un nouveau format, en utilisant repository_owner et repository_visibility :

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

Dans la configuration OIDC de votre fournisseur de cloud, configurez la condition sub pour exiger que les revendications incluent des valeurs spécifiques pour repository_owner et repository_visibility. Par exemple : "sub": "repository_owner:monalisa:repository_visibility:private". Avec cette approche, vous pouvez restreindre l’accès des rôles cloud en leur permettant uniquement d’accéder aux dépôts privés d’une organisation ou d’une entreprise.

Exemple : Autorisation de l’accès à tous les dépôts d’un propriétaire donné

Cet exemple de modèle permet à la revendication sub d’avoir un nouveau format avec uniquement la valeur repository_owner.

Pour appliquer cette configuration, envoyez une requête au point de terminaison d’API et incluez la configuration nécessaire dans le corps de la demande. Pour les organisations, consultez Points de terminaison REST pour OIDC GitHub Actions, et pour les référentiels, consultez Points de terminaison REST pour OIDC GitHub Actions.

{
   "include_claim_keys": [
       "repository_owner"
   ]
}

Dans la configuration OIDC de votre fournisseur de cloud, configurez la condition sub pour exiger que les revendications incluent une valeur spécifique pour repository_owner. Par exemple : "sub": "repository_owner:monalisa"

Exemple : Exiger un workflow réutilisable

Cet exemple de modèle permet à la revendication sub d’avoir un nouveau format qui contient la valeur de la revendication job_workflow_ref. Cela permet à une entreprise d’utiliser des workflows réutilisables afin d’appliquer des déploiements cohérents dans l’ensemble de ses organisations et de ses dépôts.

Pour appliquer cette configuration, envoyez une requête au point de terminaison d’API et incluez la configuration nécessaire dans le corps de la demande. Pour les organisations, consultez Points de terminaison REST pour OIDC GitHub Actions, et pour les référentiels, consultez Points de terminaison REST pour OIDC GitHub Actions.

  {
     "include_claim_keys": [
         "job_workflow_ref"
     ]
  }

Dans la configuration OIDC de votre fournisseur de cloud, configurez la condition sub pour exiger que les revendications incluent une valeur spécifique pour job_workflow_ref. Par exemple : "sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main".

Exemple : Exiger un workflow réutilisable et d’autres revendications

L’exemple de modèle suivant combine l’exigence d’un workflow réutilisable spécifique avec des revendications supplémentaires.

Pour appliquer cette configuration, envoyez une requête au point de terminaison d’API et incluez la configuration nécessaire dans le corps de la demande. Pour les organisations, consultez Points de terminaison REST pour OIDC GitHub Actions, et pour les référentiels, consultez Points de terminaison REST pour OIDC GitHub Actions.

Cet exemple montre également comment utiliser "context" pour définir vos conditions. Il s’agit de la partie qui suit le dépôt au format par défautsub. Par exemple, lorsque le travail fait référence à un environnement, le contexte contient : environment:ENVIRONMENT-NAME.

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

Dans la configuration OIDC de votre fournisseur de cloud, configurez la condition sub pour exiger que les revendications incluent des valeurs spécifiques pour repo, context et job_workflow_ref.

Ce modèle de personnalisation nécessite que sub utilise le format suivant : repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH. Par exemple : "sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"

Exemple : Accorder l’accès à un dépôt spécifique

Cet exemple de modèle vous permet d’accorder l’accès cloud à tous les workflows d’un dépôt spécifique, dans toutes les branches/étiquettes et environnements.

Pour appliquer cette configuration, envoyez une requête au point de terminaison d’API et incluez la configuration nécessaire dans le corps de la demande. Pour les organisations, consultez Points de terminaison REST pour OIDC GitHub Actions, et pour les référentiels, consultez Points de terminaison REST pour OIDC GitHub Actions.

{
   "include_claim_keys": [
       "repo"
   ]
}

Dans la configuration OIDC de votre fournisseur de cloud, configurez la condition sub pour exiger une revendication repo qui corresponde à la valeur demandée.

Exemple : Utilisation de GUID générés par le système

Cet exemple de modèle autorise les revendications OIDC prévisibles avec des GUID générés par le système qui ne changent pas entre les renommages d’entités (par exemple, le renommage d’un dépôt).

Pour appliquer cette configuration, envoyez une requête au point de terminaison d’API et incluez la configuration nécessaire dans le corps de la demande. Pour les organisations, consultez Points de terminaison REST pour OIDC GitHub Actions, et pour les référentiels, consultez Points de terminaison REST pour OIDC GitHub Actions.

  {
     "include_claim_keys": [
         "repository_id"
     ]
  }

Dans la configuration OIDC de votre fournisseur de cloud, configurez la condition sub pour exiger une revendication repository_id qui corresponde à la valeur demandée.

ou :

{
   "include_claim_keys": [
       "repository_owner_id"
   ]
}

Dans la configuration OIDC de votre fournisseur de cloud, configurez la condition sub pour exiger une revendication repository_owner_id qui corresponde à la valeur demandée.

Exemple : valeur de contexte avec :

Cet exemple montre comment gérer la valeur de contexte avec :. Par exemple, lorsque le travail fait référence à un environnement nommé production:eastus.

Pour appliquer cette configuration, envoyez une requête au point de terminaison d’API et incluez la configuration nécessaire dans le corps de la demande. Pour les organisations, consultez Points de terminaison REST pour OIDC GitHub Actions, et pour les référentiels, consultez Points de terminaison REST pour OIDC GitHub Actions.

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

Dans la configuration OIDC de votre fournisseur de cloud, configurez la condition sub pour exiger que les revendications incluent une valeur spécifique pour environment et repository_owner. Par exemple : "sub": "environment:production%3Aeastus:repository_owner:octo-org".

Réinitialisation des personnalisations des modèles d’organisation

Cet exemple de modèle réinitialise le format des revendications d’objet vers celui par défaut. Ce modèle refuse toute stratégie de personnalisation appliquée au niveau de l’organisation.

Pour appliquer cette configuration, envoyez une requête au point de terminaison d’API et incluez la configuration nécessaire dans le corps de la demande. Pour les organisations, consultez Points de terminaison REST pour OIDC GitHub Actions, et pour les référentiels, consultez Points de terminaison REST pour OIDC GitHub Actions.

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

Dans la configuration OIDC de votre fournisseur de cloud, configurez la condition sub pour exiger que les revendications incluent des valeurs spécifiques pour repo et context.

Réinitialisation des personnalisations des modèles de référentiel

Tous les référentiels d'une organisation ont la possibilité d'accepter ou de refuser les modèles de demande sub personnalisés (au niveau de l'organisation et du référentiel).

Pour désactiver un référentiel et revenir au format de revendication sub par défaut, un administrateur de référentiel doit utiliser le point de terminaison de l’API REST sur « Points de terminaison REST pour OIDC GitHub Actions ».

Pour configurer les référentiels afin qu’ils utilisent le format de revendication par défaut sub, utilisez le point de terminaison d’API REST PUT /repos/{owner}/{repo}/actions/oidc/customization/sub indiqué avec le corps de la demande suivant.

{
   "use_default": true
}

Exemple : Configuration d’un référentiel pour utiliser un modèle d’organisation

Une fois qu'une organisation a créé un modèle de réclamation sub personnalisé, l'API REST peut être utilisée pour appliquer par programme le modèle aux référentiels au sein de l'organisation. Un administrateur de référentiel peut configurer son référentiel pour utiliser le modèle créé par l’administrateur de son organisation.

Pour configurer le référentiel afin qu’il utilise le modèle de l’organisation, un administrateur de référentiel doit utiliser le point de terminaison de l’API REST PUT /repos/{owner}/{repo}/actions/oidc/customization/sub avec le corps de la demande suivant. Pour plus d’informations, consultez « Points de terminaison REST pour OIDC GitHub Actions ».

{
   "use_default": false
}

Débogage de vos revendications OIDC

Vous pouvez utiliser l’action github/actions-oidc-debugger pour visualiser les revendications qui seraient envoyées, avant d’intégrer un fournisseur de cloud. Cette action demande un JWT et imprime les revendications incluses dans le JWT qui ont été reçues de GitHub Actions.

Autorisations de flux de travail pour le jeton OIDC demandeur

Autorisation requise

• Le travail ou le flux de travail doit accorder l'autorisation permettant id-token: write au fournisseur OIDC de GitHub de créer un jeton Web JSON (JWT) :

  permissions:
    id-token: write
  

• Sans id-token: write, le jeton d’ID JWT OIDC ne peut pas être demandé. Ce paramètre active uniquement l’extraction et la définition du jeton OIDC ; elle n’accorde pas l’accès en écriture à d’autres ressources.

Définition des autorisations

• Pour extraire un jeton OIDC pour un workflow, définissez l’autorisation au niveau du workflow :

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

• Pour récupérer un jeton OIDC pour un seul travail, définissez l’autorisation dans ce travail :

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

• Des autorisations supplémentaires peuvent être requises en fonction des besoins du flux de travail.

Workflows réutilisables

• Pour les workflows réutilisables appartenant au même utilisateur, à la même organisation ou à la même entreprise que l’appelant, le jeton OIDC généré dans le workflow réutilisable est accessible à partir du contexte de l’appelant.
• Pour les flux de travail réutilisables en dehors de votre entreprise ou organisation, définissez le paramètre permissions pour id-token sur write explicitement au niveau du flux de travail ou de l’appelant. Cela garantit que le jeton OIDC est disponible uniquement pour les flux de travail de l’appelant prévus.

Méthodes pour demander le jeton OIDC

Les actions personnalisées peuvent demander le jeton OIDC à l’aide des éléments suivants :

• La méthode getIDToken() de la boîte à outils Actions. Pour plus d’informations, consultez Jeton OIDC dans la documentation sur les packages npm.

• Les variables d'environnement suivantes sur l’exécuteur.

  Variable	Description
  ACTIONS_ID_TOKEN_REQUEST_URL	URL du fournisseur OIDC de GitHub.
  ACTIONS_ID_TOKEN_REQUEST_TOKEN	Jeton du porteur pour la demande auprès du fournisseur OIDC.

  Par exemple :

  Shell

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