Granting OAuth2 AuthZ in Entra

15 Jan 2026 🔖 intermediate web development
💬 EN

I recently had to troubleshoot an Entra issue that led me down a rabbit-hole crash course in OAuth / Microsoft Entra App Registrations (and their corresponding Entra Service Principals, a.k.a. Entra Enterprise Applications).

Hello world API

I haven’t blogged about it, but 3 years ago, I coded up a small HTTP(S) web API server using the .NET / C# programming framework/language. Check it out at web-site-dotnet-01-tiny.

There are two main ways to get my codebase up and running, so that it can actively receive HTTP requests and issue HTTP responses in return:

1. Execute dotnet run on your laptop (presuming you have the .NET SDK installed onto that laptop), which will give it a base URL like http://localhost:5000.
2. Publish it into a web server hosting service (here, let’s say Azure App Service), which will give it a base URL like https://some.example.com.

My example’s 22 lines of code ensure that if you visit http://localhost:5000/api/SayHello/ / https://some.example.com/api/SayHello/, you will receive back an HTTP response status code of 200, and an HTTP response body containing the following text:

Hello World

The .NET code in charge of handling what happens when someone visits /api/SayHello looks like this:

[ApiController]
[Route("api/[controller]")]
public class SayHelloController : ControllerBase {
    [HttpGet(Name = "GetSayHello")]
    public IActionResult Get() {
        return Ok("Hello World");
    }
}

Protecting the SayHello endpoint

What if, though, just anyone, anywhere on the internet, to be able to receive a valid HTTP response each time they visited /api/SayHello? What if I only wanted to greet visitors I’ve decided should be making HTTP requests to /api/SayHello?

I could, of course, just upgrade my API’s .NET source code to reject all incoming HTTP requests that don’t include:

1. an HTTP header named X-Api-Key with a value matching some super-secret password I gave all of my favorite visitors.

(Note: the actual HTTP response status code would be 401, issued via .NET’s Unauthorized() function, if the visitor got the password wrong or forgot to include one at all.)

Much fancier, though, and more compatible with enterprise-grade APIs, would be to protect /api/SayHello by rejecting all incoming HTTP requests that don’t include:

1. an HTTP header named Authorization…
2. …whose value starts with the phrase “Bearer “…
3. …and the rest of whose value is an appropriate…
4. …base64-encoded copy…
5. …of the plaintext contents of a JSON Web Token (“JWT”)…
6. …issued by an Identity Provider (“IdP”) of my choosing (in this article, Microsoft’s Entra ID)…
7. …as part of an OAuth 2.0 authentication/authorization flow.

• Q: Whew! That was a lot. Why bother?
• A: Because all of those little technical details make it very easy for my API’s .NET code protecting /api/SayHello to determine whether or not the part that comes after “Bearer ” is “appropriate.”

Here’s a sneak preview of the new .NET code in charge of handling what happens when someone visits /api/SayHello:

[ApiController]
[Route("api/[controller]")]
[Authorize(Roles = "PermissionToBeGreeted")]
public class SayHelloController : ControllerBase
{
    // You can get this response by visiting "/api/sayhello" (any capitalization of "sayhello" is fine)
    [HttpGet(Name = "GetSayHello")]
    public c Get()
    {
        // If the token represents a human 
        // (has "oid" and "scp" claims, and not "azp"/"appid" only), 
        // Then we also want to error out if 
        // the Client Application that helped them acquire this 
        // Bearer Token was not a Client Application that is allowed 
        // to help the human do "GreetingSeeking" work.
        var user = HttpContext.User;
        var isHuman = user.HasClaim(c => c.Type == "scp");
        if (isHuman)
        {
            var scopes = user.FindAll("scp").Select(c => c.Value.Split(' ')).SelectMany(s => s);
            if (!scopes.Contains("GreetingSeeking"))
            {
                return Forbid("Missing required scope: GreetingSeeking");
            }
        }
        return Ok("Hello World");
    }
}

Identity providers cannot protect your API

Before we dive into how the IdP plays into all this, it’s important to emphasize:

