Entra ID – Deep Dive – Entra ID Authentication – Part 3

Posted on June 24, 2026 by mattfeltonma

This is part of my series on Microsoft Entra ID:

Back for more are ya? Today we’re gonna chat about how you could add Entra ID authentication into your custom-built web application. I’ll be digging into the Entra ID application registration process and examining the requests and responses for the whole authentication process via a local proxy using HTTP Toolkit. The goal here is not to give you coding best practices (god save you if you use any of my code in production) but instead to help you understand how all this stuff works and how products are (and are not) exercising the OIDC and OAuth protocols under the hood.

If you haven’t read my first and second post in the series, stop what you’re doing right now and read them. I’m going into this post assuming you have and thus assuming knowledge and understanding basic Entra ID concepts like applications vs service principals and a foundational understanding of OIDC and OAuth.

The solution design I’m building towards this in this series of posts is a simple frontend web application and backend API that are using Entra ID for authentication and authorization. The end design will look something like the below. This post will focus on the frontend web application.

Creating the frontend application registration

As I covered in my first post, the application registration (or application object) is the globally unique representation of the application across Entra ID. There can only be one application registration for an application across all of Entra. An application registration can be single tenant (used only in your Entra ID tenant) or multi-tenant (can be used across Entra ID tenants). I like to think of the process of creating the application process similar to the manual client registration process mentioned in the OAuth spec. The result is the same as we’ll configure a bunch of information required for OAuth such as the redirect URI, the grant types it supports, and whether the client will be public or confidential client. Once registered, Entra will return a unique client_id and client_secret if a confidential application. There are additional Entra-specific properties we can populate, but the manual client registration explanation makes the most sense in my brain at least.

Creating an application registration can be done through the Portal, CLI/PowerShell, REST, Terraform, etc. I’m going to create it direct through the Microsoft Graph REST API because I want to walk through all the gory properties. To create an app registration, your user account needs to be at least hold the Entra ID Application Developer role. To keep things simple and address my laziness, my user will be setup as a global admin.

			
# Set the properties for the application
app_display_name = "Demo frontend app for Entra authentication"
description = "This app is used to demonstrate a frontend application where a user authenticates using Entra ID authentication via OIDC"
contact = "business_unit1@jogcloud.com"
........
# Create an app registration
def create_app_registration(display_name: str, contact: str):
    """This function creates a new application registration in Microsoft Graph API if it doesn't already exist
    Args:
        display_name (str): The display name for the new application registration.
        contact (str): The contact information to associate with the application registration.
    Returns:
        dict: The details of the created application registration.
    """
    check_app = get_app_registration_by_display_name(display_name)
    if check_app is not None:
        print(f"Application {check_app['displayName']} already exists and its id is {check_app['id']}")
        return check_app
    else: 
        print("Creating new application registration...")
        body = {
            "displayName": display_name,
            "description": description,
            # Setting to false means this is a confidential client application vs a public client
            "isFallbackPublicClient": False,
            # Set a service management reference which can be the contact associated with the application
            "serviceManagementReference": contact,
            # Create the app as multi tenant; single tenant would use AzureADMyOrg
            "signInAudience": "AzureADMultipleOrgs",
            # Add a redirect URI to support OIDC authentication
            "web": {
                "redirectUris": [
                    "http://localhost:8100/callback"
                ]
            }
        }
        response = requests.post(
            'https://graph.microsoft.com/v1.0/applications',
            headers={
                'Content-Type': 'application/json',
                'Authorization': f'Bearer {user_token.token}'
            },
            json=body
        )
        return response.json()
app_frontend = create_app_registration(app_display_name, contact)
print(json.dumps(app_frontend, indent=2))

		

The application registration I’m creating above is being created as a multi-tenant application instead of a single tenant application and is determined by the signInAudience being set to a value of AzureADMultipleOrgs. I’m doing this because I may do an additional post in this series walking through multi-tenant applications. Most of the application registrations you create will be single tenant and would have this property set to AzureADMyOrg.

Since I’m building a web application, I’m going to be configuring it as a confidential client (which means it will have a credential) and I’m going to use the authorization code flow. I don’t want my application registration to ever support being used as a public client so I set isFallbackPublicClient to false. This will force my client to provide a credential when attempting to obtain a token. If you were building an application that would live direct on the user’s desktop or mobile device, you’d need to set to that true because at that point your application would be a public client.

Under the web property, I’m setting the redirectUri property to the endpoint in my application I want the user redirected to after the user successfully authenticates to Entra and consents to whatever access I’m requesting (if consent is required). In this case, my application runs directly on my machine so this is set to localhost.

You’ll also see I’m setting the serviceManagementReference property. Best practice is for you to set this property with a contact within the business unit for that owns the application. This can be helpful if the application registration becomes stale at this point and you detect that during your regular audits (which OF COURSE you’re doing!)

Once complete, I get the response below.

			
Creating new application registration...
{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
  "id": "be0af053-faf4-44b3-b071-XXXXXXXX",
  "deletedDateTime": null,
  "appId": "fc815c55-d456-4d38-be76-XXXXXXXX",
  "applicationTemplateId": null,
  "disabledByMicrosoftStatus": null,
  "createdByAppId": "04b07795-8ddb-461a-XXXXXXXXXXXX",
  "createdDateTime": "2026-06-25T01:19:12.1150491Z",
  "displayName": "Demo frontend app for Entra authentication",
  "description": "This app is used to demonstrate a frontend application where a user authenticates using Entra ID authentication via OIDC",
  "groupMembershipClaims": null,
  "identifierUris": [],
  "isDeviceOnlyAuthSupported": null,
  "isDisabled": null,
  "isFallbackPublicClient": false,
  "nativeAuthenticationApisEnabled": null,
  "notes": null,
  "publisherDomain": "XXXXXXXX.onmicrosoft.com",
  "serviceManagementReference": "business_unit1@jogcloud.com",
  "signInAudience": "AzureADMultipleOrgs",
  "tags": [],
  "tokenEncryptionKeyId": null,
  "uniqueName": null,
  "samlMetadataUrl": null,
  "defaultRedirectUri": null,
  "certification": null,
  "optionalClaims": null,
  "servicePrincipalLockConfiguration": null,
  "requestSignatureVerification": null,
  "addIns": [],
  "api": {
    "acceptMappedClaims": null,
    "knownClientApplications": [],
    "requestedAccessTokenVersion": null,
    "oauth2PermissionScopes": [],
    "preAuthorizedApplications": []
  },
  "appRoles": [],
  "info": {
    "logoUrl": null,
    "marketingUrl": null,
    "privacyStatementUrl": null,
    "supportUrl": null,
    "termsOfServiceUrl": null
  },
  "keyCredentials": [],
  "parentalControlSettings": {
    "countriesBlockedForMinors": [],
    "legalAgeGroupRule": "Allow"
  },
  "passwordCredentials": [],
  "publicClient": {
    "redirectUris": []
  },
  "requiredResourceAccess": [],
  "verifiedPublisher": {
    "displayName": null,
    "verifiedPublisherId": null,
    "addedDateTime": null
  },
  "web": {
    "homePageUrl": null,
    "logoutUrl": null,
    "redirectUris": [
      "http://localhost:8100/callback"
    ],
    "implicitGrantSettings": {
      "enableAccessTokenIssuance": false,
      "enableIdTokenIssuance": false
    },
    "redirectUriSettings": [
      {
        "uri": "http://localhost:8100/callback",
        "index": null
      }
    ]
  },
  "spa": {
    "redirectUris": []
  }
}

		

Next up, I want to set an owner. Every application registration should have an owner and this is a child object of the application. Now don’t go willy-nilly throwing any business unit person into that field (the owner cannot be a group as of the date of this post). When a user is an owner of an application registration, they can modify the application registration. The owner should be set to some privileged user account in Entra where access to that privileged account is tightly controlled.

			
import requests
import json
# Set the owners of the application using their Entra ID user object id
owners = [
    "2e69d9f2-b5b3-482b-9c15-XXXXXXXXXXXX"
]
........
# Add owners to the application registration
def add_owners_app_registration(owners: list, app_id: str):
    """This function adds owners to an application registration in Microsoft Graph API
    Args:
        owners (list): A list of Entra ID user object IDs to add as owners.
        app_id (str): The object ID of the application registration to add owners to.
    Returns:
        list: The updated list of owners for the application registration.
    """
    # Check the current owners to see if the owner is already listed
    check_owners = get_app_registration_owner(app_id)
    if check_owners is not None:
        for owner in owners:
            if owner in [o['id'] for o in check_owners]:
                 print(f"Owner {owner} is already an owner of the application.")
            # Since owner isn't there, add it
            else:
                print(f"Adding owner {owner} to the application...")
                response = requests.post(
                    f'https://graph.microsoft.com/v1.0/applications/{app_id}/owners/$ref',
                    headers={
                        'Content-Type': 'application/json',
                        'Authorization': f'Bearer {user_token.token}'
                    },
                    json={
                        "@odata.id": f"https://graph.microsoft.com/v1.0/directoryObjects/{owner}"
                    }
                )
                if response.status_code == 204:
                    print(f"Owner {owner} added successfully.")
                else:
                    print(f"Failed to add owner {owner}. Response: {response.status_code} - {response.text}")
    else:
        print("No current owners found for the application.")
        for owner in owners:
            print(f"Adding owner {owner} to the application...")
            response = requests.post(
                f'https://graph.microsoft.com/v1.0/applications/{app_id}/owners/$ref',
                headers={
                    'Content-Type': 'application/json',
                    'Authorization': f'Bearer {user_token.token}'
                },
                json={
                    "@odata.id": f"https://graph.microsoft.com/v1.0/directoryObjects/{owner}"
                }
            )
            if response.status_code == 204:
                print(f"Owner {owner} added successfully.")
            else:
                print(f"Failed to add owner {owner}. Response: {response.status_code} - {response.text}")
    new_owners = get_app_registration_owner(app_id)
    return new_owners
