À propos du renforcement de la sécurité avec OpenID Connect

Vue d’ensemble d’OpenID Connect

Les workflows GitHub Actions sont souvent conçus pour accéder à un fournisseur de cloud (tel qu’AWS, Azure, GCP ou HashiCorp Vault) afin de déployer des logiciels ou d’utiliser les services du cloud. Avant que le workflow puisse accéder à ces ressources, il fournit des informations d’identification, telles qu’un mot de passe ou un jeton, au fournisseur de cloud. Ces informations d’identification sont généralement stockées en tant que secret dans GitHub, et le workflow présente ce secret au fournisseur de cloud chaque fois qu’il s’exécute.

Toutefois, l’utilisation de secrets codés en dur vous oblige à créer des informations d’identification dans le fournisseur de cloud, puis à les dupliquer dans GitHub en tant que secret.

Avec OpenID Connect (OIDC), vous pouvez adopter une approche différente en configurant votre workflow pour demander un jeton d’accès à court terme directement à partir du fournisseur de cloud. Votre fournisseur de cloud doit également prendre en charge OIDC de son côté et vous devez configurer une relation d’approbation qui contrôle les workflows qui peuvent demander les jetons d’accès. Les fournisseurs qui prennent actuellement en charge OIDC incluent Amazon Web Services, Azure, Google Cloud Platform et HashiCorp Vault, entre autres.

Avantages de l’utilisation d’OIDC

En mettant à jour vos workflows pour utiliser les jetons OIDC, vous pouvez adopter les bonnes pratiques de sécurité suivantes :

• Aucun secret cloud : vous n’aurez pas besoin de dupliquer vos informations d’identification cloud en tant que secrets GitHub à long terme. Au lieu de cela, vous pouvez configurer l’approbation OIDC sur votre fournisseur de cloud, puis mettre à jour vos workflows pour demander un jeton d’accès à court terme à partir du fournisseur de cloud via OIDC.
• Gestion de l’authentification et de l’autorisation : vous avez un contrôle plus précis sur la façon dont les workflows peuvent utiliser les informations d’identification, à l’aide des outils d’authentification (authN) et d’autorisation (authZ) de votre fournisseur de cloud pour contrôler l’accès aux ressources cloud.
• Rotation des informations d’identification : avec OIDC, votre fournisseur de cloud émet un jeton d’accès à court terme qui n’est valide que pour un seul travail, puis expire automatiquement.

Bien démarrer avec OICD

Le diagramme suivant fournit une vue d’ensemble de la façon dont le fournisseur OIDC de GitHub s’intègre à vos workflows et à votre fournisseur de cloud :

1. Dans votre fournisseur de cloud, créez une approbation OIDC entre votre rôle cloud et votre ou vos workflows GitHub qui ont besoin d’accéder au cloud.
2. Chaque fois que votre travail s’exécute, le fournisseur OIDC de GitHub génère automatiquement un jeton OIDC. Ce jeton contient plusieurs revendications pour établir une identité vérifiable à la sécurité renforcée sur le workflow spécifique qui tente de s’authentifier.
3. Vous pouvez inclure une étape ou une action dans votre travail pour demander ce jeton à partir du fournisseur OIDC de GitHub, et le présenter au fournisseur de cloud.
4. Une fois que le fournisseur de cloud valide correctement les revendications présentées dans le jeton, il fournit ensuite un jeton d’accès cloud à court terme qui est disponible uniquement pour la durée du travail.

Configuration de l’approbation OIDC avec le cloud

Lorsque vous configurez votre cloud pour approuver le fournisseur OIDC de GitHub, vous devez ajouter des conditions qui filtrent les demandes entrantes, afin que les dépôts ou workflows non approuvés ne puissent pas demander de jetons d’accès pour vos ressources cloud :

• Avant d’accorder un jeton d’accès, votre fournisseur de cloud vérifie que l’subject et les autres revendications utilisées pour définir des conditions dans ses paramètres d’approbation correspondent à celles du jeton JSON Web Token (JWT) de la demande. Par conséquent, vous devez prendre soin de définir correctement le sujet et les autres conditions dans votre fournisseur de cloud.
• Les étapes de configuration de l’approbation OIDC et la syntaxe permettant de définir les conditions pour les rôles cloud (à l’aide de la revendication de sujet et d’autres revendications) varient selon le fournisseur de cloud que vous utilisez. Pour obtenir des exemples, consultez « Exemples de revendications de sujet ».

Présentation du jeton OIDC

Chaque travail demande un jeton OIDC à partir du fournisseur OIDC de GitHub, qui répond avec un jeton JSON Web Token (JWT) généré automatiquement, unique pour chaque travail de workflow où il est généré. Lorsque le travail s’exécute, le jeton OIDC est présenté au fournisseur de cloud. Pour valider le jeton, le fournisseur de cloud vérifie si la revendication de sujet et les autres revendications du jeton OIDC correspondent aux conditions préconfigurées dans la définition d’approbation OIDC du rôle cloud.

