Part 2: Applications and Service Principals

The Mystery of Two App Screens

One morning, I needed to update permissions for our payment API. I navigated to the Azure portal and found two seemingly identical sections: "App registrations" and "Enterprise applications." Both showed my app. But changing settings in one didn't always reflect in the other. I spent an embarrassing amount of time clicking between them before finally understanding the relationship.

Let me save you that confusion.

App Registrations vs Enterprise Applications

This is the single most confusing aspect of MS Entra for newcomers. Here's the truth:

App Registrations

What it is: The global definition of your application.

Think of it as: The blueprint, the source code, the master template.

You use this to:

• Configure what your app can do

• Set redirect URIs

• Define API permissions

• Generate client secrets

• Manage API exposure

Enterprise Applications

What it is: The service principal instance in your tenant.

Think of it as: The running instance, the deployment, the object created from the blueprint.

You use this to:

• Assign users and groups

• Configure SSO properties

• Set up conditional access

• Review sign-in logs

• Manage consent

The Relationship

┌──────────────────────────┐
│   App Registration       │  ← You create this first
│   (The Blueprint)        │
│                          │
│  - Client ID             │
│  - Redirect URIs         │
│  - API permissions       │
│  - Client secrets        │
└──────────────────────────┘
            │
            │ Creates automatically
            ↓
┌──────────────────────────┐
│  Enterprise Application  │  ← Entra creates this
│  (Service Principal)     │
│                          │
│  - User assignments      │
│  - SSO configuration     │
│  - Activity logs         │
│  - Consent grants        │
└──────────────────────────┘

When you create an app registration, Entra ID automatically creates a corresponding enterprise application (service principal) in your tenant.

Registering Your First Application

Let me walk you through registering an app—something I've done hundreds of times.

Step 1: Navigate to App Registrations

Azure Portal → Microsoft Entra ID → App registrations → New registration

Step 2: Basic Configuration

Name: Give your app a meaningful name

• Good: payment-api-production

• Bad: my-app-1

Supported account types: Choose based on your scenario

// Option 1: Single tenant (most common for internal apps)
// Only users in YOUR tenant can sign in
"Single tenant (mycompany.onmicrosoft.com only)"

// Option 2: Multi-tenant (for SaaS apps)
// Users from ANY Entra tenant can sign in
"Multitenant (any organizational directory)"

// Option 3: Multi-tenant + personal accounts
// Includes Microsoft personal accounts (Outlook.com, Xbox, etc.)
"Multitenant + personal Microsoft accounts"

// Option 4: Personal accounts only
// Only Microsoft personal accounts
"Personal Microsoft accounts only"

My usage pattern:

• Internal tools: Single tenant

• B2B SaaS: Multi-tenant

• Consumer apps: Multi-tenant + personal accounts

Redirect URI (optional for now): We'll configure this next, but here's a preview:

• Web: https://myapp.com/auth/callback

• SPA: https://myapp.com

• Mobile: msauth://com.mycompany.myapp/auth

Step 3: Review What You Got

After registration, you'll see:

interface AppRegistration {
  applicationId: string;        // Client ID (you'll use this EVERYWHERE)
  displayName: string;          // Your app name
  objectId: string;             // Internal Azure ID
  tenantId: string;             // Your tenant ID
  createdDateTime: string;      // When created
}

// Example:
const myApp = {
  applicationId: "12345678-1234-1234-1234-123456789abc",
  displayName: "payment-api-production",
  objectId: "87654321-4321-4321-4321-cba987654321",
  tenantId: "aaaabbbb-cccc-dddd-eeee-ffff00001111",
  createdDateTime: "2026-02-17T10:30:00Z"
};

Critical: Save your Application (client) ID. You'll need it in every authentication call.

Configuring Your Application

Now let's configure the app properly. This is where I see most mistakes.

Authentication Settings

Navigate to: App registration → Authentication

Platform Configurations

You need to tell Entra ID what type of application you're building:

Web Application:

Platform: Web
Redirect URIs:
  - https://api.mycompany.com/auth/callback
  - https://api.mycompany.com/.auth/login/aad/callback  # For App Service
Implicit grant: ❌ Disabled (use authorization code flow)

Single Page Application (SPA):

Platform: Single-page application
Redirect URIs:
  - https://app.mycompany.com
  - http://localhost:3000  # For local dev
Implicit grant: ✅ ID tokens (for legacy apps, avoid if possible)

Mobile/Desktop:

Platform: Mobile and desktop applications
Redirect URIs:
  - msauth://com.mycompany.myapp/auth  # iOS
  - msauth.com.mycompany.myapp://auth  # Android
  - http://localhost      # For desktop apps

