Remarque : Les exécuteurs hébergés sur GitHub ne sont pas pris en charge sur GitHub Enterprise Server. Vous pouvez voir plus d’informations sur le support futur planifié dans la GitHub public roadmap.
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 :
- 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.
- 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.
- 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.
- 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://HOSTNAME/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://HOSTNAME/_services/token",
"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://HOSTNAME/_services/token/.well-known/openid-configuration
.
Le jeton inclut les 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://HOSTNAME/_services/token |
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. |
Le jeton OIDC comprend également des paramètres d'en-tête et des 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. |
Le jeton inclut également des revendications personnalisées fournies par GitHub.
Revendication | 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. |
enterprise | Nom de l’entreprise qui contient le référentiel à partir duquel le workflow s’exécute. |
enterprise_id | L’ID de l’entreprise qui contient le référentiel à partir duquel le flux de travail est exécuté. |
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 « Utilisation d’OpenID Connect avec des workflows réutilisables ». |
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. |
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 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.
Remarque : Pour contrôler la façon dont votre fournisseur de cloud émet des jetons d’accès, vous devez définir au moins une condition, afin que les dépôts non approuvés ne puissent pas demander de jetons d’accès pour vos ressources cloud.
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 | "HOSTNAME/_services/token: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, 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.
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 :
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
etACTIONS_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
audience
. Consultez « Personnalisation de la valeuraudience
». - 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
etrepository_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 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 ».
Remarque : lorsque le modèle d’organisation est appliqué, il n’affecte pas les flux de travail qui utilisent déjà OIDC, sauf si leur référentiel a choisi d’utiliser des modèles d’organisation personnalisés. Pour tous les référentiels, existants et nouveaux, le propriétaire du référentiel doit utiliser l’API REST au niveau du référentiel pour choisir de recevoir cette configuration en définissant use_default
sur false
. Le propriétaire du référentiel peut également utiliser l’API REST pour appliquer une autre configuration spécifique au référentiel. 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 ».
Remarque : la revendication sub
utilise le format raccourci repo
(par exemple, repo:ORG-NAME/REPO-NAME
) au lieu de repository
pour référencer le référentiel.
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 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.
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 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 :
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.