docs: add Microsoft Entra ID integration for GitHub Actions#28858
Open
afzal442 wants to merge 3 commits into
Open
docs: add Microsoft Entra ID integration for GitHub Actions#28858afzal442 wants to merge 3 commits into
afzal442 wants to merge 3 commits into
Conversation
❗ Preview Environment deployment failed on BunnyshellSee: Environment Details | Pipeline Logs Available commands (reply to this comment):
|
PR Summary by QodoDocument GitHub Actions OIDC federation via Microsoft Entra ID
AI Description
Diagram
High-Level Assessment
Files changed (1)
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends Argo CD’s operator documentation for GitHub Actions authentication by adding an alternative path that federates GitHub OIDC tokens into Microsoft Entra ID (Workload Identity Federation) and then uses the resulting Entra-issued token against Argo CD configured with oidc.config.
Changes:
- Adds a new “Using Microsoft Entra ID” section describing prerequisites and
argocd-cmoidc.configsetup. - Provides a full GitHub Actions workflow example that performs GitHub OIDC → Entra token exchange and uses the Argo CD CLI.
- Documents RBAC differences for Entra-based auth vs. Dex-based repo/ref subjects.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+277
to
+281
| When authenticating through **Microsoft Entra ID**, the subject differs. Tokens | ||
| obtained via the `client_credentials` grant identify the workload App | ||
| Registration itself, not a repository, so the subject is the **object ID of the | ||
| service principal** (`sub`/`oid` claim) rather than a `repo:org/repo:ref` | ||
| subject. Bind your role to that ID instead: |
Code Review by Qodo
|
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
docs/operator-manual/user-management/github-actions.md:157
- The example
oidc.configuseshttps://sts.windows.net/{tenant-id}/as the issuer, but Argo CD uses OIDC discovery (/.well-known/openid-configuration). Entra ID discovery works withhttps://login.microsoftonline.com/{tenant-id}/v2.0, which is also whatmicrosoft.mddocuments. As written, the example is likely to fail discovery/token validation.
issuer: https://sts.windows.net/{tenant-id}/
Comment on lines
8
to
+11
| You need to use OAuth 2.0 Token Exchange. Some identity providers supports this | ||
| out of the box such as Dex. | ||
| out of the box such as Dex. Alternatively, you can federate the GitHub OIDC | ||
| token directly into Microsoft Entra ID and have Argo CD trust Entra via | ||
| `oidc.config`. |
afzal442
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
Comments suppressed due to low confidence (1)
docs/operator-manual/user-management/github-actions.md:157
- The
oidc.configexample setsissuertohttps://sts.windows.net/{tenant-id}/, but the NOTE immediately below (anddocs/operator-manual/user-management/microsoft.md:75) indicates Entra ID OIDC discovery should usehttps://login.microsoftonline.com/{tenant-id}/v2.0. As written, this example is internally inconsistent and will likely break OIDC discovery.
issuer: https://sts.windows.net/{tenant-id}/
Comment on lines
+132
to
+134
| This assumes Argo CD is already configured to trust Entra ID directly via | ||
| `oidc.config` as described in | ||
| [Microsoft Entra ID App Registration Auth using OIDC](microsoft.md#entra-id-app-registration-auth-using-oidc). |
| You need to use OAuth 2.0 Token Exchange. Some identity providers supports this | ||
| out of the box such as Dex. | ||
| out of the box such as Dex. Alternatively, you can federate the GitHub OIDC | ||
| token directly into Microsoft Entra ID and have Argo CD trust Entra via |
This change adds comprehensive documentation for integrating GitHub Actions with Argo CD using Microsoft Entra ID. It outlines the process of federating GitHub OIDC tokens directly into Microsoft Entra ID, eliminating the need for Dex and enabling Argo CD to trust Entra ID via `oidc.config`. The documentation includes: - Prerequisites for setting up Entra ID and GitHub App Registrations. - Configuration steps for `argocd-cm` to trust Entra ID. - A detailed example of a GitHub Action workflow that authenticates using this method. - Guidance on configuring RBAC policies in Argo CD for this new authentication method, noting the difference in subject identification (service principal object ID vs. repository ref). Signed-off-by: afzal442 <afzal442@gmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (4)
docs/operator-manual/user-management/github-actions.md:11
- Grammar issue and inconsistent terminology: “providers supports” should be “providers support”, and “trust Entra” should be “trust Entra ID” for clarity.
You need to use OAuth 2.0 Token Exchange. Some identity providers supports this
out of the box such as Dex. Alternatively, you can federate the GitHub OIDC
token directly into Microsoft Entra ID and have Argo CD trust Entra via
`oidc.config`.
docs/operator-manual/user-management/github-actions.md:182
- The workflow example sets a top-level
permissions:block but only grantsid-token: write. Whenpermissionsis specified, unspecified permissions becomenone, which can breakactions/checkout/git fetch(needscontents: read, especially for private repos).
permissions:
id-token: write # This is required for requesting the JWT
docs/operator-manual/user-management/github-actions.md:168
- The NOTE asserts a specific issuer format, but the repo’s Entra OIDC doc (
docs/operator-manual/user-management/microsoft.md) useshttps://login.microsoftonline.com/{tenant}/v2.0for interactive login. Please clarify that the issuer here must match the actual tokenissfor this flow, so readers don’t apply the wrong issuer value.
> Tokens minted via the `client_credentials` grant are v1.0 access tokens
> issued by `https://sts.windows.net/{tenant-id}/`. Make sure the `issuer` in
> `oidc.config` matches (not the `login.microsoftonline.com/{tenant}/v2.0`
> form), and that the token's `aud` claim — the Argo CD App Registration client
> ID — is listed in `allowedAudiences`.
docs/operator-manual/user-management/github-actions.md:281
- This section implies Argo CD may use the Entra token’s
oidclaim as the subject. Argo CD’s RBAC subject matching uses the token’ssub(seeutil/jwt/jwt.go:GetUserIdentifier), so mentioningoidhere can lead to RBAC rules that never match.
When authenticating through **Microsoft Entra ID**, the subject differs. Tokens
obtained via the `client_credentials` grant identify the workload App
Registration itself, not a repository, so the subject is the **object ID of the
service principal** (`sub`/`oid` claim) rather than a `repo:org/repo:ref`
subject. Bind your role to that ID instead:
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This change adds comprehensive documentation for integrating GitHub Actions with Argo CD using Microsoft Entra ID.
It outlines the process of federating GitHub OIDC tokens directly into Microsoft Entra ID, eliminating the need for Dex and enabling Argo CD to trust Entra ID via
oidc.config. The documentation includes:argocd-cmto trust Entra ID.Checklist: