From b92e113ae320ccf8d7134d29e68502716e626d41 Mon Sep 17 00:00:00 2001 From: isra-fel <11371776+isra-fel@users.noreply.github.com> Date: Tue, 17 Nov 2026 13:51:52 +1100 Subject: [PATCH 1/2] docs: explain immutable OIDC subject claims setup Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 28d4d3bc-8553-4068-8689-4d0d39ac2d4c --- README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 18890ba58..a74e8f25e 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ - [`max-context-population`](#max-context-population) - [Workflow Examples](#workflow-examples) - [Login With OpenID Connect (OIDC) \[Recommended\]](#login-with-openid-connect-oidc-recommended) + - [Immutable subject claims](#immutable-subject-claims) - [Login With a Service Principal Secret](#login-with-a-service-principal-secret) - [Login With System-assigned Managed Identity](#login-with-system-assigned-managed-identity) - [Login With User-assigned Managed Identity](#login-with-user-assigned-managed-identity) @@ -392,6 +393,17 @@ jobs: Get-AzContext ``` +#### Immutable subject claims + +GitHub's immutable OIDC subject (`sub`) format appends the numeric owner and repository IDs to their names, helping prevent another repository from gaining access if those names are reused. For example, `repo:octo-org/octo-repo:ref:refs/heads/main` becomes `repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main`. + +Both sides must use the same subject format: + +1. **Azure:** Create a federated identity credential on your app registration or user-assigned managed identity with the immutable subject, including the correct owner/repository IDs and branch, tag, or environment. Keep the existing credential during migration. +2. **GitHub:** Enable immutable subject claims in the repository or organization OIDC settings (UI or REST API). Repositories created, renamed, or transferred after July 15, 2026 use this format automatically; other existing repositories must opt in. This feature is not available on GitHub Enterprise Server. + +Run the workflow to verify login succeeds, then remove the old name-based credential. No additional Azure Login Action input is required. See [GitHub's immutable subject claims reference](https://docs.github.com/actions/reference/security/oidc#immutable-subject-claims) and [Microsoft Entra's migration guide](https://learn.microsoft.com/entra/workload-id/workload-identities-github-immutable-subjects) for detailed setup and migration steps. + ### Login With a Service Principal Secret Before you login a service principal secret, you need to prepare a service principal with a secret. @@ -835,7 +847,9 @@ Error: AADSTS7002138: No matching federated identity record found for presented This means Microsoft Entra ID could not find a federated identity credential whose **Subject** exactly matches the subject in the OIDC token that GitHub presented. The token's subject is shown in the run log under `Federated token details` as `subject claim`. Two common causes: - **Case mismatch.** Federated credential subjects are matched **case-sensitively**. If your organization, repository, branch, or environment name uses uppercase characters (for example `repo:My-Org/My-Repo`), the federated credential Subject must use the exact same casing as the `subject claim` in the run log. -- **Subject includes GitHub numeric IDs.** When you create the federated credential in the Azure portal and fill in the optional GitHub owner/repository ID fields, the portal generates a Subject of the form `repo:@/@::`. The OIDC token GitHub sends does **not** include those numeric IDs (its subject is `repo:/::`), so it will never match. Create or edit the federated credential **without** the owner/repository IDs so the Subject matches the token exactly. +- **Immutable subject claims enabled on Azure but not GitHub.** When you create the federated credential in the Azure portal and fill in the optional GitHub owner/repository ID fields, the portal generates a Subject of the form `repo:@/@::`. If GitHub still uses the name-based subject `repo:/::`, the subjects will not match. Choose one of these solutions: + 1. **Recommended:** Enable immutable subject claims on GitHub and configure the matching Azure credential as described in [Immutable subject claims](#immutable-subject-claims). + 2. To keep GitHub's name-based format, edit or recreate the Azure federated identity credential **without** the owner/repository IDs so its Subject matches the token exactly. In both cases, set the federated credential Subject to exactly match the `subject claim` shown in your run's `Federated token details`. See [Configure a federated identity credential](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#github-actions) for details. From 65384ff9071a2d703e4a8a54c2e623611a41dceb Mon Sep 17 00:00:00 2001 From: isra-fel <11371776+isra-fel@users.noreply.github.com> Date: Tue, 17 Nov 2026 13:52:38 +1100 Subject: [PATCH 2/2] docs: incorporate immutable subject announcement and portal guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 28d4d3bc-8553-4068-8689-4d0d39ac2d4c --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a74e8f25e..66317710c 100644 --- a/README.md +++ b/README.md @@ -395,7 +395,7 @@ jobs: #### Immutable subject claims -GitHub's immutable OIDC subject (`sub`) format appends the numeric owner and repository IDs to their names, helping prevent another repository from gaining access if those names are reused. For example, `repo:octo-org/octo-repo:ref:refs/heads/main` becomes `repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main`. +GitHub's [immutable OIDC subject claims](https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens/) append the numeric owner and repository IDs to their names in the subject (`sub`), helping prevent another repository from gaining access if those names are reused. For example, `repo:octo-org/octo-repo:ref:refs/heads/main` becomes `repo:octo-org@123456/octo-repo@456789:ref:refs/heads/main`. Both sides must use the same subject format: @@ -847,9 +847,9 @@ Error: AADSTS7002138: No matching federated identity record found for presented This means Microsoft Entra ID could not find a federated identity credential whose **Subject** exactly matches the subject in the OIDC token that GitHub presented. The token's subject is shown in the run log under `Federated token details` as `subject claim`. Two common causes: - **Case mismatch.** Federated credential subjects are matched **case-sensitively**. If your organization, repository, branch, or environment name uses uppercase characters (for example `repo:My-Org/My-Repo`), the federated credential Subject must use the exact same casing as the `subject claim` in the run log. -- **Immutable subject claims enabled on Azure but not GitHub.** When you create the federated credential in the Azure portal and fill in the optional GitHub owner/repository ID fields, the portal generates a Subject of the form `repo:@/@::`. If GitHub still uses the name-based subject `repo:/::`, the subjects will not match. Choose one of these solutions: +- **Immutable subject claims enabled on Azure but not GitHub.** An Azure federated identity credential whose Subject includes GitHub owner/repository IDs uses the form `repo:@/@::`. If GitHub still uses the name-based subject `repo:/::`, the subjects will not match. Choose one of these solutions: 1. **Recommended:** Enable immutable subject claims on GitHub and configure the matching Azure credential as described in [Immutable subject claims](#immutable-subject-claims). - 2. To keep GitHub's name-based format, edit or recreate the Azure federated identity credential **without** the owner/repository IDs so its Subject matches the token exactly. + 2. To keep GitHub's name-based format, edit the Azure federated identity credential's Subject to **remove** the owner/repository IDs so it matches the token exactly. In both cases, set the federated credential Subject to exactly match the `subject claim` shown in your run's `Federated token details`. See [Configure a federated identity credential](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#github-actions) for details.