|
| 1 | +--- |
| 2 | +type: post |
| 3 | +title: "GitHub EntraID Federated Credentials With Merge Queue" |
| 4 | +subtitle: "" |
| 5 | +date: 2025-05-08T15:00:23+0100 |
| 6 | +lastMod: 2025-05-08T15:00:23+0100 |
| 7 | +draft: false |
| 8 | +categories: |
| 9 | + - technical |
| 10 | +tags: |
| 11 | + - github |
| 12 | + - azure-entra-id |
| 13 | +--- |
| 14 | + |
| 15 | +## Introduction |
| 16 | + |
| 17 | +I often have GitHub workflows that deploy resources to Azure. |
| 18 | +In the past, I have created a service principal and use the client secret to authenticate to Azure. |
| 19 | +This isn't ideal as if the client secret is leaked then it can be used to access the Azure resources. |
| 20 | +Additionally, the client secret needs to be rotated periodically which can be a pain (yeah, I'm lazy!). |
| 21 | + |
| 22 | +A while back several colleagues pushed me to start using [federated credentials](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure). |
| 23 | +Initially I pushed back as it was another thing to learn and I had other things I needed to get done. |
| 24 | +When I finally got around to it, I found that it was easier than I expected and I'm gradually migrating all of my projects to use federated credentials. |
| 25 | + |
| 26 | +With federated credentials, you can use Azure Entra ID to authenticate to Azure without needing to manage client secrets. |
| 27 | +Instead, your GitHub workflow gets a token from GitHub and then uses that token to get an Azure Entra ID token. |
| 28 | +This flow is shown in the [Entra ID docs](https://learn.microsoft.com/en-gb/entra/workload-id/workload-identity-federation). |
| 29 | + |
| 30 | + |
| 31 | +## Merge Queue - The Challenge |
| 32 | + |
| 33 | +When configuring federated credentials, you need to set up a trust relationship between GitHub and Azure. |
| 34 | +As part of this, you set up the contexts that GitHub will use to authenticate to Azure. |
| 35 | +For example, the screenshot below shows the configuration for the `main` branch of a repository. |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +To use these credentials in a GitHub workflow, you can use the [azure/login](https://github.com/azure/login) action. |
| 41 | +This action needs the client ID of the Azure Entra ID application and the tenant ID of the Azure Entra ID tenant, e.g. from repo variables/secrets. |
| 42 | + |
| 43 | +When the action runs it uses the token from GitHub to get a token from Azure Entra ID. |
| 44 | +It is able to do this because of the federated credentials configuration above. |
| 45 | + |
| 46 | +If you are using the same workflow for multiple contexts, for example pushing to `main` and PRs to `main`, then you need to set up the federated credentials for each context. |
| 47 | +This can be useful, for example if you only want to allow access to your Azure resources from the `main` branch and not from PRs. Or if you want to use different Azure Entra ID identities for different contexts and grant different access to each identity. |
| 48 | + |
| 49 | +At the time of writing, the available options for the entity type in Entra ID are `Environment`, `Branch`, `PullRequest`, and `Tag`. |
| 50 | +Note the lack of `MergeQueue` as an option! |
| 51 | +If you trying running a workflow that uses federated credentials as part of a merge queue run you will get an error similar to the one below. |
| 52 | + |
| 53 | +``` |
| 54 | +Error: AADSTS7002131: No matching federated identity record found for presented assertion subject 'repo:testing-turtle/transient-terrapin:ref:refs/heads/gh-readonly-queue/main/pr-13-7b1f002b00ec25a5facc43e470ef7dfe6d32f300' or no federated identity credential expression matched. Please check your federated identity credential Subject, Expression, Audience and Issuer against the presented assertion. https://learn.microsoft.com/entra/workload-id/workload-identity-federation |
| 55 | +``` |
| 56 | + |
| 57 | + |
| 58 | +## Merge Queue - The workaround |
| 59 | + |
| 60 | +While the configuration UI in Entra ID gives a guided flow for GitHub, it doesn't currently support merge queues. |
| 61 | +Fortunately, it gives us an escape hatch - we can pick the "Other issuer" option from the scenario dropdown and get more control over the configuration. |
| 62 | + |
| 63 | +When using the GitHub token to get the Entra ID token, the token has a subject claim that varies depending on the context. |
| 64 | +The error message above shows us the subject claim that is being presented to Entra ID. |
| 65 | +From this we can see that the subject claim is in the format `repo:{owner}/{repo}:ref:refs/heads/{branch}/pr-{number}-{id}`. |
| 66 | + |
| 67 | +Since the subject claim varies based on the PR number and some other ID value that changes, we can't use standard claim matching. |
| 68 | +Instead, we need to use the preview of claim expressions to match the subject claim. |
| 69 | + |
| 70 | +To enable merge queue runs with federated credentials, we can set the issuer to `https://token.actions.githubusercontent.com` and the claim expression to `claims['sub'] matches 'repo:<{owner}>/{repo}:ref:refs/heads/gh-readonly-queue/{branch}/pr*'` (note that the values for `{owner}`, `{repo}`, and `{branch}` need to be replaced with the actual values for your repository). |
| 71 | +This is shown in the screenshot below. |
| 72 | + |
| 73 | + |
| 74 | + |
| 75 | + |
| 76 | +## Summary |
| 77 | + |
| 78 | +Federated credentials seem like a great way to authenticate to Azure from GitHub workflows. |
| 79 | +They are better for locking down the access to Azure resources and avoid the need to manage client secrets. |
| 80 | + |
| 81 | +Currently, the configuration experience for federated credentials with GitHub merge queues needs a workaround, but hopefully this will be improved in the future. |
0 commit comments