There’s a reason my .NET code snippet above exploded to 28 lines of code from its original 8. Please take your responsibilities as the person writing the code behind an HTTP(S) web API server very seriously.

If your .NET code forgets to actually validate incoming Bearer tokens against the IdP’s configuration settings, then /api/sayhello is going to 200 Hello World every HTTP request ever, and you’ve done nothing but waste your poor IdP admin’s time, asking for them to data-enter a bunch of configuration settings into the IdP.

That warning aside … let’s dive, now, into all of the configuration settings that can exist inside of your IdP, to support all of the amazing work you’ve done authoring defensive .NET code like:

• Authorize(Roles="...")
• var isHuman = ...
• scopes.Contains(...)

IdP settings for all API visitors

Entra App Registration and its Identifier URI

In addition to my .NET code protecting /api/sayhello, what I didn’t show you earlier was a little bit of boilerplate in the overall web server’s Program.cs file that taught the whole web server exactly where within Entra to look while validating an incoming Bearer token against an IdP’s settings.

I’ll need an Entra admin to create an App Registration (named Greeter-Api, though that’s not important in this article, but it will be in future articles) and, in its “Expose an API” settings blade, give it an “Application ID URI” (a.k.a. “identifier URI”).

Once I find out what value they chose, I’ll want to configure my .NET server settings to know the following four details:

1. The URI, starting with api://, that the IdP admin chose to represent the App Registration.
   • Quick-and-dirty implementation tip: try putting it into a web server environment variable named AZUREAD__AUDIENCE.
   • For the purpose of this article, let’s pretend the Entra admin told me it’s api://123456578-1234-1234-1234567890ab.
2. The “Client ID” GUID that Microsoft Entra auto-generated to represent the App Registration.
   • Quicktip: AZUREAD__CLIENTID environment variable.
   • For the purpose of this article, let’s pretend the Entra admin told me it’s 123456578-1234-1234-1234567890ab.
3. The “Tenant ID” GUID representing which company’s instance of Microsoft Entra the App Registration exists within.
   • Quicktip: AZUREAD__TENANTID environment variable.
   • For the purpose of this article, let’s pretend the Entra admin told me it’s 98765432-9876-9876-9876-9876543210fe.
4. The Entra “instance type” – usually just “https://login.microsoftonline.com/” if you’re using Entra Commercial Cloud.
   • Quicktip: AZUREAD__INSTANCE environment variable.

Not shown: in the .NET web API server’s Program.cs source code file, I had a few extra lines of code such as:

...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
	.AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));
...
app.UseAuthentication(); // Ensures incoming requests get checked for well-formed bearer tokens issued by the IdP noted above.
app.UseAuthorization(); // Ensures policies like roles and scope checks get enforced.
...

App Roles

In my longer 28-line /api/sayhello code above, I, the .NET developer, decided I don’t want /api/sayhello to talk to any incoming HTTP request whose JWT Bearer token, freshly minted by the IdP, doesn’t include a claim named “roles” with a value that includes a role named “PermissionToBeGreeted.”

Here’s the thing: the incoming HTTP request’s Bearer token definitely isn’t going to include the word PermissionToBeGreeted if the IdP doesn’t even know that PermissionToBeGreeted is an option for it to included in Bearer. So let’s tell it!

Back in that 123456578-1234-1234-1234567890ab App Registration that my Entra admin created for me, in its “App Roles” settings blade, I’ll ask the Entra admin to declare that this App Registration contains an “App Role” named “PermissionToBeGreeted.”

App Role Assignments

Now my Authorize(Roles="...") .NET code will work great, rejecting all HTTP requests from visitors that don’t have permission to be greeted.

The problem is, we haven’t yet granted anyone permission to be greeted.

Let’s fix that: we’ll ask the IdP admin to configure the 123456578-1234-1234-1234567890ab App Registration so that exactly two Entra ID “principals” are allowed PermissionToBeGreeted:

1. One nonhuman Entra principal ID (“Service Principal”)
   • For the purpose of this article, we’ll say the nonhuman’s ID within Entra is 76767676-6767-6767-6767-767676767676.