My real configuration example (payment SPA):

// Azure Portal settings for React SPA
{
  platform: "Single-page application",
  redirectUris: [
    "https://pos.mycompany.com",
    "https://pos-staging.mycompany.com",
    "http://localhost:3000",
    "http://localhost:3001"  // Backup port
  ],
  implicitGrant: {
    accessTokens: false,  // Don't use implicit flow
    idTokens: false       // Use auth code flow with PKCE instead
  },
  frontChannelLogoutUrl: "https://pos.mycompany.com/logout"
}

Advanced Settings

Allow public client flows: Enable if your app is a mobile/desktop app

Allow public client flows: ✅ Yes

Supported account types: Can change later if needed

Single tenant → Multi-tenant: ✅ Possible
Multi-tenant → Single tenant: ⚠️ Risky (existing users lose access)

Certificates & Secrets

Navigate to: App registration → Certificates & secrets

This is how your application authenticates itself to Entra ID.

Client Secrets (Password-Based)

Creating a secret:

1. New client secret
2. Description: "Production API key - Expires 2027-02-17"
3. Expiration: 24 months (max)
4. Copy the VALUE immediately (you won't see it again!)

Real example from my API:

// .env file (NEVER commit to git!)
AZURE_TENANT_ID=aaaabbbb-cccc-dddd-eeee-ffff00001111
AZURE_CLIENT_ID=12345678-1234-1234-1234-123456789abc
AZURE_CLIENT_SECRET=abc...xyz  # The secret value

// Using in code
import { ClientSecretCredential } from "@azure/identity";

const credential = new ClientSecretCredential(
  process.env.AZURE_TENANT_ID!,
  process.env.AZURE_CLIENT_ID!,
  process.env.AZURE_CLIENT_SECRET!
);

// Get token for Microsoft Graph
const token = await credential.getToken("https://graph.microsoft.com/.default");

Security best practices:

• ✅ Store in Key Vault or environment variables

• ✅ Rotate before expiration

• ✅ Use separate secrets for dev/staging/prod

• ❌ Never commit to source control

• ❌ Never share in Slack/email

• ❌ Never log the secret value

Certificates (More Secure)

For production, I prefer certificates over secrets:

Creating a certificate:

# Generate self-signed cert (for testing)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Extract public key for Azure
openssl x509 -in cert.pem -out cert.cer

# Upload cert.cer to Azure Portal → App registration → Certificates & secrets

Using certificate in code:

import { ClientCertificateCredential } from "@azure/identity";
import { readFileSync } from "fs";

const certificate = readFileSync("./cert.pem", "utf8");
const privateKey = readFileSync("./key.pem", "utf8");

const credential = new ClientCertificateCredential(
  process.env.AZURE_TENANT_ID!,
  process.env.AZURE_CLIENT_ID!,
  certificate,
  { certificatePrivateKey: privateKey }
);

const token = await credential.getToken("https://graph.microsoft.com/.default");

Why certificates are better:

• Can't be accidentally leaked as easily

• Support automated rotation

• Comply with strict security policies

• Can be stored in HSMs

API Permissions

Navigate to: App registration → API permissions

This defines what your app is allowed to access.

Microsoft Graph Permissions

Let's say my app needs to read user profiles and send emails:

// Azure Portal configuration:
Microsoft Graph permissions:
  - User.Read (Delegated)       // Read signed-in user's profile
  - Mail.Send (Delegated)       // Send email as the user
  - User.Read.All (Application) // Read all users (admin consent required)

Delegated vs Application permissions (we'll cover this deeply in Part 5):

Delegated: Act on behalf of a signed-in user

// User Bob signs in
// App requests Mail.Send permission
// App can send email AS Bob
// Bob's permissions apply

Application: App acts with its own identity

// No user signed in
// App requests User.Read.All permission
// App can read ANY user's profile
// Requires admin consent

Custom API Permissions

If you're protecting your own API, you expose scopes here:

Example: payment-api exposes scopes:

Expose an API:
  Application ID URI: api://payment-api
  
  Scopes:
    - Payments.Read
      Description: "Read payment transactions"
      Admin consent: No
      
    - Payments.Write
      Description: "Create payment transactions"
      Admin consent: No
      
    - Payments.Admin
      Description: "Full admin access to payments"
      Admin consent: Yes

Then frontend app requests these:

API permissions:
  APIs my organization uses → payment-api:
    - Payments.Read (Delegated)
    - Payments.Write (Delegated)

Token Configuration

Navigate to: App registration → Token configuration

Customize what claims appear in tokens.

Optional claims I commonly add:

ID Token:
  - email          // User's email
  - family_name    // Last name
  - given_name     // First name
  - upn            // User Principal Name

Access Token:
  - email
  - groups         // User's group memberships

Example: Adding groups claim:

// After adding 'groups' optional claim, tokens include:
{
  "aud": "12345678-1234-1234-1234-123456789abc",
  "iss": "https://login.microsoftonline.com/{tenant}/v2.0",
  "sub": "user-id...",
  "groups": [
    "aa11bb22-...",  // Finance group
    "cc33dd44-..."   // Support group
  ],
  "email": "[email protected]"
}

// In my API, I check groups:
const financeGroupId = "aa11bb22-...";
if (token.groups?.includes(financeGroupId)) {
  // Grant finance permissions
}

Expose an API

Navigate to: App registration → Expose an API

This is for APIs that other applications will call.

Real example from my payment API:

Step 1: Set Application ID URI

Application ID URI: api://payment-api

Step 2: Define scopes

// Scope 1: Read payments
{
  scopeName: "Payments.Read",
  whoCanConsent: "Admins and users",
  adminConsentDisplayName: "Read payment transactions",
  adminConsentDescription: "Allows the app to read payment transactions",
  userConsentDisplayName: "Access your payment history",
  userConsentDescription: "Allows the app to read your payment transactions",
  state: "Enabled"
}

// Scope 2: Write payments (more sensitive)
{
  scopeName: "Payments.Write",
  whoCanConsent: "Admins only",  // More restrictive
  adminConsentDisplayName: "Create payment transactions",
  adminConsentDescription: "Allows the app to create payment transactions",
  state: "Enabled"
}

Step 3: Authorize client applications

// Allow frontend SPA to call this API without consent prompt
Authorized client applications:
  - Client ID: "frontend-spa-client-id"
    Authorized scopes: 
      - Payments.Read
      - Payments.Write

This pre-authorizes the frontend, so users don't see a consent screen.

Service Principals in Depth

Remember: when you create an app registration, a service principal is automatically created.

Finding Your Service Principal

Option 1: Azure Portal

Microsoft Entra ID → Enterprise applications → 
Filter by Application type "All Applications" → 
Search for your app name

Option 2: Azure CLI

# List service principals
az ad sp list --display-name "payment-api"

# Get details
az ad sp show --id "12345678-1234-1234-1234-123456789abc"

Option 3: Microsoft Graph API

// Using Microsoft Graph SDK
import { Client } from "@microsoft/microsoft-graph-client";

const client = Client.initWithMiddleware({
  authProvider: {
    getAccessToken: async () => {
      return await getToken(); // Your token function
    }
  }
});

const servicePrincipal = await client
  .api(`/servicePrincipals(appId='${clientId}')`)
  .get();

console.log(servicePrincipal);

Service Principal Properties

interface ServicePrincipal {
  id: string;                          // Object ID (different from app ID!)
  appId: string;                       // Application (client) ID
  displayName: string;                 // App name
  servicePrincipalType: string;        // "Application" or "ManagedIdentity"
  accountEnabled: boolean;             // Can authenticate?
  appOwnerOrganizationId: string;      // Tenant where app is registered
  assignmentRequired: boolean;         // Must assign users?
}

// Example:
{
  id: "sp-object-id-guid",
  appId: "12345678-1234-1234-1234-123456789abc",
  displayName: "payment-api-production",
  servicePrincipalType: "Application",
  accountEnabled: true,
  appOwnerOrganizationId: "aaaabbbb-cccc-dddd-eeee-ffff00001111",
  assignmentRequired: false
}

Assigning Users and Groups

By default, all users in your tenant can sign in to your app. Often, you want to restrict this.

Enable assignment requirement:

Enterprise application → Properties → 
Assignment required? ✅ Yes

Then assign users/groups:

Enterprise application → Users and groups → Add user/group

Example from my internal admin tool:

// In Azure Portal:
Assignment required: Yes

Assigned:
  - Admin Group (10 users)
  - John Doe (individual)
  - DevOps Team (5 users)

// Result: Only these 16 people can sign in
// Everyone else gets: "You do not have access to this application"

Service Principal Authentication

Service principals can authenticate using:

1. Client Secret

2. Certificate

3. Federated Identity (for GitHub Actions, Kubernetes)

Client credentials flow (service principal auth):

import { ClientSecretCredential } from "@azure/identity";
import { Client } from "@microsoft/microsoft-graph-client";
import { TokenCredentialAuthenticationProvider } from "@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials";

// Service principal credentials
const credential = new ClientSecretCredential(
  "tenant-id",
  "client-id",
  "client-secret"
);

// Create authenticated Graph client
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["https://graph.microsoft.com/.default"]
});

