From fa61ac638d479815f2f7d9f75f71e64a80e76a0e Mon Sep 17 00:00:00 2001 From: Maddison Das <272712104+MaddyMicrosoft@users.noreply.github.com> Date: Fri, 21 Aug 2026 02:32:29 +0100 Subject: [PATCH 1/3] Add Troubleshooting section for OIDC federated credential subject mismatch Document the AADSTS700213 / AADSTS7002138 "no matching federated identity record" failures caused by case-sensitive subject matching and by portal- generated subjects that include GitHub owner/repository numeric IDs. Addresses #617. Also relevant to #573. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index 5d3085cfb..7b56544a6 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ - [Login to Azure Stack Hub](#login-to-azure-stack-hub) - [Login without subscription](#login-without-subscription) - [Enable/Disable the cleanup steps](#enabledisable-the-cleanup-steps) + - [Troubleshooting](#troubleshooting) + - [OIDC login fails with `AADSTS700213` / `AADSTS7002138` (no matching federated identity record)](#oidc-login-fails-with-aadsts700213--aadsts7002138-no-matching-federated-identity-record) - [Security hardening](#security-hardening) - [Azure CLI dependency](#azure-cli-dependency) - [Reference](#reference) @@ -737,6 +739,29 @@ jobs: ``` +## Troubleshooting + +### OIDC login fails with `AADSTS700213` / `AADSTS7002138` (no matching federated identity record) + +When logging in with OIDC, the login may fail with an error similar to: + +```text +Error: AADSTS700213: No matching federated identity record found for presented assertion subject 'repo:/:environment:production'. +``` + +or: + +```text +Error: AADSTS7002138: No matching federated identity record found for presented assertion subject 'repo:/:ref:refs/heads/main'. The subject matches with case-insensitive comparison, but not with case-sensitive comparison. +``` + +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. + +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. + ## Security hardening > [!WARNING] From a144e288ebc1db25b34445272cf2526e02ee597d Mon Sep 17 00:00:00 2001 From: Maddison Das <272712104+MaddyMicrosoft@users.noreply.github.com> Date: Fri, 21 Aug 2026 06:09:03 +0100 Subject: [PATCH 2/3] Document intentional client-id masking in workflow logs Explain in the client-id input section that the action registers the client-id as a secret (core.setSecret), why it is masked, and that tenant-id and subscription-id are not masked. Addresses #566. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 7b56544a6..daebf02bc 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,9 @@ It's better to create a GitHub Action secret for this parameter when using it. R Refer to [Login With OpenID Connect (OIDC)](#login-with-openid-connect-oidc-recommended) and [Login With User-assigned Managed Identity](#login-with-user-assigned-managed-identity) for its usage. +> [!NOTE] +> The action registers the `client-id` value as a secret (via `core.setSecret`) so it is masked in workflow logs. Some enterprises treat the client ID as sensitive, and masking also prevents it from being printed accidentally, which matters in public repositories. `tenant-id` and `subscription-id` are not masked. + ### `subscription-id` The input parameter `subscription-id` specifies the login subscription id. From d563b25b7e2597658e9a78086a56ff3060b49d19 Mon Sep 17 00:00:00 2001 From: Maddison Das <272712104+MaddyMicrosoft@users.noreply.github.com> Date: Fri, 21 Aug 2026 06:30:40 +0100 Subject: [PATCH 3/3] Document Azure CLI 2.66.x requirement for Azure Stack Hub Note in the Azure Stack Hub section that Azure CLI newer than 2.66.x no longer supports Azure Stack Hub, so environment: 'AzureStack' requires pinning Azure CLI to 2.66.x (LTS). Prevents the failure reported when using the example on a current runner. Addresses #534. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index daebf02bc..c4f105c67 100644 --- a/README.md +++ b/README.md @@ -570,6 +570,9 @@ jobs: ### Login to Azure Stack Hub +> [!NOTE] +> Azure CLI versions newer than 2.66.x no longer support Azure Stack Hub. To use `environment: 'AzureStack'`, pin Azure CLI to 2.66.x (LTS), for example via the [Azure CLI action](https://github.com/Azure/cli) with `azcliversion: 2.66.0`. See the [Azure CLI notice for Azure Stack Hub customers](https://learn.microsoft.com/cli/azure/whats-new-overview?view=azure-cli-latest#important-notice-for-azure-stack-hub-customers). + ```yaml # File: .github/workflows/workflow.yml