2. One human Entra principal ID (“User”).
   • For the purpose of this article, we’ll say the human’s ID within Entra is 34343434-4343-4343-4343-343434343434.

Over in the “Users and Groups” settings blade of the Entra Service Principal (a.k.a. “Enterprise Application”) corresponding to the 123456578-1234-1234-1234567890ab App Registration that my Entra admin created for me, or over in the Entra Admin Center web portal, I’ll need the Entra admin to grant these two principals PermissionToBeGreeted and admin-consent on their behalf to having been given such an App Role Assignment.

Once that’s done, code running on a machine legitimately represented by the “Service Principal” ID 76767676-6767-6767-6767-767676767676 should stop erroring out when it makes an HTTP GET request to https://some.example.com/api/SayHello/, and should start getting a 200 response that says “Hello World.”

Hooray!

If 76767676-6767-6767-6767-767676767676 happened to represent an Entra Service Principal to which I happened to have the secret or certificate, I could even validate this for myself by:

1. Logging into the Azure CLI as the Service Principal:

    az login `
        --service-principal `
        --tenant '98765432-9876-9876-9876-9876543210fe' `
        --username '76767676-6767-6767-6767-767676767676' `
        --password 'the_secret' `
   

2. Making an HTTP request that uses a Bearer token representing that Service Principal:

    $bearer_token = 
    (
        az account get-access-token `
            --resource 'api://123456578-1234-1234-1234567890ab' `
            --tenant '98765432-9876-9876-9876-9876543210fe' `
            --query 'accessToken' `
            --output 'tsv'
    )
    $response = Invoke-WebRequest `
        -Uri "https://some.example.com/api/SayHello/" `
        -UseBasicParsing `
        -Headers @{ 'Authorization' = "Bearer $bearer_token" }
    $response.StatusCode # Should be 200
    $response.Content.Trim() # Should be "Hello World"
    $bearer_token = $null
   

All of this resulted in a 200 response because nonhumans are allowed to request OAuth 2.0 Client Credentials Grant-typed Bearer access tokens from IdPs, which sort of “just work.”

IdP settings for human visitors

Human 34343434-4343-4343-4343-343434343434 is not so lucky, and would not yet get a 200 response from /api/SayHello.

Remmeber, my .NET app also includes code such as:

• var isHuman = ...
• scopes.Contains("GreetingSeeking")

Heck, they wouldn’t even get a Bearer token out of the Entra IdP just yet.

Even though 34343434-4343-4343-4343-343434343434 is authorized with PermissionToBeGreeted, they still need a computer program to help them request an OAuth 2.0 Authorization Code Grant-typed Bearer access token out of the Entra IdP.

Entra will refuse to issue a human Bearer token to the helper-computer-program unless the request for one specifies:

1. Which type of computer program is helping this human (A web site? The Azure CLI desktop tool? The VSCode desktop software? Etc.), and
2. Exactly which types of work (OAuth 2.0 “scopes”) the helper-computer-program promised assistance on to the human.
3. That the Entra IdP configuration settings were expecting this exact helper-computer-program to be assisting humans with this exact type of work.
4. That this particular human actually consented (whether personally or implicitly based on Entra IdP configuration settings) to let this exact helper-computer-program assist them with this exact type of work.

Scopes

In my longer 28-line /api/sayhello code above, I, the .NET developer, decided I don’t want /api/sayhello to talk to any incoming HTTP request whose JWT Bearer token, freshly minted by the IdP, doesn’t include a claim named “scp” with a value that includes a scope named “GreetingSeeking.”

As with roles, the incoming HTTP request’s Bearer token definitely isn’t going to include the word GreetingSeeking if the IdP doesn’t even know that GreetingSeeking is an option for it to included in Bearer. So let’s tell it!

Back in that 123456578-1234-1234-1234567890ab App Registration that my Entra admin created for me, in its “Expose an API” settings blade, in the section labeled “Scopes,” I’ll ask the Entra admin to declare that this App Registration understands the concept of an “OAuth 2.0 Scope” named “GreetingSeeking.”

Authorized Client Applications

