/entra-app-registration

First App Registration - Step-by-Step Guide

This guide walks you through creating your first Microsoft Entra app registration from scratch.

Overview

You'll learn how to:

1. Create an app registration in Azure Portal
2. Configure authentication settings
3. Add API permissions
4. Create client credentials
5. Test the authentication flow

Prerequisites

• Azure subscription (free tier works)
• Azure Portal access: https://portal.azure.com
• Basic understanding of your application type (web, mobile, service)

Step 1: Navigate to App Registrations

1. Open Azure Portal
2. Search for "Microsoft Entra ID"
3. In the left menu, click "App registrations"
4. Click "+ New registration" at the top

Step 2: Register Your Application

You'll see a form with several fields:

Application Name

• What to enter: A descriptive name for your app
• Example: "My First Console App" or "Product Inventory API"
• Tip: Use a name that clearly identifies the purpose

Supported Account Types

Choose who can use your application:

Note: Once selected, users whose account type is not allowed will get errors when trying to get access token for the app registration.

Redirect URI (optional)

The redirect URI is where authentication responses are sent.

Platform: Select the type:

• Web - Server-side web apps
• Single-page application (SPA) - React, Angular, Vue apps
• Public client/native - Mobile, desktop, console apps

URI examples:

• Web app: https://localhost:5001/signin-oidc
• SPA: http://localhost:3000
• Console/Desktop: http://localhost

For your first app: Select "Public client/native" and enter http://localhost

Click "Register"

After clicking, you'll be redirected to your app's overview page.

Step 3: Save Important Information

On the Overview page, you'll see critical information. Copy and save these values:

Application (client) ID

• What it is: Unique identifier for your app
• Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
• When you need it: Every time your app authenticates
• Where to save: Environment variables, configuration file

Directory (tenant) ID

• What it is: Unique identifier for your Azure AD tenant
• Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
• When you need it: Constructing authentication URLs

Example values to save:

# Save these in a secure location
APPLICATION_CLIENT_ID="12345678-1234-1234-1234-123456789012"
TENANT_ID="87654321-4321-4321-4321-210987654321"

Step 4: Configure Authentication (Optional)

Click "Authentication" in the left menu.

Advanced Settings

Allow public client flows:

• What it is: Enables device code flow, resource owner password flow
• For console apps: Turn this ON
• For web apps: Keep OFF

Supported account types

You can change this later if needed.

Logout URL (optional)

Where to redirect users after logout.

Click "Save" at the top if you made changes.

Step 5: Add API Permissions

Click "API permissions" in the left menu.

Default Permission

You'll see one default permission:

• Microsoft Graph → User.Read (Delegated)

This allows your app to read the signed-in user's profile.

Add More Permissions

1. Click "+ Add a permission"

2. Select "Microsoft Graph"

3. Choose "Delegated permissions" (for user context)

4. Search for and select permissions you need:

   • User.Read - Read user profile (already added)
   • Mail.Read - Read user's mail
   • Calendars.Read - Read user's calendar

5. Click "Add permissions"

Admin Consent

Some permissions require admin consent:

• If you're an admin: Click "Grant admin consent for [Your Org]"
• If you're not: Ask your admin to grant consent

Status indicator:

• ✅ Green checkmark = Granted
• ⚠️ Yellow warning = Not granted (may still work for user consent)

Step 6: Create Client Secret (If Needed)

Skip this if: You're building a desktop/mobile/console app (public client)

Do this if: You're building a web app, API, or service (confidential client)

1. Click "Certificates & secrets" in the left menu
2. Click "+ New client secret"
3. Enter a description: "Development Secret"
4. Choose expiration:
   • Recommended for development: 6 months
   • For production: 12-24 months (set up rotation)
5. Click "Add"

⚠️ CRITICAL: Copy the secret Value immediately!

• It's only shown once
• You cannot retrieve it later
• If you lose it, create a new one

# Save this securely (example)
CLIENT_SECRET="abc123~defGHI456jklMNO789pqrSTU"

Security tips:

• Never commit secrets to source control
• Use Azure Key Vault for production
• Use environment variables for development

Step 7: Test Your App Registration

Option A: Quick Test with Azure CLI

# Set your values
CLIENT_ID="your-client-id-here"
TENANT_ID="your-tenant-id-here"

# Interactive login
az login --scope "https://graph.microsoft.com/.default"

# Get an access token
az account get-access-token --resource "https://graph.microsoft.com"

Option B: Test with MSAL Library

See the complete code example in console-app-example.md

Expected Results

Success:

• Browser opens for authentication (or device code shown)
• You authenticate with your Azure AD account
• Access token is returned
• You can call Microsoft Graph API

Common first-time issues:

• Redirect URI mismatch → Double-check URI in Authentication settings
• Insufficient permissions → Add required API permissions
• User consent required → Grant admin consent or user must consent

Tip: Once you get the access token, you can use jwt.ms to decode it and inspect its claims.

Step 8: Review Configuration

Checklist

• ✅ App registered with clear name
• ✅ Application ID and Tenant ID saved securely
• ✅ Redirect URI configured correctly
• ✅ API permissions added
• ✅ Admin consent granted (if required)
• ✅ Client secret created and saved (if needed)
• ✅ Authentication tested successfully

Next Steps

• In your client app, implement the OAuth flow to acquire access tokens for your app registration.
• In your server app, implement token validation to protect your resources.

Troubleshooting

Redirect URI mismatch"

Solution:

• Check Authentication → Redirect URIs
• Ensure exact match (case-sensitive, trailing slash matters)
• Ensure correct platform (Web vs SPA vs Public client)

User consent required

Solution:

• Grant admin consent in API permissions
• Or have user consent during first login

Additional Resources

• Microsoft Entra ID Documentation