new_owners = add_owners_app_registration(owners = owners, app_id=app_frontend['id'])
print(json.dumps(new_owners, indent=2))

		

Next up I need to create a client credential for my application. This will act as its client_secret to support its confidential client status. Entra supports multiple types of credentials including a basic client secret, client certificate, and federated credential. Of the three, the federated credential is the sweet spot if you can make it work. This is where you can use something like a managed identity which means the actual secret is automatically managed and rotated by Microsoft. Way easier lifecycle. Federated credentials can also use external identity providers, like GCP, GitHub and others neat integrations via the workload identity federation. A client certificate should be your next preferred credential since it has higher assurance and avoids having to worry about secret rotation and leakage. Since I’m lazy, I’ll be using a client secret.

Below I create a client secret that will be valid for a year.

			
# Create a date one year from now that will be used to expire the app registration credential
start_date = datetime.now(timezone.utc)
end_date = (datetime.now(timezone.utc) + relativedelta(years=1)).replace(hour=23, minute=59, second=59, microsecond=0)
formatted_start_date = start_date.strftime('%Y-%m-%dT%H:%M:%SZ')
formatted_end_date = end_date.strftime('%Y-%m-%dT%H:%M:%SZ')
.........
# Create a client secret
def create_password_credential(app_id, end_date, start_date, override=False):
    """This function creates a password credential for an application registration in Microsoft Graph API. It will delete existing 
    credentials if override is set to True, otherwise it will return a message that a credential already exists.
    Args:
        app_id (str): The object ID of the application registration to create a password credential for.
        end_date (str): The end date and time for the password credential in ISO 8601 format.
        start_date (str): The start date and time for the password credential in ISO 8601 format.
        override (bool): Whether to override existing password credentials. Defaults to False.
    Returns:
        dict: The deatils of the created password credential or a blank dict if a credential already exists and override is False.
    """
    # Check to see if the app already has a password credential
    app = get_app_registration(app_id)
    if app['passwordCredentials'] == []:
        # Create a new credential
        body = {
            "displayName": "primary",
            "endDateTime": end_date,
            "startDateTime": start_date
        }
        response = requests.post(
            f'https://graph.microsoft.com/beta/applications/{app_id}/addPassword',
            headers={
                'Content-Type': 'application/json',
                'Authorization': f'Bearer {user_token.token}'
            },
            json=body
        )
        if response.status_code != 200:
            print(f"Error creating password credential: {response.status_code}: {response.text}")
        else:
            print("Created new password credential.")
            return response.json()
    elif override:
        # Delete existing credentials
        for cred in app['passwordCredentials']:
            print("Deleting existing password credential...")
            response = requests.post(
                f'https://graph.microsoft.com/beta/applications/{app_id}/removePassword',
                headers={
                    'Content-Type': 'application/json',
                    'Authorization': f'Bearer {user_token.token}'
                },
                json={
                    "keyId": cred['keyId']
                }
            )
            if response.status_code != 204:
                print(f"Error deleting password credential: {response.status_code}: {response.text}")
        # Create a new credential
        body = {
            "displayName": "primary",
            "endDateTime": end_date,
            "startDateTime": start_date
        }
        response = requests.post(
            f'https://graph.microsoft.com/beta/applications/{app_id}/addPassword',
            headers={
                'Content-Type': 'application/json',
                'Authorization': f'Bearer {user_token.token}'
            },
            json=body
        )
        if response.status_code != 200:
            print(f"Error creating password credential: {response.status_code}: {response.text}")
        else:
            print("Created new password credential after deleting existing one.")
            return response.json()
    else:
        print("A secret already exists. You can delete it and create a new one by setting override=True")
        return app['passwordCredentials'][0]
        
password_credential_frontend = create_password_credential(app_frontend['id'], formatted_end_date, formatted_start_date, override=False)

		

Alright, at this point we have an application registration and client credential, which essentially means we have manually registered the application as an OAuth client to the authorization server (Entra ID). I now have a client_id (appId property) and client_secret. What next?

Creating the frontend service principal

I now need a security principal (or identity) to represent my application in my Entra ID tenant. In comes the service principal. There are many types of service principals as I mentioned previously, for this use case I’ll be creating an application service principal. Manual creation of this is only required because I’m creating it programmatically through REST. If I created this app registration in Azure Portal a service principal would automatically be created.

Creating the service principal is very straightforward and there’s not much need you to pass beyond the appId (or client id) of the application registration.

			
def create_service_principal(app_id: str):
    """This function creates a service principal for an application registration in Microsoft Graph API if it doesn't already exist
    Args:
        app_id (str): The application ID of the service principal to create.
    Returns:
        dict or None: The details of the created service principal if successful, otherwise None.
    """
    # Check to see if the service principal already exists
    service_principal = get_service_principal_by_app_id(app_id)
    if service_principal is not None:
        print(f"Service principal already exists: {service_principal['id']}")
        return service_principal
    else:
        body = {
            "appId": app_id
        }
        response = requests.post(
            'https://graph.microsoft.com/v1.0/servicePrincipals',
            headers={
                'Content-Type': 'application/json',
                'Authorization': f'Bearer {user_token.token}'
            },
            json=body
        )
        if response.status_code == 201:
            return response.json()
        else:
            print(f"Error creating service principal: {response.status_code}: {response.text}")
            return None
# Get or create the service principal
service_principal_frontend = create_service_principal(app_frontend['appId'])
print(json.dumps(service_principal_frontend, indent=2))

		

This spits out a new service principal object seen below. You’ll notice the schema is somewhat similar to the application registration schema. The service principal will be the object the application uses to exercise permissions it is delegated across the platform.

			
{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals/$entity",
  "id": "ce341fd2-fd6b-4dab-9beb-XXXXXXXXXXXX",
  "deletedDateTime": null,
  "accountEnabled": true,
  "alternativeNames": [],
  "appDisplayName": "Demo frontend app for Entra authentication",
  "appDescription": "This app is used to demonstrate a frontend application where a user authenticates using Entra ID authentication via OIDC",
  "appId": "fc815c55-d456-4d38-be76-XXXXXXXXXXX",
  "applicationTemplateId": null,
  "appOwnerOrganizationId": "6c80de31-d5e4-4029-93e4-XXXXXXXXXXXX",
  "appRoleAssignmentRequired": false,
  "createdByAppId": "04b07795-8ddb-461a-bbee-XXXXXXXXXXXX",
  "createdDateTime": "2026-06-25T01:41:05Z",
  "description": null,
  "disabledByMicrosoftStatus": null,
  "displayName": "Demo frontend app for Entra authentication",
  "homepage": null,
  "isDisabled": null,
  "loginUrl": null,
  "logoutUrl": null,
  "notes": null,
  "notificationEmailAddresses": [],
  "preferredSingleSignOnMode": null,
  "preferredTokenSigningKeyThumbprint": null,
  "replyUrls": [
    "http://localhost:8100/callback"
  ],
  "servicePrincipalNames": [
    "fc815c55-d456-4d38-be76-XXXXXXXXXXX
  ],
  "servicePrincipalType": "Application",
  "signInAudience": "AzureADMultipleOrgs",
  "tags": [],
  "tokenEncryptionKeyId": null,
  "samlSingleSignOnSettings": null,
  "addIns": [],
  "appRoles": [],
  "info": {
    "logoUrl": null,
    "marketingUrl": null,
    "privacyStatementUrl": null,
    "supportUrl": null,
    "termsOfServiceUrl": null
  },
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "passwordCredentials": [],
  "resourceSpecificApplicationPermissions": [],
  "verifiedPublisher": {
    "displayName": null,
    "verifiedPublisherId": null,
    "addedDateTime": null
  }
}

		

Document your required permissions!