However, we haven’t yet told Entra which helper-computer-programs are allowed to offer humans assistance getting a Bearer token for the alleged purpose of seeking a greeting.

Anyway, let’s go ahead with setting up the alleged authorized client applications list inside Entra, shall we?

• (Now that we’ve reiterated so many times that this is just “alleged” permission to assist a human, and that it’s up to the actual API server to care which allegations the JWT Bearer token are marked by the Entra IdP as “meant for” assisting with.)

We’ll ask the IdP admin to configure the 123456578-1234-1234-1234567890ab App Registration so that exactly one Entra ID “principal” is allowed to help humans acquire Bearer tokens marked as meant for GreetingSeeking:

1. The GUID representing Microsoft’s Azure command-line interface (“CLI”) tool.
   • This is 04b07795-8ddb-461a-bbee-02f9e1bf7b46.

Back in that 123456578-1234-1234-1234567890ab App Registration that my Entra admin created for me, in its “Expose an API” settings blade, toward the bottom in the section labeled “Authorized Client Applications,” I’ll ask the Entra admin to pre-approve the Azure CLI to help humans seek greetings by granting Client ID 04b07795-8ddb-461a-bbee-02f9e1bf7b46 the api://123456578-1234-1234-1234567890ab/GreetingSeeking authorized scope.

Once that’s done, code running on a machine legitimately represented by the human ID 34343434-4343-4343-4343-343434343434 should stop erroring out when it makes an HTTP GET request to https://some.example.com/api/SayHello/, and should start getting a 200 response that says “Hello World.”

Hooray!

If I were human 34343434-4343-4343-4343-343434343434, then I could even validate this for myself in the Azure CLI by doing the following:

1. Prerequisite, just once per machine: do a weird logout-login dance so that I, specifically, can click the flows (note: probably hidden behind other windows, annoyingly, so minimize windows looking for them) to specifically confirm that yes, I want the Azure CLI to help me seek greetings:

    # BEGIN:  Block of code that only has to be run once on a given machine
    az logout
    az login `
        --tenant '98765432-9876-9876-9876-9876543210fe' `
        --scope 'api://123456578-1234-1234-1234567890ab/GreetingSeeking'
    # Popups might be behind your other windows; if things seem to run slow, check for them.
    # Any human except `34343434-4343-4343-4343-343434343434` 
    # should get 403'ed out because they aren't authZ'ed 
    # (authZ phase 1) 
    # for the `PermissionToBeGreeted` **role**.
    # But even other humans should still be taken 
    # through the flow of getting a Bearer token.
    # And that Bearer token will even include the `GreetingSeeking` scope.
    # (But that should be irrelevant, because the .NET should not 
    # even bother to check authZ phase 2 if authZ phase 1 failed.)
    # Popups should, I believe, warn all humans who 
    # seek a bearer token using this code 
    # that the Azure CLI ALLEGEDLY 
    # wants to help them **SEEK GREETINGS**.
    # Anyway, this "az login" step fails if the Azure CLI is not on the 
    # preapproved list of Authorized Client Applications 
    # allowed to help humans "seek greetings."
    az logout
    az login
    # END:  Block of code that only has to be run once on a given machine
   