const client = Client.initWithMiddleware({
  authProvider
});

// Call Graph API as service principal
const users = await client
  .api("/users")
  .top(10)
  .get();

console.log(`Found ${users.value.length} users`);

Multi-Tenant Applications

This is where things get interesting. A multi-tenant app can be used by multiple organizations.

When to Use Multi-Tenant

Use multi-tenant when:

• Building SaaS (Salesforce, GitHub, Slack model)

• App serves multiple customer organizations

• Want customers to sign in with their own corporate accounts

Use single-tenant when:

• Internal company apps

• Apps for a specific organization

• You control all users

Converting to Multi-Tenant

Before (single-tenant):

Supported account types: "Accounts in this organizational directory only"
Sign-in audience: "AzureADMyOrg"

After (multi-tenant):

Supported account types: "Accounts in any organizational directory"
Sign-in audience: "AzureADMultipleOrgs"

Warning: This change affects:

• Token validation (accept tokens from any tenant)

• Consent experience (users from other tenants see consent prompt)

• Service principals (created in each customer's tenant)

Multi-Tenant Authentication Flow

Customer A Tenant                Your Tenant                Customer B Tenant
┌──────────────┐               ┌──────────────┐            ┌──────────────┐
│              │               │ App          │            │              │
│ User Alice   │               │ Registration │            │ User Bob     │
│              │               │              │            │              │
│ Service      │               │ (Multi-      │            │ Service      │
│ Principal A  │               │  tenant)     │            │ Principal B  │
│              │               │              │            │              │
└──────┬───────┘               └──────────────┘            └──────┬───────┘
       │                                                           │
       │ 1. Sign in                                               │ 1. Sign in
       │ [email protected]                                       │ [email protected]
       │                                                           │
       └────────────────┐                         ┌───────────────┘
                        │                         │
                        ↓                         ↓
                   ┌─────────────────────────────┐
                   │    Your SaaS Application    │
                   │                             │
                   │  - Validates tokens from    │
                   │    ANY tenant               │
                   │  - Stores tenant ID to      │
                   │    identify customer        │
                   └─────────────────────────────┘

Multi-Tenant Implementation

// Backend API token validation (multi-tenant)
import { JwtPayload, verify } from "jsonwebtoken";
import { jwksClient } from "jwks-rsa";

async function validateMultiTenantToken(token: string): Promise<JwtPayload> {
  // Decode without verification first
  const decoded = jwt.decode(token, { complete: true });
  if (!decoded) throw new Error("Invalid token");
  
  // Extract tenant ID from token
  const tenantId = decoded.payload.tid;  // Tenant ID claim
  
  // Get JWKS for this tenant
  const client = jwksClient({
    jwksUri: `https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`
  });
  
  const key = await client.getSigningKey(decoded.header.kid);
  const publicKey = key.getPublicKey();
  
  // Verify token
  const verified = verify(token, publicKey, {
    audience: process.env.AZURE_CLIENT_ID,
    issuer: `https://login.microsoftonline.com/${tenantId}/v2.0`,
    algorithms: ["RS256"]
  });
  
  return verified as JwtPayload;
}

// Usage:
app.get("/api/payments", async (req, res) => {
  try {
    const token = req.headers.authorization?.replace("Bearer ", "");
    const claims = await validateMultiTenantToken(token!);
    
    // Identify customer by tenant
    const customerId = claims.tid;  // Tenant ID
    const userId = claims.oid;       // User object ID
    
    // Fetch data for this customer's tenant
    const payments = await getPayments(customerId, userId);
    
    res.json(payments);
  } catch (error) {
    res.status(401).json({ error: "Unauthorized" });
  }
});

Real-World Application Patterns

Let me show you how I structure apps in production.

Pattern 1: SPA + Backend API

App Registrations:

1. pos-frontend (SPA)
   - Platform: Single-page application
   - Redirect URI: https://pos.mycompany.com
   - Permissions: payment-api (Payments.Read, Payments.Write)

2. payment-api (Backend API)
   - Platform: Web
   - Exposes: Payments.Read, Payments.Write scopes
   - Permissions: Microsoft Graph (User.Read)

Authentication flow:

// Frontend (React)
import { PublicClientApplication } from "@azure/msal-browser";

const msalConfig = {
  auth: {
    clientId: "pos-frontend-client-id",
    authority: "https://login.microsoftonline.com/tenant-id",
    redirectUri: window.location.origin
  }
};

const msalInstance = new PublicClientApplication(msalConfig);

// Sign in
const loginRequest = {
  scopes: ["api://payment-api/Payments.Read", "api://payment-api/Payments.Write"]
};

const result = await msalInstance.loginPopup(loginRequest);
const accessToken = result.accessToken;

// Call API with token
const response = await fetch("https://api.mycompany.com/payments", {
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

Pattern 2: Microservices with Service Principal Auth

** App Registrations:**

1. api-gateway (Entry point)
   - Client secret
   - Permissions: user-service, payment-service

2. user-service (Backend service)
   - Exposes: Users.Read, Users.Write
   
3. payment-service (Backend service)
   - Exposes: Payments.Read, Payments.Write
   - Permissions: user-service (Users.Read)

Service-to-service auth:

// api-gateway calling user-service
import { ClientSecretCredential } from "@azure/identity";

class ServiceClient {
  private credential: ClientSecretCredential;
  
  constructor() {
    this.credential = new ClientSecretCredential(
      process.env.AZURE_TENANT_ID!,
      process.env.AZURE_CLIENT_ID!,
      process.env.AZURE_CLIENT_SECRET!
    );
  }
  
  async callUserService(userId: string) {
    // Get token for user-service
    const tokenResponse = await this.credential.getToken(
      "api://user-service/.default"
    );
    
    const response = await fetch(
      `https://user-service.mycompany.com/users/${userId}`,
      {
        headers: {
          "Authorization": `Bearer ${tokenResponse.token}`
        }
      }
    );
    
    return response.json();
  }
}

Pattern 3: Azure Function with Managed Identity

Setup:

1. payment-processor-function
   - System-assigned managed identity: ✅ Enabled
   - Key Vault access policy: GET secrets
   - Storage account: Contributor role

No app registration needed!

// Azure Function code
import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import { BlobServiceClient } from "@azure/storage-blob";

// Automatically uses managed identity
const credential = new DefaultAzureCredential();

// Access Key Vault
const kvClient = new SecretClient(
  "https://my-vault.vault.azure.net",
  credential
);
const secret = await kvClient.getSecret("api-key");

// Access Storage
const blobClient = new BlobServiceClient(
  "https://mystorageaccount.blob.core.windows.net",
  credential
);
const container = blobClient.getContainerClient("payments");

No secrets to manage. Azure handles everything.

Common Pitfalls

Let me share mistakes I've made (so you don't have to):

Pitfall 1: Confusing Object ID and Application ID

// ❌ Wrong
const appId = "sp-object-id";  // This is service principal's object ID

// ✅ Correct
const appId = "12345678-1234-1234-1234-123456789abc";  // Application (client) ID

Always use Application (client) ID for authentication.

Pitfall 2: Exposing Client Secrets

// ❌ NEVER do this
const secret = "abc123secret";  // Hardcoded
git add .
git commit -m "Add auth"
// Secret now in git history forever

// ✅ Use environment variables
const secret = process.env.AZURE_CLIENT_SECRET;

// ✅ Or Key Vault
const secret = await keyVaultClient.getSecret("client-secret");

Pitfall 3: Wrong Platform Configuration

// SPA configured as "Web" platform
// ❌ Implicit flow enabled
// ❌ Client secret created (SPAs can't keep secrets!)

// ✅ Configure as "Single-page application"
// ✅ Use authorization code flow with PKCE
// ✅ No client secrets

Pitfall 4: Forgetting to Grant Admin Consent

// Added Application permission User.Read.All
// Forgot to click "Grant admin consent"
// API calls fail with "Insufficient privileges"

// ✅ Always grant admin consent for Application permissions

Key Takeaways

1. App Registration = Blueprint: Define your app globally

2. Service Principal = Instance: Instance in each tenant

3. Client ID is Everything: You'll use it constantly

4. Secrets vs Certificates: Certificates are more secure

5. Platform Matters: Configure correctly (Web vs SPA vs Mobile)

6. Multi-Tenant = More Complex: Only use if you need it

7. Managed Identities = No Secrets: Use for Azure resources

What's Next

In Part 3: Authentication Protocols and Flows, we'll dive into:

• OAuth 2.0 flows in detail

• OpenID Connect (OIDC) implementation

• SAML integration

• Which flow to use when

• Authorization code, client credentials, on-behalf-of flows

• PKCE for public clients

We'll move from configuration to actual authentication implementation.

---

Previous: Part 1: Introduction to Microsoft Entra ID Next: Part 3: Authentication Protocols and Flows Back to Series Overview