It’s best practice to document the permission your application will require versus being an asshole and forcing someone to guess, struggle, learn to hate you, and likely over permission. Permissions are divided into two categories which include role permissions and scope permissions. Role permissions are going to be the permissions the app exercises using its own identity context (we’ll see some of this in a future post) and scope permissions are going to be delegated permissions it requires. The permissions an application requires can be documented as part of the app registration by setting the requiredResourceAccess property of the application registration. This doesn’t grant any access, but simply informs the administrator what permissions will be required from the application. Remember, the app registration is the template for the application.

			
# Get the existing app permissions
def get_app_permissions(id: str):
    """This function retrieves the existing permissions required for an application registration from the Microsoft Graph API.
    Args:
        id (str): The object ID of the application registration to retrieve permissions for.
    Returns:
        list: A list of required resource permissions or else an empty list
    """
    response = requests.get(
        f'https://graph.microsoft.com/v1.0/applications/{id}',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {user_token.token}'
        }
    )
    if response.status_code != 200:
        print(f"Error getting app permissions: {response.status_code}: {response.text}")
        return None
    
    # Return the current permission set or a blank array if there are no permissions currently set
    return response.json().get('requiredResourceAccess') or []
# Add the app permissions to the app registration. This is useful for multi-tenant apps to document required permissions. It does not grant any permissions.
def add_app_permissions(app_id: str, resource_access: list):
    """This function adds the required permissions to an application registration in Microsoft Graph API
    Args:
        app_id (str): The object ID of the application registration to add permissions to.
        resource_access (list): A list of permissions to add to the application registration in the format of requiredResourceAccess.
    Returns:
        dict or None: The updated application registration details if successful, otherwise None.
    """
    # Get the existing permissions in order to append to them
    app_permissions = get_app_permissions(app_id)
    # Append the new permissions to the existing ones
    for permission in resource_access:
        # Check if this resource already exists in the app permissions
        existing_resource = None
        for resource in app_permissions:
            if resource['resourceAppId'] == permission['resourceAppId']:
                existing_resource = resource
                break
        if existing_resource:
            # Append the new permissions to the existing resource
            for access in permission['resourceAccess']:
                if access not in existing_resource['resourceAccess']:
                    existing_resource['resourceAccess'].append(access)
        else:
            # Add the new resource and its permissions
            app_permissions.append(permission)
    
    # Update the app registration with the new permissions
    body = {
        "requiredResourceAccess": app_permissions
    }
    response = requests.patch(
        f'https://graph.microsoft.com/v1.0/applications/{app_id}',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {user_token.token}'
        },
        json=body
    )
    if response.status_code != 204:
        print(f"Error adding app permissions: {response.status_code}: {response.text}")
        return None
    else:
        print("App permissions documented as required successfully.")
        return get_app_registration(app_id)
new_permissions = [
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",  # Microsoft Graph
        "resourceAccess": [
            {
                "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",  # User.Read
                "type": "Scope"
            }
        ]
    }
]
app_required_permissions = add_app_permissions(app_frontend['id'], new_permissions)['requiredResourceAccess']
print("\n=== App required permissions ===")
print(json.dumps(app_required_permissions, indent=2))

		

Once those are added they will appear in the API permissions section of the Application Registration inside of the Azure Portal as seen below. For my app I’m documenting that it requires the User.Read delegated permission on the Microsoft Graph API. For some of the built-in applications like the Microsoft Graph, some permissions will require admin consent and some will not like User.Read. If you add these things programmatically, it’s a bit more work because you need to dig up the resource’s appId and object ids of the permission. Something like Microsoft Graph is well documented.

Alright, at this point we’re ready to test our app!

Authenticating to the application

After starting the application I immediately see a lookup to metadata endpoint for the OIDC and OAuth endpoints. This is triggered an MSAL instance is started in the code. These endpoints will be used throughout the login process.

Opening my website I’m faced with a very simple login screen (simple setup for a simple man).

Once I click login with Entra ID, the underlining MSAL library redirects me to the /authorize endpoint of Entra where my user is prompted to authenticate. The request that is generated is below. In this request we see all the things we covered in the second post for the protocol primer. There is the redirect URI that the user will be redirected to after authenticating to Entra, the response_type indicating this is the authorization code grant type, the client id of my application, the state property used to mitigate CSRF attacks, the nonce to prevent replay attacks, and the code challenge and code challenge method for PKCE.

Now one thing to note is you’ll find a lot of samples on the wider Internet for MSAL (and likely generated by LLMs if you’re one of those vibe coders) that will use the acquire_token_for_client method (like this Microsoft sample here). This method WILL NOT use PKCE. If you want to include the code challenge and code verifier for PKCE you will need to use the initiate_auth_code_flow method.

The scopes query perimeter includes the Microsoft Graph User.Read permission, offline_access (for a refresh token), openid (for an id token), and profile (for access to the user’s basic profile for OIDC). The code in my app specifically requests User.Read, the remaining scopes are automatically added by MSAL for each request depending on the method you’re calling.

			
https://login.microsoftonline.com/6c80de31-d5e4-4029-93e4-XXXXXXXXXXXX/oauth2/v2.0/authorize?
client_id=afbd7539-a21f-4d11-93a3-XXXXXXXXXXXX&
response_type=code&
redirect_uri=http%3A%2F%2Flocalhost%3A8100%2Fcallback&
scope=User.Read+offline_access+openid+profile&
state=iuxzJhtpdQrWHKqG&code_challenge=L2KNF971_Izy0wWY4v_8GJ1XXXXXXXXXXXX&
code_challenge_method=S256&
nonce=b448a1420a781ac5f18bc2db7f74e06a42fbedca3dd04ebdXXXXXXXXXXXX&
client_info=1

		

My user completes the authentication process the user is prompted to consent to the application to be delegated the requested scopes. Once the user accepts, the user’s consent is saved in Entra and the user is no longer required to consent moving forward. You’ll notice my application says app is unverified because it’s using localhost. For anything remotely relating to production, you should configure a publishing domain and validate it.

Once the user consents, the user is redirected to the redirect uri registered for the application with an authorization code generated by Entra. My application then makes a call to the /oauth2/v2.0/token endpoint in Entra to exchange the authorization code for an access token, identity token, and refresh token. It provides its client secret to authenticate itself to Entra and the code_verifier value allowing Entra to validate this is the original client who requested the access token (PKCE).

Entra validates the client secret and code verifier and if valid returns an access token, refresh token, and id token. My application can use the id token to authenticate the user and grant it access to the application.

Once logged in, I navigate to the profile page of the application. This page has basic profile information about the user collected from the get user endpoint in the Microsoft Graph.

Navigating to the tokens page of the application displays the decoded access token and id token. In the payload of the id token we can see this id token is intended for the application (which you must validate in your code to ensure someone isn’t trying to pass you some rando token meant for another application) via the aud claim. We also get some basic information about the user. The full schema of the id token is in the official public docs. Some of the helpful properties are the user’s full name and their object id (oid). The object id could be used to pull additional information about the user (which we’ll see next post). We can also stuff additional claims in this id token if we wanted to. I’ll demonstrate this in a future post where I add a user’s group memberships into the id token.

			
{
  "aud": "fc815c55-d456-4d38-be76-XXXXXXXXXXXX",
  "exp": 1782358405,
  "iat": 1782354505,
  "iss": "https://login.microsoftonline.com/6c80de31-d5e4-4029-93e4-XXXXXXXXXXXX/v2.0",
  "name": "Carl Carlson",
  "nbf": 1782354505,
  "nonce": "19297055204c96a487b701f62890cf1c867a7fac55814081f53cbe4XXXXXXXX",
  "oid": "2e69d9f2-b5b3-482b-9c15-XXXXXXXXXXXX",
  "preferred_username": "carl.carlson@jogcloud.com",
  "rh": "1.AbcAMd6AbOTVKUCT5ForPA4SmVVcgfxW1XXXXXXXXXXXX",
  "sid": "005f65fa-bad8-71a5-49eb-XXXXXXXXXXXX",
  "sub": "p9RBIgpi113pdPH37Q50qylIbANwgMtDXXXXXXXXXXXX",
  "tid": "6c80de31-d5e4-4029-93e4-XXXXXXXXXXXX",
  "uti": "tL2-eu4OB0KFhXGl7j4UAA",
  "ver": "2.0"
}

		

The end-to-end flow

So I’ve authenticated my user to the application using OIDC and gained delegated access to the Microsoft Graph API via OAuth all using Entra. Not too shabby. This is the most basic of basic use cases. In my next post I’ll walk you through how to add group information to the id or access token which you could use within your application to authorize the user within the application.

I’m a big fan of old school style protocol flow diagrams, so I threw one together that walks through the end-to-end process I’ve outlined today.

Summing It Up

Yeah, I know that was a lot. If all you take out of this post is a better understanding of what app registrations and service principals do and have a general understanding of how they’re structured, and what the protocol flow looks like when using Entra ID for OIDC/OAuth, that’s a win.

If you want to muck around with this stuff yourself in a personal or test tenant, I’ve published all the code I put together to run through these posts in this repository. It’s a work in progress which I’m fine-tuning as I write these posts but it does have the sample frontend app included in it if you want to take a glance at my application-level code and perhaps want to replicate what I walked through today. Please do not use any of this code in a production app. This is purely intended to demonstrate the concepts.

Some key takeaways for you:

