Skip to main content

🏗️ Deep Dive: Understanding Every Concept in Microsoft Entra API Onboarding for .NET Developers


When working with Microsoft Entra (formerly Azure Active Directory), you’ll hear terms like App Registration, Tenant, Client ID, Audience, Scopes, Roles, Tokens, OBO flow, and more. If you’re new, it can feel overwhelming.

This guide breaks down every key term and concept, with definitions, examples, and how they connect when you onboard and consume a new API.

🔹 1. Tenant

  • Definition: A tenant in Entra ID is your organization’s dedicated, isolated instance of Microsoft Entra.
  • Think of it like: Your company’s identity directory.
  • Example: contoso.onmicrosoft.com is a tenant for Contoso Ltd.

🔹 2. App Registration

  • Definition: The process of registering an application in Entra to give it an identity and permission to use Microsoft identity platform.
  • Why needed: Without registration, Entra doesn’t know about your app.
  • What it creates:
    • Application (Client) ID – unique identifier for your app
    • Directory (Tenant) ID – your organization’s ID
  • Types of apps:
    • Web API (backend, receives tokens)
    • Web App / SPA (frontend, requests tokens)
    • Daemon/service (background jobs, uses client credentials)

🔹 3. Client ID

  • Definition: A globally unique GUID assigned to your registered app.
  • Use: Identifies the app when requesting tokens.
  • Example: 12345678-abcd-4321-efgh-9876543210ab.

🔹 4. Tenant ID

  • Definition: Unique GUID representing your organization’s Entra tenant.
  • Use: Used in token endpoints (https://login.microsoftonline.com/{tenantId}).

🔹 5. Instance

  • Definition: The login endpoint base URL for Entra.
  • Example: https://login.microsoftonline.com/

🔹 6. Audience (aud claim)

  • Definition: The intended recipient of the token.
  • In practice: The token must have aud = api://{API_CLIENT_ID} or your custom URI.
  • If mismatch: API rejects the token (401 Unauthorized).

🔹 7. Application ID URI

  • Definition: The unique identifier (URI) that represents your API in Entra.
  • Default: api://{clientId}
  • Custom: https://contoso.com/myapi
  • Use: Appears in tokens as the aud (audience).

🔹 8. Scopes (Delegated Permissions)

  • Definition: A named permission your API exposes that clients can request.
  • Delegated means: “Acting on behalf of a user.”
  • Stored in: scp claim of the token.
  • Example:
    • Scope: access_as_user
    • Token claim: "scp": "access_as_user"
  • Use: API checks that the scope is present before granting access.

🔹 9. Roles (Application Permissions)

  • Definition: Permissions granted to an application itself (not a user).
  • Stored in: roles claim of the token.
  • Use case: Background services, daemons, or APIs calling other APIs without user context.

🔹 10. Delegated Flow (Authorization Code Flow)

  • Definition: User signs in → app gets an authorization code → exchanges for access token.
  • When to use: SPAs, web apps.
  • Result: Token includes scp claim (scopes).

🔹 11. Client Credentials Flow (App-Only)

  • Definition: App authenticates with client ID + secret/certificate.
  • When to use: Background services / daemons.
  • Result: Token includes roles claim.

🔹 12. On-Behalf-Of (OBO) Flow

  • Definition: API A receives a user token → exchanges it for a new token → calls API B.
  • When to use: Multi-tier architecture (frontend → API → downstream API).
  • Token claims: Still delegated (scp present).

🔹 13. Tokens

a) ID Token

  • Purpose: Proves user identity to the client app.
  • Claims: Name, email, oid (object ID).
  • NOT for APIs.

b) Access Token

  • Purpose: Grants access to an API.
  • Claims: aud, scp or roles, expiry.
  • APIs validate this.

c) Refresh Token

  • Purpose: Long-lived; used to get new access tokens silently.
  • Where used: Client apps with long sessions.

