Wildcards in Federated Credentials Entra ID (OIDC)

That is a gorgeous present for Christmas and New Year from Microsoft!

As of the end of 2024, Microsoft Entra ID started the public preview of the new feature Federated Credentials!

Here is the official Microsoft documentation about that.

What is Federated Credentials and why is it important?

That is a set of properties and technology that allow to define which external security credentials can be trusted.

Simple!

In Entra ID, you can create a Security Principal identity. Then you can assign this identity with rights: Roles or Permissions within both Entra ID and Azure Cloud.

Any outside service that wants to use the identity must provide credentials. Secrets are the easiest way to do it, but they are also the least safe.

Entra ID supports secretless authentication via Federated Credentials.

So, we can create identities and use them without secrets, right?

Precisely! I wrote an article GitLab, Azure, OpenTofu, and NO secrets! about that.

The most important thing is that you can define a subject field with precise reference to external identity. And that will allow your external identity to associate itself with identity in Entra ID.

That subject definition allows a GitLab pipeline from the rokicool/gitlab-azure-oidc-opentofu project that is executed from the main branch to access our Entra ID identity.

Can you see the name of the project and the branch name in the subject:

project_path:rokicool/gitlab-azure-oidc-opentofu:ref_type:branch:ref:main
?

Don't be scared. If you feel overwhelmed, just look over the mentioned article.

OK. That Federated Credentials thing has been here for years. That is the fuss now?

We are close! Bear with me!

The subject of the Federated Credentials requires explicit, exact reference.

That works perfectly with the main branch! Your pipeline from the main branch can authenticate itself easily.

What if you need to authenticate a pipeline from a feature branch?

Here is the use case. Your developer works on a feature AAA and creates a branch 'feat-JIRA-AAA'. How to authenticate a GitLab pipeline in Entra ID using Federated Credentials? And remember that Entra ID supports only 20 federated credentials per identity.

I can hear your deep sights.

Rejoice! Here are wildcards now!

Instead of an explicit subject, you can define a matching expression.

In our example, it will be something like this:

claims['sub'] matches 'project_path:rokicool/gitlab-azure-oidc-opentofu:ref_type:branch:ref:feat-JIRA-*'

Can you see that the name of the branch is dynamic? So every brach in this project whose name starts with feat-JIRA- will be authenticated! Using one record in the Federated Credentials!

Isn't it cool?

Complicaitons

Wildcards might be tricky, and they might provide access when you don't expect it. That's your responsibility now.

The AUD field. GitLab and Microsoft have different vision

audiences field is part of the Federated Credentials and OIDC protocol.

Microsoft claims that

This field is mandatory and should be set to api://AzureADTokenExchange for Microsoft Entra ID

At the same time, GitLab always puts https://gitlab.com to this field.

But. You can write https://gitlab.com there, and your authentication will work:

Using command line instead of the Portal

Just as it was written in the Microsoft documentation, you can use the az rest command to create the Federated Credentials.

Of course, you should be authenticated as owner of the service principal or higher.

Here is the example that worked for me perfectly:

export OBJECT_ID=<OBJECT_ID (not APP_ID!!!) of your applicaiton or Service Principal>

az rest --method post \
    --url https://graph.microsoft.com/beta/applications/$OBJECT_ID/federatedIdentityCredentials \
    --body "{'name': 'FlexFic2', 'issuer': 'https://gitlab.com', 'audiences': ['https://gitlab.com'], 'claimsMatchingExpression': {'value': 'claims[\'sub\'] matches \'project_path:rokicool/gitlab-azure-oidc-opentofu:ref_type:branch:ref:feat-JIRA-*\'', 'languageVersion': 1}}"

Good luck!