Every app registration should have an owner. Just be aware the owner can modify the app registration so don’t go nuts and give this to a non-privileged user.
Set the servericeManagementReference property to some type of BU-level distribution list. This will cover you in case the owners are wiped out through someone accidentally removing them or them leaving the company.
Make sure you’re using the correct methods in the MSAL library if your goal is to use PKCE to align with OAuth 2.1.
If you setup an app registration, be a good human being and document the permissions the app is going to require.
When configuring an app registration that will be a confidential client, try to use a federated identity credential. If your app is running in Azure, you can use a managed identity. This will both be more secure and make your app owner’s life a little less miserable having to rotate credentials.

See you next post!

Entra ID – Deep Dive – Protocol Primer – Part 2

Posted on June 12, 2026 by mattfeltonma

This is part of my series on Microsoft Entra ID:

Welcome back folks. Today I’ll be continuing my deep dive series into Entra. In my last post I went over the basics of Entra ID covering what it is at a high level and how it handles human and non-human identities. One of the features of Entra ID that I highlighted in that post was that it provides authentication services. It is capable of providing authentication of a human or non-human through older protocols like Kerberos (don’t get me started on this feature or else I’ll spend the whole post ranting) and LDAP (through Entra ID Domain Services, another service I hate), but also more modern protocols such as SAML and OIDC (OpenID Connect). Before I dive into Microsoft’s implementation of OIDC and the protocol it’s built on top of, OAuth, I figured it was a good time to do a light protocol primer (primarily for my own benefit because I can only re-read the RFC so many times before it stops being fun. Yeah I find it fun to read a good RFC, so what?).

What is OAuth?

You are probably thinking, “Why the hell are we talking about OAuth?” We need to talk about OAuth (Open Authorization) because OIDC is built on top of the OAuth protocol. If you have a basic understanding of OAuth, then OIDC makes a lot more sense. I’m not going to try to make you an expert, because to make you an expert I’d need to expert which I am very far from. Instead, I’m going to give you the basics. If you want a better/smarter explanation, start with the RFC(s) and then take a read through Vittorio Bertocci’s (an absolute legend, RIP) many articles, ebook, and videos online.

There are a lot of misconceptions out there where folks will talk about OAuth authentication, which is not a real thing. OAuth itself exists as an authorization protocol to provide a framework (lots of SHOULDs/COULDs and not a ton of MUSTs in that RFC) for how applications can get limited access to a user’s data based around the user’s consent using delegation.

The protocol refers to this limited access as a scope. The assignment of a specific scope to an application gives you the ability to do delegation vs impersonation. In the latter, the application will typically act as you with your full permission set vs with delegation you grant consent for the application to access a subset of your data with a more restricted set of permissions. A good example would be delegating the application the read permission over your email vs the reading, writing new emails, and deleting child emails impersonation might give the application.

When it comes to the whole process of a user delegating a scope of access to an application, a number of different roles are involved. These roles include:

Client
Resource Owner
Authorization Server
Resource Server

The client is an application that needs to access some data. Within the protocol it’s important to divide applications into a few different buckets, because the protocol supports them in different ways as I’ll cover in a bit. The standard breaks them into three buckets: web applications, browser-based applications, and native applications. I’m going to keep it simple and consolidate those three buckets into two which will be web applications and non-web applications.

Clients can be either public clients (non-web apps) or confidential clients (web apps). Confidential clients have some type of credential they use to authenticate themselves to the authorization server where as public clients do not (because their code runs on the user’s machine so there is no way to secure the credential). Clients must register with the authorization server either through dynamic registration (which Entra ID does not support today) or through some other type of process. Registration, at a minimum, will include providing the authorization server with a redirectUri, which grant types it will use, and whether it’s a public or confidential client. The client is then issued a unique identifier called a client_id and optionally a client_secret if a confidential client. We’ll see an example of how Entra does it later on this series. Examples of clients could be applications you develop, third-party applications you integrate with, or Microsoft-native applications like Microsoft Teams.

The resource owner is the user or organization that owns the data the client wants to access and is the entity that is capable of granting access to that data through a consent process. Consent is a major focus in OAuth since it relies on delegation of a specific scope of access to the data. Consent is the process of the resource owner approving that delegation. Resource owners in the Entra ID world are going the enterprise at the top layer, business units underneath that layer, and finally its employees which are represented by user objects in Entra. Consent will either be granted for all users within the tenant by an administrator or by individual users to data they have permissions over.

The authorization server is the role that glues all other roles together. This is the server authenticates the user (OAuth doesn’t care how), gets the user’s consent for the client to access the data, and issues an access token to the client. Entra ID fulfills this role in the Microsoft cloud world.

The resource server hosts the resource owner’s data. It will consume the access token obtained by the client from the authorization server and allow or deny access to the data. Resource servers in the Microsoft world could be your custom built application or the Microsoft Graph API.

The RFC has a basic diagram which does a good job explaining the flow at a high level.

You’ll notice the the term authorization grant in the above image. An authorization grant represents the resource owner’s authorization (delegation) of a specific scope of access to their data and is used by the client to get an access token which the resource server consumes and approves/denies access. In the base specification for OAuth 2.1, there are three types of grants (there are a ton of extension grants, some of which we’ll cover in this series) which include the authorization code grant, the refresh token grant, and the client credentials grant.

Before I describe the grant types, it’s worth calling out that I’m going to be talking specifically about OAuth 2.1 (which is still a draft RFC right now). OAuth 2.1 seeks to address a lot of the security issues with OAuth 2.0. In OAuth 2.0 there were a bunch more grant types including resource owner credentials flow and the implicit flow there are somewhat of security nightmares. OAuth 2.1 removes those grant types and the official spec sticks to the three I described above while adding an additional requirement for PKCE (Proof-Key for Code Exchange) for both public AND confidential clients. PKCE helps to address authorization code interception attacks. This Okta article does a great job describing the security benefit brings. I’ll demonstrate this with MSAL in a later post. Now back to the authorization grant types.

The authorization code grant type involves sending the resource owner to the authorization server to authenticate and consent to the client’s access of their data, returning an authorization code to the client, and the client exchanging that with the authorization server for an access token. This is going to be your go to grant type any delegation use case. An example of this would be an application accessing my data in a storage account that belongs to me.

Next up is the client credentials flow grant type. In this flow there is no user consent because the data the client is trying to access is under its control. Essentially, the client uses its own identity context to access the data because it’s already been authorized to do so. An example here would be an application pulling Entra ID sign-in logs from the MS Graph API.

Lastly, we have the refresh token grant. This grant type is used by the client to exchange a refresh token for a fresh access token. Access tokens must be short lived (typically around an hour). Instead of having the resource owner go through the whole authentication and consent process again, the client can exchange its longer living refresh token (if it requested one) for a new access token of the same or lesser scope.

In addition to grant types above there are extension grant types. The one that will be relevant to this series is the jwt bearer type, or more formally the JSON Web Token (JWT) profile. In the Microsoft world, you’ll see this referred to as the on-behalf-of flow. This is the flow that Microsoft will use for any multi-hop OAuth. There is also another newer grant type to be aware of which is the token exchange flow. This has a similar use case as the jwt bearer flow for multi-hop OAuth but isn’t limited to JWTs and provides additional information in the access token which can be very helpful in identifying client (actor) vs the resource owner (subject) in the access token. Entra doesn’t support this flow to my understanding, so you’ll be using jwt-bearer instead for multi-hop flows as we’ll see in a future post.

In an authorization request will look something like the below:

			
GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
    &code_challenge=6fdkQaPm51l13DSukcAH3Mdx7_ntecHYd1vi3n0hMZY
    &code_challenge_method=S256&scope=User.Read HTTP/1.1
Host: server.example.com

		

In the above example we see the client is requesting the authorization code grant type, is specifying its client id and its redirect_uri (which were established during client registration), a code challenge (for PKCE), and the scope of access it is requesting.

Access tokens come in a few flavors which you can read about in the RFC. The most common type of token is a bearer token. The bearer token is exactly what it sounds like, whoever bears the token holds the power! Bearer tokens are typically JWTs (JSON Web Tokens). While RFC doesn’t specifically require the access token to be cryptographically signed, the ones that Entra ID issues are. The public key used to verify the signature can be obtained for Entra ID from a public metadata endpoint we’ll see later.

Here is a sample access token issued by Entra:

			
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "ABC123XYZ789KeyIdentifier"
}
{
  "aud": "api://backend-app-client-id",
  "iss": "https://login.microsoftonline.com/tenant-id/v2.0",
  "iat": 1780963927,
  "nbf": 1780963927,
  "exp": 1780968246,
  "aio": "AaQAW/8cAAAA...sessionData...",
  "azp": "frontend-app-client-id",
  "azpacr": "1",
  "name": "John Doe",
  "oid": "user-object-id-guid",
  "preferred_username": "john.doe@example.com",
  "rh": "1.AbcA...refreshTokenHash...",
  "scp": "user_impersonation",
  "sid": "session-id-guid",
  "sub": "subject-claim-unique-identifier",
  "tid": "tenant-id-guid",
  "uti": "unique-token-identifier",
  "ver": "2.0",
  "xms_ftd": "xEyJj...federationMetadata..."
}

		

There are a few important endpoints the client needs to know about for the authorization server. This includes the authorization endpoint (where the resource owner is sent to authenticate and consent) and the token endpoint (where the client obtains an access token). These can be retrieved via a metadata endpoint. This is how Entra ID does it as we’ll see in a future post.