L’exemple de jeton OIDC suivant utilise un sujet (sub) qui référence un environnement de travail nommé prod dans le dépôt octo-org/octo-repo.

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "environment": "prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_visibility": "private",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "runner_environment": "github-hosted"
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "enterprise": "avocado-corp",
  "enterprise_id": "2",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

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 inclut les revendications standard d’audience, d’émetteur et d’objet.

Le jeton OIDC comprend également des paramètres d'en-tête et des revendications standard JOSE supplémentaires.

Le jeton inclut également des revendications personnalisées fournies par GitHub.

Définition de conditions d’approbation sur des rôles cloud à l’aide de revendications OIDC

Avec OIDC, un workflow GitHub Actions nécessite un jeton pour accéder aux ressources dans votre fournisseur de cloud. Le workflow demande un jeton d’accès à partir de votre fournisseur de cloud, qui vérifie les détails présentés par le jeton JWT. Si la configuration d’approbation dans le jeton JWT est une correspondance, votre fournisseur de cloud répond en émettant un jeton temporaire au workflow, qui peut ensuite être utilisé pour accéder aux ressources dans votre fournisseur de cloud. Vous pouvez configurer votre fournisseur de cloud computing pour qu’il ne réponde qu’aux demandes émanant du référentiel d’une organisation spécifique. Vous pouvez également spécifier des conditions supplémentaires, décrites ci-dessous.

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 l’émetteur (iss) et le sujet (sub), revendiquer les qui sont 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 :

Pour plus d’informations, consultez les guides répertoriés dans « Activation d’OpenID Connect pour votre fournisseur de cloud ».

Mise à jour de vos actions pour OIDC

Pour mettre à jour vos actions personnalisées afin de vous authentifier à l’aide d’OIDC, vous pouvez utiliser getIDToken() à partir du kit de ressources Actions pour demander un jeton JWT à partir du fournisseur OIDC de GitHub. Pour plus d’informations, consultez « Jeton OIDC » dans la documentation sur les packages npm.

Vous pouvez également utiliser une commande curl pour demander le jeton JWT, à l’aide des variables d’environnement suivantes.

Par exemple :

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

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

Ajout de paramètres d’autorisations

L’exécution du projet ou du flux de travail nécessite un paramètre permissions avec id-token: write pour autoriser le fournisseur OIDC de GitHub à créer un JSON Web Token pour chaque exécution. Vous ne pourrez pas demander le jeton OIDC JWT ID si le permissions pour id-token n’est pas défini sur write, mais cette valeur n’implique pas l’octroi d’un accès en écriture à des ressources, permettant uniquement de récupérer et de définir le jeton OIDC pour une action ou une étape afin de permettre l’authentification avec un jeton d’accès à courte durée. Tout paramètre d’approbation réel est défini à l’aide de revendications OIDC, pour plus d’informations, consultez « À propos du renforcement de la sécurité avec OpenID Connect ».

Le paramètre id-token: write permet au JWT d’être demandé à partir du fournisseur OIDC de GitHub à l’aide de l’une des approches suivantes :

• Utilisation de variables d’environnement sur l’exécuteur (ACTIONS_ID_TOKEN_REQUEST_URL et ACTIONS_ID_TOKEN_REQUEST_TOKEN).
• Utilisation du getIDToken() issu du kit de ressources Actions.

Si vous devez extraire un jeton OIDC pour un workflow, l’autorisation peut être définie au niveau du workflow. Par exemple :

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

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

Si vous avez uniquement besoin d’extraire un jeton OIDC pour un seul travail, alors cette autorisation peut être définie au sein de ce travail. Par exemple :

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

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

Vous aurez peut-être besoin de spécifier des autorisations supplémentaires ici, en fonction des exigences liées à votre workflow.

Pour les workflows réutilisables appartenant au même utilisateur, à la même organisation ou à la même entreprise que le workflow de l’appelant, le jeton OIDC généré dans le workflow réutilisable est accessible à partir du contexte de l’appelant. Pour les workflows réutilisables en dehors de votre entreprise ou organisation, le paramètre permissions pour id-token doit être défini explicitement avec la valeur write au niveau du workflow de l’appelant ou dans le travail spécifique qui appelle le workflow réutilisable. Cela garantit que le jeton OIDC généré dans le workflow réutilisable n’est autorisé à être consommé dans les workflows de l’appelant que si c’est prévu.

Pour plus d’informations, consultez « Réutilisation des workflows ».

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 issuer ou audience. Consultez « Personnalisation de la valeur issuer pour une entreprise » et « 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 « Présentation du jeton OIDC ».

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 « Metadata syntax for GitHub Actions ».

Personnalisation de la valeur issuer pour une entreprise

Par défaut, le jeton JWT est émis par le fournisseur OIDC de GitHub sur https://token.actions.githubusercontent.com. Ce chemin est présenté à votre fournisseur de cloud à l’aide de la valeur iss du jeton JWT.