2. Make an HTTP request that uses a Bearer token representing me and the “scopes” Entra confirmed that I’ve allowed my helper-computer-program to ask to help me with:

    # BEGIN:  Block of code that has to be run every time a human wants to be greeted
    $bearer_token = 
    (
        az account get-access-token `
            --resource '123456578-1234-1234-1234567890ab' `
            --tenant '98765432-9876-9876-9876-9876543210fe' `
            --query 'accessToken' `
            --output 'tsv'
    )
    # The above attempt to fetch a bearer token 
    # will fail if the Azure CLI is not 
    # an "authorized client application" for 
    # any "scopes" over in Entra IdP configuration settings.
    # If it's preauthorized to help humans with at least 1 "scope," 
    # I believe that Entra will issue a JWT Bearer token 
    # whose "scp" claim details include a list of all of the 
    # scopes that the Azure CLI has both:
    # 1. Both been preauthorized to help humans in general with, and
    # 2. Been authorized, as during "az login --scope" above, 
    # by this particular human, to help them specifically with.
    # But I need to try all the nuances again; I forget a lot of it.
    $response = Invoke-WebRequest `
        -Uri "https://some.example.com/api/SayHello/" `
        -UseBasicParsing `
        -Headers @{ 'Authorization' = "Bearer $bearer_token" }
    $response.StatusCode # Should be 200
    $response.Content.Trim() # Should be "Hello World"
    $bearer_token = $null
    # END:  Block of code that has to be run every time a human wants to be greeted
   

No authorized desktop clients

Hot take: Despite the Azure CLI being my teaching example, I don’t think you actually should authorize software that runs directly on a general-purpose desktop computer to serve as an Authorized Client Application to your enterprise web APIs.

They’re far too much “general computation” that can go rogue on an endpoint without much oversight, compared to a proper web site running in a web browser that a human will notice.

No Azure CLI, no Azure PowerShell, no VSCode, no Visual Studio, etc. etc. etc.

Your enterprise web APIs don’t just greet people – they do stuff that a general-purpose programming environment like an IDE or CLI just really shouldn’t be left lying around as something willing to “helpfully” act on behalf of humans who need to make calls to your enterprise web APIs.

If your developers need to emulate a nonhuman, make them create an actual second nonhuman, like in the 76767676-6767-6767-6767-767676767676 example above. The gap between “nonhuman” and “human,” in OAuth, is just too wide, and it’s probably more secure to authorize a second nonhuman to take the place of a first one than it is to suddenly add humans where there weren’t humans.

Even if your app already has legitimate frontend web sites as Authorized Client Applications that help humans acquire Bearer tokens out of Entra, those are deterministic pieces of JavaScript that hopefully you control the publication of, and that have controlled rates of change. They’re not just, say, a virus running loose on a laptop poking at the Azure CLI or the VSCode terminal.

I’m sure there are exceptions, but I think that “just don’t” is a good rule of thumb. Don’t add desktop tools’ GUIDs to your Authorized Client Applications that are allowed to request Bearer tokens into your internal web APIs on behalf of humans. Require some serious governance / exception hurdles, is what my gut is telling me.

I’m no identity architect, but my gut, as a general-purpose security-minded architect, is even telling me to consider going so far as to run scripts to look for major desktop tool GUIDs in Entra and kick them out periodically if they don’t have an exception.

More to come

Oofda. You tired yet? I was, figuring all this out!

Not covered: other “blades” of Entra App Registration settings, like the one labeled “API Permissions,” which is … like … kind of the opposite of what this article covered. (Hint on that: thanks to the App Role Assignments our IdP admin did, if 76767676-6767-6767-6767-767676767676 happened to be the type of Entra Service Principal that comes from an Entra App Registration, then its PermissionToBeGreeted by 123456578-1234-1234-1234567890ab would automatically show up ,marked as type “Application”, within the “Configured Permissions” section of 76767676-6767-6767-6767-767676767676’s own “API Permissions” configuration-settings blade! That’s what I mean by it kind of being “the opposite” side of authZ from what we covered today. Today we covered “granting” alleged authorization; “API Permissions” has more to do with “requesting” alleged authorization. Either way, please remember – it’s all alleged! Entra is just a record of alleged/desired authorization grants. API server coders still have to program their codebases to care what Entra thinks!)

LLM enhancements

I ran this article through an LLM and it had some pretty great enhancements.

Infographic

It autogenerated the infographic serving as this post’s header image.

Quiz

I love this 10-question quiz it came up with.

• (click expander icon at left – it’s a rightward-facing triangle – to reveal the quiz questions below)

• Answers (click expander icon at left – it’s a rightward-facing triangle – to reveal the answers)

Simpler blog post

Dangit, the LLM’s a better, clearer blogger than me. I love its (albeit very American) metaphors about the DMV vs. the bouncer.

• (click expander icon at left – it’s a rightward-facing triangle – to reveal the blog post titled “Securing Your API: A Simple Guide to OAuth2, Roles, and Scopes with Entra ID”)