Ok, with that you should now have a high level understanding of OAuth and be aware of its role as an authorization protocol. Key in on that word, authorization. When I perform an OAuth flow I get an access token back to my app that I can use to access a resource owner’s data, but I would still need to authenticate the user to my application and get some basic profile information via another means. In comes OIDC.

What is OpenID Connect?

Like the prior section, my goal is give you a primer. If you want the gory details, take a read through the specification (another tolerable if not enjoyable read). Microsoft and Auth0 have solid one pagers if reading specifications isn’t your style.

The OIDC protocol is built on top of the OAuth (Open Authorization) protocol to provide an identity layer and authentication layer. It gives us the means get some assurance that the user is who they say they are and get some basic information about the user.

Within the OpenID protocol there are three roles that exist. These include:

End User
RP (Relying Party)
OP (OpenID Provider)

Since the protocol is built on top of the OAuth protocol, these roles will map nicely to the OAuth roles as we’ll see.

We first have the end user. The end user is the human participant that will be access our application. They are very often also the resource owner for any data we may want to access about them as we’ll see later.

Next, we have the RP. The RP is the application that is requesting end user authentication and claims (or data/attributes) about the user. This will be an OAuth client application.

Finally we have the OP. The OP is the server capable of authenticating the user and providing claims about the user’s identity. This role is fulfilled by the OAuth authorization server in all (I don’t believe their are exceptions, but feel free to correct me) instances.

The OP will issue a security token referred to as an id token with claims about the authentication of the end user, including claims about the user.

This is another instance where the specification did a great job with a high level flow diagram.

The structure of the authentication request is almost identical to the structure of an authorization request in OAuth.

			
GET /authorize?response_type=code&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&scope=User.Read+openid+profile
&state=random-state-value
&nonce=random-nonce-value  
&code_challenge=IFrWuREBBR_QJ39q5Ts4
&code_challenge_method=S256

		

Notice above that we have an added state and nonce. The state helps to provide CSRF (cross-site request forgery) attacks, such as fooling the victim into accessing an attacker’s account to get them to upload data or perhaps purchase things for the attacker’s account. The nonce helps to mitigate id token replay attacks (app validates the nonce in the id token matches what it expects for the user’s session). Now the major things to pay attention to is the additional scopes. Here we see the openid and profile scopes. The openid scope tells the OP the client is looking for an id token. The profile scope is an optional scope which tells the OP to include additional claims in the id token such as the user’s name, preferred_username, and the like.

Once the RP (client / application) exchanges its authorization code (think authorization code grant) to the OP/authorization server, it returns back the an OIDC id token in addition to the OAuth access token. The application can then use the claims in the id token to identify the user, get information into how the user authenticated, get group information, and anything else you can stuff into the claims. It gives the application context about the user.

Below is an example id token’s payload. ID tokens follow the JWT standard and are cryptographically signed by a private key held by the OP. Clients will need to verify the signature using the OPs public key which is usually published in the OIDC discovery endpoint which looks something like this https://{issuer}/.well-known/openid-configuration. We’ll see an example when we break down Entra’s implementation.

			
{
  "iss": "http://exmaple.com.com",
  "sub": "123456",
  "aud": "myclientid",
  "exp": 1311281970,
  "iat": 1311280970,
  "name": "Homer Simpson",
  "given_name": "Homer",
  "family_name": "Simpson",
  "gender": "male",
  "birthdate": "2025-10-31",
  "email": "homersimpson@example.com",
  "picture": "http://example.com/homersimpson/me.jpg"
}

		

Your takeaways

At this point you should have a reasonably decent high level understanding of OAuth/OIDC. If you are already an “expert” you likely snorted milk through you nose reading my shitty explanation. What I mainly want you to take away from this is that OAuth is an authorization protocol with OIDC providing an authentication layer nicely on top. I like to think of OAuth as the cake with OIDC as the frosting. That top layer doesn’t work without the bottom layer (you freaks that eat the frosting right out of the can shall remain silent) and the bottom layer is enriched by the frosting on top. It’s 7PM and I’m craving a sweet, lay off.

In my next post I’ll walk through building out the required components in Entra ID for the frontend application. You’ll read and recognize properties that translate directly back to these two protocols. Other properties may not have the same name, but you’ll understand why they exist.

Alright, my brain is fried. Enjoy the weekend!

Entra ID – Deep Dive – The Basics – Part 1

Posted on June 9, 2026 by mattfeltonma

This is part of my series on Microsoft Entra ID:

Yeah… You read that right. I’m finally biting the bullet and doing a series on Entra ID. There are some cobwebs there, but once upon a time I was a half-baked “identity guy”. Nah, I’m not returning to that place, but I have had to visit it more frequently over the past few months. With the growing use of agents, identity has one again become of those things that apparently everyone is a so called “expert in”. I aint no expert, but I have been digging into the chatter around the implications of agents into the identity world. Given my employer, that has been spending some time in the Entra ID Agent Identity space.

Digging into that demanded I go back to some of the basics of Entra ID such as the purpose of an application registration versus a service principal and the request flow when authenticating a user to an application using OIDC (OpenID Connect) or executing an on-behalf-of flow in OAuth. I had conceptual knowledge of the above, but it was too ivory tower. I needed to eat the dog food and do it. After spending a few weeks reading through the documentation, reviewing captured requests and responses, reviewing RFCs, and poorly coding some applications to exercise on the concepts I figured it was time to brain dump what I learned before I get distracted with some new shiny widget and forget 60% of it.

So yeah… that’s where this series is coming from. Hopefully some folks out there draw some value out of it beyond serving as a refresher for my neural pathways.

With that rambling out of the way, let’s get to it.

WTF is Entra ID?

Many years ago when Microsoft first introduced Azure Active Directory my peers and I scratched our heads with this question. Given the name, the initial assumption was it was the Windows Active Directory “killer” (stop trying to make that happen, it aint gonna happen). That seems to have been a pretty common assumption given what I’ve heard from customers over the years as I sat in the vendor space and is likely why the name was shifted a few years back to Entra ID. Either that or marketing needed to justify their existence with another product rename.

If you want the professional explanation as to what Entra ID is you can read the public documentation and bask in the marketing mumbo jumbo. Since you’re here, you’re going to get the less fancy and quick and dirty Matt Felton explanation. My take is that Entra ID does a lot of shit, but at its core it is:

An identity store for the identities of human and non-human security principals, their attributes, and their credentials.
An authentication service which can act as an OAuth Authorization Server, OIDC identity provider, SAML IdP / SP, and even Kerberos / LDAP provider (gross)

It provides these core services to Microsoft’s cloud services such as M365, Azure, Dynamics 365, and whatever other clouds Microsoft has that I’m missing. It can be extended to provide these services to other applications by integrating with it via one of the supported protocols like we’ll see in further posts in this series.

Entra ID is divided into separate tenants which represent unique identity boundaries. Services for a given customer (such as an Azure subscription) are associated to an Entra ID tenant which acts as the identity boundary for those resources. Tenants can trust other tenants to facilitate cross tenant accessing of resources through features like Entra ID External ID.

The identity store piece of the Entra ID service is where users, groups, many types of service principals, applications, and device identities are stored. Similar to an LDAP (hell may be LDAP under the hood, who the hell knows) each of these objects has a schema with specific properties that are consumed for the other services Entra provides (as we’ll see later).

That should be enough context to give you a very general idea of what Entra ID is. Like I mentioned above, it does a lot of shit (conditional access, privileged identity management, etc) that isn’t relevant to the point of this series and that I’m not going to discuss. If you can hammer it in your head those two core functions, it will be enough to get you through this series.

Humans vs Non-Humans

Within Entra ID we have two primary objects that represent humans and non-humans. For humans we have the user identity. For non-humans we have service principals. Service principals come in many flavors including the base service principal (consider legacy), applications, managed identities, Agent Identity Blueprints, and Agent Identities (likely others I’m missing), Agent Users. The way I like to think about the many types of service principals (probably incorrect but I don’t care) is that the base service principal is the parent object class and things like managed identities, agent identity blueprints, and agent identities are children of that object class which look a bit different. Agent Users are a bit weird and I haven’t delved into them much, however, I like to think of it as a child of the base user object class.

The other object type that’s important to understand is the application object (typically referred to as the app registration). The application object is interesting (and can be confusing). It exists to represent a globally unique representation of an application. For a given application, you only ever have a single application object which exists in the tenant it was registered. What’s helped me is to think of the application object as the OAuth client registration. That’s probably not completely correct, but it helps ground you in its purpose. The application object can have a credential (secret, certificate, federated) which allows it to authenticate to Entra ID (think OAuth confidential client). It also contains information critical to OAuth such as the client id (appid), the audience (identifierUris), the OAuth scopes it supports (oauth2PermissionScopes), and redirectUris (when using interactive OAuth flows).