Pour renforcer la sécurité de leur configuration OIDC, les administrateurs d’entreprise peuvent configurer leur entreprise afin de recevoir des jetons à partir d’une URL unique à l’adresse https://token.actions.githubusercontent.com/<enterpriseSlug>, en remplaçant <enterpriseSlug> par la valeur slug de l’entreprise.

Cette configuration signifie que votre entreprise recevra le jeton OIDC provenant d’une URL unique. Vous pourrez ensuite configurer votre fournisseur de cloud pour qu’il accepte uniquement les jetons provenant de cette URL. Cela garantit que seuls les dépôts de l’entreprise pourront accéder à vos ressources cloud à l’aide d’OIDC.

Pour activer ce paramètre pour l’entreprise, l’administrateur d’entreprise doit utiliser le point de terminaison /enterprises/{enterprise}/actions/oidc/customization/issuer et spécifier "include_enterprise_slug": true dans le corps de la demande. Pour plus d’informations, consultez « Points de terminaison REST pour OIDC GitHub Actions ».

Une fois ce paramètre appliqué, le jeton JWT contient la valeur iss mise à jour. Dans l’exemple suivant, la clé iss utilise octocat-inc comme valeur enterpriseSlug :

{
  "jti": "6f4762ed-0758-4ccb-808d-ee3af5d723a8",
  "sub": "repo:octocat-inc/private-server:ref:refs/heads/main",
  "aud": "http://octocat-inc.example/octocat-inc",
  "enterprise": "octocat-inc",
  "enterprise_id": "123",
  "iss": "https://token.actions.githubusercontent.com/octocat-inc",
  "bf": 1755350653,
  "exp": 1755351553,
  "iat": 1755351253
}

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 « À propos du renforcement de la sécurité avec OpenID Connect ».

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 sub par défaut. 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 améliorer davantage la sécurité, vous pouvez combiner ce modèle avec une URL d’émetteur unique pour votre entreprise, comme décrit dans « Personnalisation de la valeur issuer pour une entreprise ».

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
}

Mise à jour de vos workflows pour OIDC

Vous pouvez maintenant mettre à jour vos workflows YAML pour utiliser des jetons d’accès OIDC à la place de secrets. Les fournisseurs de cloud populaires ont publié leurs actions de connexion officielles qui vous permettront de bien démarrer avec OIDC. Pour plus d’informations sur la mise à jour de vos workflows, consultez les guides spécifiques au cloud répertoriés ci-dessous dans « Activation d’OpenID Connect pour votre fournisseur de cloud ».

Activation de OpenID Connect pour la publication de package Python

Vous pouvez utiliser un flux de travail GitHub Actions dans un référentiel en tant qu’éditeur approuvé pour un projet PyPI. L’utilisation d’un flux de travail en tant qu’éditeur approuvé permet aux jetons d’accès OIDC d’être échangés pour des jetons d’API PyPI temporaires. Pour plus d’informations, consultez « Configuration d’OpenID Connect dans PyPl » et « Publication sur PyPI avec un éditeur approuvé » dans la documentation PyPI.

Activation d’OpenID Connect pour votre fournisseur de cloud

Pour activer et configurer OIDC pour votre fournisseur de cloud spécifique, consultez les guides suivants :

• « Configuration d’OpenID Connect dans Amazon Web Services »
• « Configuration d’OpenID Connect dans Azure »
• « Configuration d’OpenID Connect dans Google Cloud Platform »
• « Configuration d’OpenID Connect dans HashiCorp Vault »

Pour activer et configurer OIDC pour un autre fournisseur de cloud, consultez le guide suivant :

• « Configuration d’OpenID Connect dans les fournisseurs de cloud »

Suivi de ces guides sur GHE.com

Si vous faites partie d’une entreprise qui utilise GitHub Enterprise Cloud avec résidence des données et que vous configurez OIDC sur GHE.com, vous devez remplacer certaines valeurs dans les articles liés.

• La revendication attendue de votre fournisseur doit remplacer githubusercontent.com par SUBDOMAIN.ghe.com, où SUBDOMAIN est le sous-domaine de votre entreprise sur GHE.com.
• Pour toutes les URL qui incluent un itinéraire avec le nom ou le slug de votre entreprise, vous devez remplacer le sous-domaine de votre entreprise sur GHE.com.

Par exemple, si votre sous-domaine est octocorp, les substitutions suivantes s’appliquent :

• L’URL permettant de voir toutes les revendications prises en charge par le fournisseur OIDC de GitHub serait https://token.actions.octocorp.ghe.com/.well-known/openid-configuration.
• La valeur de iss dans votre jeton OIDC serait https://token.actions.octocorp.ghe.com.
• L’entreprise peut recevoir des jetons à https://token.actions.octocorp.ghe.com/octocorp, et le point de terminaison d’’API REST pour personnaliser la valeur issuer serait /enterprises/octocorp/actions/oidc/customization/issuer.

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.