🔹 14. MSAL (Microsoft Authentication Library)

  • Definition: Official library to authenticate and acquire tokens.
  • Flavors:
    • MSAL.NET (C#)
    • MSAL.js (JavaScript/React/Angular)
  • Why use: Handles token caching, refresh, OBO, multi-account scenarios.

🔹 15. Microsoft.Identity.Web

  • Definition: ASP.NET Core extension library that simplifies validating JWTs issued by Entra.
  • Features:
    • Easy token validation
    • Scope/role validation helpers
    • Built-in OBO support
  • Example helper:
HttpContext.VerifyUserHasAnyAcceptedScope("access_as_user");

🔹 16. AppSettings.json Config

  • Why: Stores Entra settings.
  • Example:
"AzureAd": {
  "Instance": "https://login.microsoftonline.com/",
  "TenantId": "11111111-2222-3333-4444-555555555555",
  "ClientId": "API_CLIENT_ID",
  "Audience": "api://API_CLIENT_ID"
}

🔹 17. Authentication Middleware

  • Definition: Middleware in ASP.NET Core that validates tokens.
  • Code:
builder.Services.AddAuthentication("Bearer")
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

🔹 18. Authorization Policy

  • Definition: Rules that enforce which scopes/roles are required.
  • Example:
options.AddPolicy("ApiScope", policy =>
    policy.RequireAuthenticatedUser()
          .RequireClaim("scp", "access_as_user"));

🔹 19. Claims

  • Definition: Key-value pairs in a JWT token.
  • Examples:
    • aud → Audience (API identifier)
    • scp → Scopes
    • roles → App roles
    • exp → Expiration

🔹 20. Consent

  • Definition: When a user/admin agrees that a client can call an API with specific scopes.
  • Types:
    • User consent → For delegated scopes, if allowed.
    • Admin consent → Required for app-only permissions.

🛠️ How They Fit Together

Imagine this flow:

  1. Register API → creates identity (API_CLIENT_ID) and exposes scope (access_as_user).
  2. Register Client App → requests that scope.
  3. User signs in (delegated flow) or App authenticates (client credentials).
  4. Token issued by Entra → contains aud, scp or roles.
  5. .NET API middleware validates the token.
  6. Controller enforces authorization with VerifyUserHasAnyAcceptedScope.
  7. If API calls another API → uses OBO flow to get downstream token.

✅ Conclusion

By now, you should understand every key concept in Microsoft Entra API onboarding:

  • Tenant, App registration, Client ID, Tenant ID
  • Scopes vs Roles
  • Access tokens, ID tokens, Refresh tokens
  • Delegated vs App-only flows
  • On-Behalf-Of (OBO) for multi-tier calls
  • Middleware and policies in ASP.NET Core

👉 With this foundation, you can securely expose APIs, register clients, and enforce least-privilege access using Entra ID and .NET.


Comments

Post a Comment

Popular posts from this blog

🗑️ Garbage Collection & Resource Management in .NET (C#) — Beginner Friendly Guide

When you start working with .NET and C#, one of the biggest advantages is that you don’t need to manually manage memory like in C or C++. The Garbage Collector (GC) does most of the work for you. But here’s the catch — not everything is managed automatically. Some resources like files, database connections, sockets, and native memory still need special handling. This blog will help you understand: ✔ How the GC works ✔ What are managed vs unmanaged resources ✔ The difference between Dispose , Finalize , and using ✔ The Dispose pattern with examples ✔ Best practices every C# developer should know 1) How Garbage Collection Works in .NET Managed resources → Normal .NET objects (string, List, etc.). GC frees them automatically. Unmanaged resources → External resources like file handles, database connections, sockets, native memory. GC cannot clean them up — you must do it. 👉 GC uses a Generational Model for performance: Gen 0 : Short-lived objects (local variables, t...
Post a Comment
Read more

☁️ Azure Key vault Short Notes

🟢 What is Azure Key Vault? A cloud service for securely storing and accessing secrets, keys, and certificates . Removes the need to keep secrets (like connection strings, passwords, API keys) inside code or config files. Provides centralized secret management, encryption, and access control . 👉 Think of it like a secure password manager but for your applications. 🟢 Key Features Secrets → store text values (e.g., DB connection string, API key). Keys → store cryptographic keys (RSA, EC) for encryption, signing. Certificates → store/manage SSL/TLS certificates. Access Control → Access Policies (older model). Azure RBAC (modern, preferred). Integration → works with App Service, Functions, AKS, VMs, SQL DB, etc. Logging → audit who accessed secrets via Azure Monitor / Diagnostic Logs. 🟢 Why Use Key Vault? Security → secrets are encrypted with HSM (Hardware Security Modules). Compliance → meet industry standards (PCI-DSS, ISO, GDPR). Automation → aut...
Post a Comment
Read more