Below you’ll see an example of an application object for an application that is acting as a backend API to the demo solution I put together for this series.

			
Application Demo backend app for Entra authentication already exists and its id is 23f7d0f0-85e6-453a-b0bb-723b65ac7958
{
  "id": "23f7d0f0-85e6-453a-b0bb-723b65ac7958",
  "deletedDateTime": null,
  "appId": "22d2ff53-9442-404c-8da5-01c2e135532d",
  "applicationTemplateId": null,
  "disabledByMicrosoftStatus": null,
  "createdByAppId": "04b07795-8ddb-461a-bbee-02f9e1bf7b46",
  "createdDateTime": "2026-06-08T23:46:22Z",
  "displayName": "Demo backend app for Entra authentication",
  "description": "This app is used to demonstrate a backend API that uses the user's identity context to fetch a user's story'",
  "groupMembershipClaims": null,
  "identifierUris": [
    "api://22d2ff53-9442-404c-8da5-01c2e135532d"
  ],
  "isDeviceOnlyAuthSupported": null,
  "isDisabled": null,
  "isFallbackPublicClient": false,
  "nativeAuthenticationApisEnabled": null,
  "notes": null,
  "publisherDomain": "XXXXXXXX.onmicrosoft.com",
  "serviceManagementReference": null,
  "signInAudience": "AzureADMultipleOrgs",
  "tags": [],
  "tokenEncryptionKeyId": null,
  "uniqueName": null,
  "samlMetadataUrl": null,
  "defaultRedirectUri": null,
  "certification": null,
  "optionalClaims": null,
  "servicePrincipalLockConfiguration": null,
  "requestSignatureVerification": null,
  "addIns": [],
  "api": {
    "acceptMappedClaims": null,
    "knownClientApplications": [],
    "requestedAccessTokenVersion": 2,
    "oauth2PermissionScopes": [
      {
        "adminConsentDescription": "Allow the application to impersonate the signed-in user to access their user story.",
        "adminConsentDisplayName": "Impersonate user",
        "id": "00000000-0000-0000-0000-000000000001",
        "isEnabled": true,
        "type": "User",
        "userConsentDescription": "Allow the application to impersonate you to access your user story.",
        "userConsentDisplayName": "Impersonate user",
        "value": "user_impersonation"
      }
    ],
    "preAuthorizedApplications": []
  },
  "appRoles": [],
  "info": {
    "logoUrl": null,
    "marketingUrl": null,
    "privacyStatementUrl": null,
    "supportUrl": null,
    "termsOfServiceUrl": null
  },
  "keyCredentials": [],
  "parentalControlSettings": {
    "countriesBlockedForMinors": [],
    "legalAgeGroupRule": "Allow"
  },
  "passwordCredentials": [
    {
      "customKeyIdentifier": null,
      "displayName": null,
      "endDateTime": "2028-06-08T23:46:45.7547438Z",
      "hint": "NnW",
      "keyId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX",
      "secretText": null,
      "startDateTime": "2026-06-08T23:46:45.7547438Z"
    }
  ],
  "publicClient": {
    "redirectUris": []
  },
  "requiredResourceAccess": [
    {
      "resourceAppId": "e406a681-f3d4-42a8-90b6-c2b029497af1",
      "resourceAccess": [
        {
          "id": "03e0da56-190b-40ad-a80c-ea378c433f7f",
          "type": "Scope"
        }
      ]
    }
  ],
  "verifiedPublisher": {
    "displayName": null,
    "verifiedPublisherId": null,
    "addedDateTime": null
  },
  "web": {
    "homePageUrl": null,
    "logoutUrl": null,
    "redirectUris": [],
    "implicitGrantSettings": {
      "enableAccessTokenIssuance": false,
      "enableIdTokenIssuance": false
    },
    "redirectUriSettings": []
  },
  "spa": {
    "redirectUris": []
  }
}

		

Now comes the importance of the service principal. An application object will typically have an associated service principal (not much use without it) which acts as the security principal for the application in the given Entra ID tenant. Applications have one application object (or app registration) but many service principals (if it’s multi-tenant). Think of the service principal as the “stub” identity representing the application in the Entra ID tenant. Permissions are granted to the service principal and the application uses the service principal to exercise those permissions to do things such as querying the Microsoft Graph API.

If you build a multi-tenant application like I’ve done here, other Entra ID tenants can create a service principal for the application in their tenant allowing the application to possibly authenticate those users and access resources in that Entra ID tenant.

The official documentation likes to refer to the application object as the template for the application and the service principal as the security principal. I think that’s a pretty damn good single sentence explanation.

Below is an example of the service principal for the frontend application I built for this series. You can see the type of service principal (servicePrincipalType) in this scenario is application because this service principal has an associated application object (app registration).

			
{
  "id": "ece073e5-744e-4d70-b79d-4887e1dd008f",
  "deletedDateTime": null,
  "accountEnabled": true,
  "alternativeNames": [],
  "appDisplayName": "Demo frontend app for Entra authentication",
  "appDescription": "This app is used to demonstrate a frontend application where a user authenticates using Entra ID authentication via OIDC",
  "appId": "afbd7539-a21f-4d11-93a3-490017032fb7",
  "applicationTemplateId": null,
  "appOwnerOrganizationId": "6c80de31-d5e4-4029-93e4-5a2b3c0e1299",
  "appRoleAssignmentRequired": false,
  "createdByAppId": "04b07795-8ddb-461a-bbee-02f9e1bf7b46",
  "createdDateTime": "2026-06-08T23:45:54Z",
  "description": null,
  "disabledByMicrosoftStatus": null,
  "displayName": "Demo frontend app for Entra authentication",
  "homepage": null,
  "isDisabled": null,
  "loginUrl": null,
  "logoutUrl": null,
  "notes": null,
  "notificationEmailAddresses": [],
  "preferredSingleSignOnMode": null,
  "preferredTokenSigningKeyThumbprint": null,
  "replyUrls": [
    "http://localhost:8100/callback"
  ],
  "servicePrincipalNames": [
    "afbd7539-a21f-4d11-93a3-490017032fb7"
  ],
  "servicePrincipalType": "Application",
  "signInAudience": "AzureADMultipleOrgs",
  "tags": [],
  "tokenEncryptionKeyId": null,
  "samlSingleSignOnSettings": null,
  "addIns": [],
  "appRoles": [],
  "info": {
    "logoUrl": null,
    "marketingUrl": null,
    "privacyStatementUrl": null,
    "supportUrl": null,
    "termsOfServiceUrl": null
  },
  "keyCredentials": [],
  "oauth2PermissionScopes": [],
  "passwordCredentials": [],
  "resourceSpecificApplicationPermissions": [],
  "verifiedPublisher": {
    "displayName": null,
    "verifiedPublisherId": null,
    "addedDateTime": null
  }
}

		

What are we going to build?

Now that you have the bare bones basics of Entra, you likely want to understand how an application would go about using it for authentication and authorization. While you might not be doing this now and it may not seem relevant, it will become very relevant to you if you begin building agents in Microsoft’s clouds through Microsoft Foundry, CoPilot Studio, or the 18 other random services Microsoft allows agents to be built. This will also be relevant to you if you’re going to consume Microsoft resources (such as Azure) from other clouds through an application or an agent. So yeah, you should understand what this looks like to do. The whole Entra ID Agent Identity feature builds on these foundational pieces.

To see these concepts in action I’m going to walk through a very simplistic solution with a frontend website and backend API in Python. The frontend website is built using the Flask Framework and the backend API is built with fastapi.

The frontend website will use Entra ID to authenticate the user and will be issued an OIDC id token to identify the user. The frontend will get some information from the user from the id token and access token it receives from Entra and will make additional calls to the Microsoft Graph API using the client credentials flow to grab other attributes of the user’s identity. I’ll also show how to include the user’s Entra ID group information in the id or access token and how to handle nested group membership.

The frontend will have a link on it to call the /story endpoint of the backend API. The story endpoint will pull a pre-built AI generated story about the user which has been uploaded toblob storage in an Azure Storage Account. The backend API will use the on-behalf-of flow to access the storage account as the user to pull the user’s specific story.

This will demonstrate some of the most common flows including authentication, OAuth client credentials flow, and OAuth on-behalf-of (or jwt bearer). I’ll show you how the id tokens and access tokens look in different scenarios pointing out the relevant claims and how they’re used upstream. I’ll even share some process flows so you understand what does what in a given flow.

My primary goal here is give you the basics so you can walk away with a more solid understanding of what’s happening under the hood and how Entra ID has decided to implement OIDC and OAuth. I can’t stress how helpful this will be for you once you start diving into the agent identity space (which I’ll be covering after this series).

Summing it up

Ok, so you know what you’re in for. This series is gonna be relatively deep in the weeds so bring your favorite caffeinated beverage for future posts. I’m doing everything direct with the REST APIs because I want to show you the gory details. No pretty SDKs for you. If you’ve had a “conceptual” idea of how this works without the implementation specifics (like I did before I went down this rabbit hole) this series should help to fill those gaps.

In the next post I’ll walk through setting up Entra for the frontend website, authenticating a user, and exploring the id token and access token. The post following that will walk through using the application’s identity context to get more information about the user from the Microsoft Graph API such as nested group membership, then I’ll finish up the series by walking through the on-behalf-of flow with the backend API to show you how to carry the user’s identity context through the application to the destination resource down the line.

