1# First App Registration - Step-by-Step Guide
2 
3This guide walks you through creating your first Microsoft Entra app registration from scratch.
4 
5## Overview
6 
7You'll learn how to:
81. Create an app registration in Azure Portal
92. Configure authentication settings
103. Add API permissions
114. Create client credentials
125. Test the authentication flow
13 
14## Prerequisites
15 
16- Azure subscription (free tier works)
17- Azure Portal access: https://portal.azure.com
18- Basic understanding of your application type (web, mobile, service)
19 
20## Step 1: Navigate to App Registrations
21 
221. Open [Azure Portal](https://portal.azure.com)
232. Search for **"Microsoft Entra ID"**
243. In the left menu, click **"App registrations"**
254. Click **"+ New registration"** at the top
26 
27## Step 2: Register Your Application
28 
29You'll see a form with several fields:
30 
31### Application Name
32- **What to enter:** A descriptive name for your app
33- **Example:** "My First Console App" or "Product Inventory API"
34- **Tip:** Use a name that clearly identifies the purpose
35 
36### Supported Account Types
37 
38Choose who can use your application:
39 
40| Option | When to Use |
41|--------|-------------|
42| **Accounts in this organizational directory only (Single tenant)** | Only users from the same tenant of this app registration need access |
43| **Accounts in any organizational directory (Multi-tenant)** | Users from multiple organization tenants need access |
44| **Accounts in any organizational directory + Personal Microsoft accounts** | Users from multiple organization tenants and MSA users need access |
45| **Personal Microsoft accounts only** | Only MSA users need access |
46 
47**Note:** Once selected, users whose account type is not allowed will get errors when trying to get access token for the app registration.
48 
49### Redirect URI (optional)
50 
51The redirect URI is where authentication responses are sent.
52 
53**Platform:** Select the type:
54- **Web** - Server-side web apps
55- **Single-page application (SPA)** - React, Angular, Vue apps
56- **Public client/native** - Mobile, desktop, console apps
57 
58**URI examples:**
59- Web app: `https://localhost:5001/signin-oidc`
60- SPA: `http://localhost:3000`
61- Console/Desktop: `http://localhost`
62 
63**For your first app:** Select **"Public client/native"** and enter `http://localhost`
64 
65### Click "Register"
66 
67After clicking, you'll be redirected to your app's overview page.
68 
69## Step 3: Save Important Information
70 
71On the **Overview** page, you'll see critical information. **Copy and save these values:**
72 
73### Application (client) ID
74- **What it is:** Unique identifier for your app
75- **Format:** `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (GUID)
76- **When you need it:** Every time your app authenticates
77- **Where to save:** Environment variables, configuration file
78 
79### Directory (tenant) ID
80- **What it is:** Unique identifier for your Azure AD tenant
81- **Format:** `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (GUID)
82- **When you need it:** Constructing authentication URLs
83 
84### Example values to save:
85```bash
86# Save these in a secure location
87APPLICATION_CLIENT_ID="12345678-1234-1234-1234-123456789012"
88TENANT_ID="87654321-4321-4321-4321-210987654321"
89```
90 
91## Step 4: Configure Authentication (Optional)
92 
93Click **"Authentication"** in the left menu.
94 
95### Advanced Settings
96 
97**Allow public client flows:**
98- **What it is:** Enables device code flow, resource owner password flow
99- **For console apps:** Turn this **ON**
100- **For web apps:** Keep **OFF**
101 
102### Supported account types
103 
104You can change this later if needed.
105 
106### Logout URL (optional)
107 
108Where to redirect users after logout.
109 
110**Click "Save"** at the top if you made changes.
111 
112## Step 5: Add API Permissions
113 
114Click **"API permissions"** in the left menu.
115 
116### Default Permission
117 
118You'll see one default permission:
119- **Microsoft Graph → User.Read (Delegated)**
120 
121This allows your app to read the signed-in user's profile.
122 
123### Add More Permissions
124 
1251. Click **"+ Add a permission"**
1262. Select **"Microsoft Graph"**
1273. Choose **"Delegated permissions"** (for user context)
1284. Search for and select permissions you need:
129   - **User.Read** - Read user profile (already added)
130   - **Mail.Read** - Read user's mail
131   - **Calendars.Read** - Read user's calendar
132 
1335. Click **"Add permissions"**
134 
135### Admin Consent
136 
137Some permissions require admin consent:
138- If you're an admin: Click **"Grant admin consent for [Your Org]"**
139- If you're not: Ask your admin to grant consent
140 
141**Status indicator:**
142- ✅ Green checkmark = Granted
143- ⚠️ Yellow warning = Not granted (may still work for user consent)
144 
145## Step 6: Create Client Secret (If Needed)
146 
147**Skip this if:** You're building a desktop/mobile/console app (public client)
148 
149**Do this if:** You're building a web app, API, or service (confidential client)
150 
1511. Click **"Certificates & secrets"** in the left menu
1522. Click **"+ New client secret"**
1533. Enter a description: "Development Secret"
1544. Choose expiration:
155   - **Recommended for development:** 6 months
156   - **For production:** 12-24 months (set up rotation)
1575. Click **"Add"**
158 
159**⚠️ CRITICAL:** Copy the secret **Value** immediately!
160- It's only shown once
161- You cannot retrieve it later
162- If you lose it, create a new one
163 
164```bash
165# Save this securely (example)
166CLIENT_SECRET="abc123~defGHI456jklMNO789pqrSTU"
167```
168 
169**Security tips:**
170- Never commit secrets to source control
171- Use Azure Key Vault for production
172- Use environment variables for development
173 
174## Step 7: Test Your App Registration
175 
176### Option A: Quick Test with Azure CLI
177 
178```bash
179# Set your values
180CLIENT_ID="your-client-id-here"
181TENANT_ID="your-tenant-id-here"
182 
183# Interactive login
184az login --scope "https://graph.microsoft.com/.default"
185 
186# Get an access token
187az account get-access-token --resource "https://graph.microsoft.com"
188```
189 
190### Option B: Test with MSAL Library
191 
192See the complete code example in [console-app-example.md](console-app-example.md)
193 
194### Expected Results
195 
196**Success:**
197- Browser opens for authentication (or device code shown)
198- You authenticate with your Azure AD account
199- Access token is returned
200- You can call Microsoft Graph API
201 
202**Common first-time issues:**
203- Redirect URI mismatch → Double-check URI in Authentication settings
204- Insufficient permissions → Add required API permissions
205- User consent required → Grant admin consent or user must consent
206 
207**Tip:** Once you get the access token, you can use [jwt.ms](https://jwt.ms) to decode it and inspect its claims.
208 
209## Step 8: Review Configuration
210 
211### Checklist
212 
213- ✅ App registered with clear name
214- ✅ Application ID and Tenant ID saved securely
215- ✅ Redirect URI configured correctly
216- ✅ API permissions added
217- ✅ Admin consent granted (if required)
218- ✅ Client secret created and saved (if needed)
219- ✅ Authentication tested successfully
220 
221## Next Steps
222 
223- In your client app, implement the OAuth flow to acquire access tokens for your app registration.
224- In your server app, implement token validation to protect your resources.
225 
226## Troubleshooting
227 
228### Redirect URI mismatch"
229 
230**Solution:**
231- Check Authentication → Redirect URIs
232- Ensure exact match (case-sensitive, trailing slash matters)
233- Ensure correct platform (Web vs SPA vs Public client)
234 
235### User consent required
236 
237**Solution:**
238- Grant admin consent in API permissions
239- Or have user consent during first login
240 
241## Additional Resources
242 
243- [Microsoft Entra ID Documentation](https://learn.microsoft.com/en-us/entra/identity-platform/)
244