See you next post!

Microsoft Foundry – Publishing Agents To Teams Deep Dive – Part 2

Posted on May 22, 2026 by mattfeltonma

This is part of my series on Microsoft Foundry:

With Memorial Day weekend coming quickly, I wanted to get the second post to this series out before the knowledge my late nights with Red Eye coffee brought leaks from my brain. In my last post I did a walkthrough of the Publishing Agents To Teams feature of the Foundry Agent Service within Microsoft Foundry. In that post I covered the Portal experience, broke open some of the black box as to my understanding of the workflow that happens underneath when you push the publish button, and talked through the AI Bot Service’s role in the feature. For this post I’m going to cover a possible network architecture to support this feature when security controls are required around inbound and outbound network access (I mentioned a few last post), the network flow for that architecture, and some of the switches and knobs you can turn to add additional security beyond the basic layer 4 network controls. After that, I’m going to walk through a Jupyter Notebook I put together than shows you how to perform the steps behind the publish button programmatically. If you haven’t read my last post, Graeme’s blog post on this topic, and Moim’s blog post on reverse engineering Bot services you should do that before you try to tackle this one.

A Possible Architecture

As I covered in my last post, when we want to make an agent available in Teams we need Teams to be capable of reaching it. In this design, with Teams interacting with the AI Bot Service which relays the information to our agent, this means we need to make the agent’s messaging endpoint available to the Microsoft public backbone (i.e. it needs to be exposed via a public IP address). Graeme provided one architecture to accomplish this which will work for a number of folks. I foresee a few different architectural options:

APIM v2 configured for public inbound and regional vnet integration
APIM classic configured for external mode
App Gateway with a public listener with APIM v2 VNet Injected or PE + regional vnet integration behind it
App Gateway with a public listener with APIM classic VNet injection behind it
Firewall DNAT + APIM v2 VNet Injected or PE + regional vnet integration behind it
Firewall DNAT + APIM classic VNet injection behind it

For this post I’m going to focus on the 3rd option which has Application Gateway sitting in front of an v2 tier API Management. I like this pattern because I get the WAF, SNI, host-based routing, and path-based routing benefits of an App Gw (Application Gateway) and avoid slapping a public IP on my APIM (API Management). There is more complexity to this pattern, but more security and flexibility always comes with more complexity, right?

Generally my traffic will look something like the image you seen down below.

The green line is the incoming message from the Microsoft Teams. We see it is relayed from the Teams Service to the public IP address of the AppGw via the Bot Service. From there, we send it through the APIM and finally on to the Private Endpoint for Foundry which tunnels it on to the Microsoft-managed compute behind the Foundry Agent Service.

The blue line is the response from the agent. You’ll notice there are two blue lines. Based on the logs in my firewall when I tested this, I did not see the response traffic back to the Bot Service (this would be the endpoint in the serviceurl in the JWT received from the Bot Service which should be something like smba.trafficmanager.net). I’m making the assumption that this traffic isn’t egressed through the customer virtual network and instead flows out whatever path Microsoft is providing in the network where the managed compute lives that hosts the agent runtimes. Additionally, you’ll notice a blue line flowing through my virtual network and headed to an FQDN at tenant.api.powerplatform.com. I’m still trying to get clarification on if this flow is truly required and what it’s for.

The first instinct of us old networking farts is to look at this diagram and think this is asymmetric routing. However, in this situation it isn’t because the green and blue flows are separate TCP sessions because the message and response sequence is asynchronous.

Execution of the Architecture

Alright, you now have an understanding of the flow with this architecture. Let’s talk about the cool shit we can do with it. I’ve set the messaging endpoint in my Bot Service resource to https://agent.agw.jogcloud.com/agents/api/projects/sampleproject1/agents/test-manual-publish/endpoint/protocols/activityProtocol?api-version=2025-05-15-preview. What I’ve done is replace my FQDN with my AppGw’s FQDN and I appended /agents after the FQDN to ensure it routes to the proper API on my APIM.

Given we’re starting with AppGw we can use the WAF functionality to validate the source IP address is coming from the Teams service. A simple rule like the below will do that check.

Next, I want to validate the request header of x-ms-tenant-id to validate that the header is present and contains my tenant id.

Next up I have APIM. Here I’ve created an API with an operation named PublishedAgent. The operation is defined as you see below.

Within the operation, I’ve taken Graeme’s policy and made a small tweak to it to validate the serviceurl claim in the JWT and ensure it contains my tenant id.

			
<policies>
    <inbound>
        <base />
        <validate-jwt header-name="Authorization" require-scheme="Bearer">
            <openid-config url="https://login.botframework.com/v1/.well-known/openidconfiguration" />
            <audiences>
                <audience>8fd8ec07-ae24-4038-8771-6d4b85a4b19a</audience>
            </audiences>
            <issuers>
                <issuer>https://api.botframework.com</issuer>
            </issuers>
            <required-claims>
                <claim name="serviceurl" match="all">
                    <value>https://smba.trafficmanager.net/amer/6c80de31-d5e4-4029-93e4-5a2b3c0e1299/</value>
                </claim>
            </required-claims>
        </validate-jwt>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

		

If we bring it back up out of the weeds and to the high level, here is what we’re doing at each component in the flow.

So there you have it folks, that’s an architecture you could use and some of the details of getting it up and running. Now let’s bounce over and take a look at how to avoid the manual action of “pushing the pretty blue button” and look at how we’d publish a Foundry Agent programmatically.

Programmatic Setup

The kind folks over at the Foundry Agents PG (product group) put together a sample of the steps needed to do this programmatically with PowerShell and Bicep. Since I prefer good ole bash shell, Python, and Terraform I reworked their steps into a Jupyter Notebook which you can find here. There is a sample env file in the repository. You don’t need to populate the client id and client secret unless you want to play around with the commands in the appendix. Those are not required.

The first step in the process is creation of the Bot Service resource in Azure. As I covered in my last post, this resource mainly exists to store metadata about your bot (or agent in this scenario) that the AI Bot Service uses to relay data back and forth between Teams and the agent. You’ll want to create a new Bot Service which will require you have the specific permissions to do that (if you want to go the custom role) or something more generic like Contributor. You’ll also want to make sure the Bot.Service resource provider is registered in your subscription (pretty sure this requires Owner).

I’ve crafted a Terraform template for this step. Before you can create the Bot Service with the template, you need to collect some Entra ID-related information. First, you’ll need to fetch your Entra ID tenant ID. You can do this programmatically by running after logging into az cli using the command below.

az account show --query tenantId -o tsv

Now that you have you’re logged into az cli and you’ve grabbed the tenant id, your next step is to fetch the principal id (or appId) of the Entra ID Agent Identity associated with the Foundry Agent. You’ll associate this identity with the Bot Service resource. Before you do that, you’ll need to get fetch an access token with the appropriate scope.


from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Get a token for Foundry scope
credential = DefaultAzureCredential()
scopes = ["https://ai.azure.com"]

user_token = credential.get_token(*scopes)

Next you can use this function to grab the principal_id property.

			
import os
import json
import requests
from dotenv import load_dotenv
# Load environmental variables
load_dotenv(override=True)
# Function that gets the agent object
def get_foundry_agent(account_name: str, project_name: str, agent_name: str, token: str):
    """This function retrieves a Foundry agent by name from a Foundry project
    Args:
        account_name (str): The name of the Foundry account
        project_name (str): The name of the Foundry project
        agent_name (str): The name of the Foundry agent to retrieve
        token (str): The authentication token to use for the API request
    Returns:
        dict: The Foundry agent details if found, otherwise None
    """
    response = requests.get(
        f"https://{account_name}.services.ai.azure.com/api/projects/{project_name}/agents/{agent_name}?api-version=v1",
        headers={
            "Content-Type": "application/json", 
            "Authorization": f"Bearer {token}"
        }
    ) 
    if response.status_code == 200:
        return response.json()
    else:
        logging.error(f"Failed to retrieve agent: {response.status_code} - {response.text}")
        return None
# Grab the principal_id of the Entra ID Agent Identity associated with the Foundry Agent  
foundry_account_name = os.getenv("FOUNDRY_ACCOUNT_NAME")
project_name = os.getenv("FOUNDRY_PROJECT_NAME")
agent_name = os.getenv("FOUNDRY_AGENT_NAME")
agent = get_foundry_agent(foundry_account_name, project_name, agent_name, user_token.token)
agent_principal_id = agent.get("instance_identity", {}).get("principal_id")
print(f"Foundry Agent Principal ID: {agent_principal_id}")
print(json.dumps(agent, indent=2))

		

Once you have the tenant id and principal id of the agent identity associated with your Foundry Agent, you are almost ready to create the Bot Service. The last step is formulating your messaging endpoint. It will look something like this:

https://FOUNDRY_ACCOUNT_NAME.services.ai.azure.com/api/projects/PROJECT_NAME/agents/AGENT_NAME/endpoint/protocols/activityProtocol?api-version=2025-05-15-preview

As I showed earlier, you can modify this to change the FQDN to point to your preferred ingress infrastructure and add pathing to the beginning to ensure proper routing through an API Gateway.

Now that you have everything ready to go you can run a Terraform template like the one located here. This will create the Bot Service and Teams channel child object and configure diagnostic settings with delivery to the specified (Log Analytics Workspace).

Once that is complete, you need enable the activity protocol support for your agent. You can do this using the code below:

			
import os
import json
import requests
from dotenv import load_dotenv
# Load environmental variables
load_dotenv(override=True)
# Function that enables the activity protocol for the agent and configures the required Bot Service authorization scheme
def enable_agent_activity_protocol(account_name: str, project_name: str, agent_name: str, token: str):
    """This function enables the activity protocol for a Foundry agent and configures the required Bot Service authorization scheme
    Args:
        account_name (str): The name of the Foundry account
        project_name (str): The name of the Foundry project
        agent_name (str): The name of the Foundry agent to retrieve
        token (str): The authentication token to use for the API request
    Returns:
        dict: The updated Foundry agent details if the update was successful, otherwise None
    """
    # 
    body = {
        "agent_endpoint": {
            "protocols": [
                "responses",
                "activity"
            ],
            "authorization_schemes": [
                {
                    "type": "Entra",
                    "isolation_key_source": {
                        "kind": "Entra"
                    }
                },
                {
                    "type": "BotServiceRbac"
                }
            ]
        }
    }
    response = requests.patch(
        f"https://{account_name}.services.ai.azure.com/api/projects/{project_name}/agents/{agent_name}?api-version=v1",
        headers={
            "Content-Type": "application/merge-patch+json", 
            "Authorization": f"Bearer {token}",
            "Foundry-Features": "AgentEndpoints=V1Preview"
        },
        json=body
    ) 
    if response.status_code == 200:
        return response.json()
    else:
        logging.error(f"Failed to enable agent activity protocol: {response.status_code} - {response.text}")
        return None
# Grab the principal_id of the Entra ID Agent Identity associated with the Foundry Agent  
foundry_account_name = os.getenv("FOUNDRY_ACCOUNT_NAME")
project_name = os.getenv("FOUNDRY_PROJECT_NAME")
agent_name = os.getenv("FOUNDRY_AGENT_NAME")
enabled_agent = enable_agent_activity_protocol(foundry_account_name, project_name, agent_name, user_token.token)
enabled_agent_guid = enabled_agent.get('versions', {}).get("latest", {}).get("agent_guid", {})
print(f"Enabled Agent GUID: {enabled_agent_guid}")
updated_agent_endpoint = enabled_agent.get('agent_endpoint', {})
print(f"Updated Agent Endpoint: {json.dumps(updated_agent_endpoint, indent=2)}")

		

At this point, you have the Bot Service setup and you’ve activated the activity protocol for the agent so its now listening for requests at the messaging endpoint. The last step in the process is to use the publish operation and you will need the Foundry User role for this (as far as I can tell).

What exactly this does is still a bit of a black box for me, but it seems like it’s creating some type of API object to represent the agent in M365 Agent Registry (soon to be rebranded to Agent 365 I’m sure). Some of the APIs I need to poke around with require an Agents 365 license. Once I get that, I’ll update this section with more detail if I find exactly what it’s doing.

import os
import json
import requests
from dotenv import load_dotenv

# Load environmental variables
load_dotenv(override=True)

def publish_agent_teams(
    subscription_id: str,
    resource_group: str,
    account_name: str, 
    project_name: str, 
    location: str,
    agent_name: str, 
    agent_guid: str,
    bot_id: str,
    app_publish_scope: str,
    publish_as_digital_worker: bool,
    app_version: str,
    short_description: str,
    full_description: str,
    developer_name: str,
    developer_website_url: str,
    privacy_url: str,
    terms_of_use_url: str,
    token: str
    ):
    """This function uses the Foundry API to publish a Foundry agent to Microsoft Teams
    Args:
        subscription_id (str): The Azure subscription ID where the Foundry account is provisioned
        resource_group (str): The name of the resource group where the Foundry account is provisioned
        account_name (str): The name of the Foundry account
        project_name (str): The name of the Foundry project
        location (str): The Azure region where the Foundry account is provisioned
        agent_name (str): The name of the Foundry agent to publish
        agent_guid (str): The GUID of the Foundry agent to publish
        bot_id (str): The Microsoft App ID of the Bot registered in Entra ID for this agent
        app_publish_scope (str): The scope to publish the Teams app to, either "Individual" or "Tenant"
        publish_as_digital_worker (bool): Whether to publish the agent as a Digital Worker in Teams, which surfaces it in the Power Virtual Agents app in addition to allowing it to be installed as a standard Teams app
        app_version (str): The version of the Teams app to publish
        short_description (str): A short description of the agent to display in Teams
        full_description (str): A full description of the agent to display in Teams
        developer_name (str): The name of the developer or organization that created the agent, to display in Teams
        developer_website_url (str): The URL for the developer's website, to display in Teams
        privacy_url (str): The URL for the privacy policy for this agent, to display in Teams
        terms_of_use_url (str): The URL for the terms of use for this agent, to display in Teams
        token (str): The Entra ID access token with the scope of https://ai.azure.com/.default to authenticate the API request
    Returns:
        dict: The response from the Foundry API if the publish was successful, otherwise None
    """

    body = {
        "subscriptionId": subscription_id,
        "agentGuid": agent_guid,
        "agentName": agent_name,
        "appRegistrationId": appRegistrationId,
        "botId": bot_id,
        "appPublishScope": app_publish_scope,
        "publishAsDigitalWorker": publish_as_digital_worker,
        "appVersion": app_version,
        "shortDescription": short_description,
        "fullDescription": full_description,
        "developerName": developer_name,
        "developerWebsiteUrl": developer_website_url,
        "privacyUrl": privacy_url,
        "termsOfUseUrl": terms_of_use_url
    }

    response = requests.post(
        url = f"https://{location}.api.azureml.ms/agent-asset/v2.0/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.MachineLearningServices/workspaces/{account_name}@{project_name}@AML/microsoft365/publish",
        headers={
            "Content-Type": "application/json", 
            "Accept": "application/json",
            "Authorization": f"Bearer {token}",
        },
        json=body
    ) 

    if response.status_code == 200:
        print("Agent published successfully! Status code: 200")
    else:
        logging.error(f"Failed to publish agent: {response.status_code} - {response.text}")
        return None

publish_response = publish_agent_teams(
    subscription_id = os.getenv("FOUNDRY_SUBSCRIPTION_ID"),
    resource_group = os.getenv("FOUNDRY_RESOURCE_GROUP"),
    account_name = os.getenv("FOUNDRY_ACCOUNT_NAME"),
    project_name = os.getenv("FOUNDRY_PROJECT_NAME"),
    location = os.getenv("FOUNDRY_LOCATION"),
    agent_name = os.getenv("FOUNDRY_AGENT_NAME"),
    agent_guid = enabled_agent_guid,
    bot_id = enabled_agent_guid,
    app_publish_scope = "Tenant",
    publish_as_digital_worker = False,
    app_version = "1.0.0",
    short_description = "This is a sample agent published from Foundry to Teams",
    full_description = "This agent was created in Foundry and published to Microsoft Teams using the Foundry API.",
    developer_name = "Carl Carlson",
    developer_website_url = "https://www.example.com",
    privacy_url = "https://www.example.com/privacy",
    terms_of_use_url = "https://www.example.com/terms",
    token = user_token.token
)

This step is effectively the last step in the Foundry Portal publishing experience. If you installed it for an individual it will be immediately available for that user. If you publish it to the Teams App Catalog (tenant option) it will be put in a pending state until approved via the M365 Admin Portal.

And like magic, you have a programmatic way to emulate the magical blue button in the Foundry portal. If you’re curious as to what that API call is going to an AML (Azure Machine Learning) endpoint, that is because (today at least) Foundry is built on top of AML.

Summing it up

What I’ve hoped you gathered from here is publishing an agent to Teams isn’t as simple as pushing a button. Requirements needs to be gathered, a design needs to be worked out, services chosen, service properties chosen for security and scale, services load tested, and security controls properly implemented and any risks accepted.

You have a ton of flexibility with this design and my take is there is no optimal design. The optimal design is the one that provides you with the user experience you require aligned with the risks your org is willing to accept. If you’re building an agent that is hitting some public data source, maybe you don’t care about any of this infrastructure. Either way, do not just hit the publish button, group up with your peers across security, networking, operations, collaboration, and AI engineering and put your heads together to come up with a design you’re all happy with.

With that, I’m out for Memorial Day weekend. See you next time!

Journey Of The Geek

The chronicles of a Bostonian tech geek navigating through life and technology

Entra ID – Deep Dive – Entra ID Authentication – Part 3

Creating the frontend application registration

Creating the frontend service principal

Document your required permissions!

Authenticating to the application

The end-to-end flow

Summing It Up

Entra ID – Deep Dive – The Basics – Part 1

WTF is Entra ID?

Humans vs Non-Humans

What are we going to build?

Summing it up