1# Troubleshooting Microsoft Entra App Registration
2 
3This guide helps you diagnose and fix common issues with app registrations and authentication.
4 
5## Table of Contents
6 
7- [Authentication Errors](#authentication-errors)
8- [Token Issues](#token-issues)
9- [Permission Problems](#permission-problems)
10- [Redirect URI Issues](#redirect-uri-issues)
11- [Application Configuration](#application-configuration)
12- [Debugging Tools](#debugging-tools)
13 
14## Authentication Errors
15 
16### Redirect URI Mismatch
17 
18**Error message:**
19```
20AADSTS50011: The redirect URI 'http://localhost:3000' specified in the request 
21does not match the redirect URIs configured for the application.
22```
23 
24**Cause:** The redirect URI in your authentication request doesn't exactly match what's registered.
25 
26**Solutions:**
27 
281. **Check exact match** (case-sensitive, trailing slash matters):
29   ```
30   Registered: https://myapp.com/callback
31   Request:    https://myapp.com/callback/  ❌ (trailing slash)
32   Request:    https://MyApp.com/callback   ❌ (case difference)
33   Request:    https://myapp.com/callback   ✅
34   ```
35 
362. **Add URI to app registration:**
37   ```bash
38   # Portal: Authentication → Add redirect URI
39   # CLI:
40   az ad app update --id $APP_ID \
41     --web-redirect-uris "http://localhost:3000" "https://myapp.com/callback"
42   ```
43 
443. **Check platform type:**
45   - Web URIs go in "Web" platform
46   - SPA URIs go in "Single-page application"
47   - Desktop/mobile URIs go in "Public client/native"
48 
49### Invalid Client Secret
50 
51**Error message:**
52```
53AADSTS7000215: Invalid client secret provided. 
54Ensure the secret being sent in the request is the client secret value, not the client secret ID.
55```
56 
57**Causes:**
58- Client secret expired
59- Wrong secret value (copied secret ID instead of value)
60- Secret doesn't match app registration
61 
62**Solutions:**
63 
641. **Check expiration:**
65   ```bash
66   az ad app credential list --id $APP_ID
67   ```
682. **Create new secret:**
69   ```bash
70   az ad app credential reset --id $APP_ID --years 1
71   ```
72   Copy the `password` value (not the `keyId`)
73 
74### User Consent Required
75 
76**Error message:**
77```
78AADSTS65001: The user or administrator has not consented to use the application
79```
80 
81**Causes:**
82- Application permissions require admin consent
83- User hasn't consented to delegated permissions
84- Consent was revoked
85 
86**Solutions:**
87 
881. **Grant admin consent (if admin):**
89   ```bash
90   az ad app permission admin-consent --id $APP_ID
91   ```
92 
932. **Request user consent (interactive flow):**
94   This requires the client app to have access to UI such as browser, terminal window, etc. Follow the best practices of your client app to implement the interactive flow.
95 
963. **Check API permissions in portal:**
97   - Ensure permissions are added
98   - Look for green checkmarks (granted)
99   - Yellow warning means not granted
100 
101### Grant Declined
102 
103**Error message:**
104```
105AADSTS70000: The request was denied because one or more permissions have been declined
106```
107 
108**Cause:** User or admin explicitly denied consent.
109 
110**Solutions:**
111 
1121. **Re-request with explanation:**
113   - Explain why permissions are needed
114   - Request only necessary permissions
115 
1162. **Check if admin consent is required:**
117   - Some organizations disable user consent
118   - Contact your admin to grant consent
119 
1203. **Reduce permission scope:**
121   - Request minimal permissions initially
122   - Use incremental consent for additional features
123 
124### Application Not Found
125 
126**Error message:**
127```
128AADSTS700016: Application with identifier '{app-id}' was not found in the directory
129```
130 
131**Causes:**
132- Wrong application ID
133- Wrong tenant ID
134- Service principal not created
135- App in different tenant
136 
137**Solutions:**
138 
1391. **Verify application ID:**
140   ```bash
141   az ad app list --display-name "MyApp" --query "[].{Name:displayName, AppId:appId}"
142   ```
143 
1442. **Verify tenant ID:**
145   ```bash
146   az account show --query tenantId -o tsv
147   ```
148 
149### Application Doesn't have a Service Principal
150 
151**Error message:**
152```
153The app is trying to access a service 'your_app_id'(your_app_name) that your organization 'your_tenant_id' lacks a service principal for
154```
155 
156**Causes:**
157- Your tenant is not configured to automatically provision the service principal for app registrations in it.
158 
159**Solutions:**
160 
1611. **Create service principal:**
162   ```bash
163   az ad sp create --id $APP_ID
164   ```
165 
166### Missing Required Field
167 
168**Error message:**
169```
170AADSTS90014: The required field 'client_id' is missing from the request
171```
172 
173This can happen if the client you are using isn't compatible with Entra. Consult the owner of your client app to see if it supports Entra.
174 
175## Token Issues
176 
177Unless the the access token is encrypted, you can decode and view its claims securely at https://jwt.ms. **Don't** use any other website to decode an access token. Compare the claims in the token with the app registration's configuration to identify issues.
178 
179## Debugging Tools
180 
181### JWT Token Decoder
182 
183**Tool:** https://jwt.ms
184 
185**How to use:**
1861. Copy your access token
1872. Paste into jwt.ms
1883. Review claims:
189   - `aud` - Audience (should match your API)
190   - `iss` - Issuer (should be login.microsoftonline.com)
191   - `scp` - Delegated permissions
192   - `roles` - Application permissions
193   - `exp` - Expiration timestamp
194   - `oid` - User object ID
195 
196---
197 
198### Fiddler
199 
200**Use for:** Inspecting HTTP requests/responses
201 
202**What to check:**
203- Authorization header format: `Bearer {token}`
204- Token is being sent
205- Response status codes and error messages
206 
207### Entra Sign-in Logs
208 
209**Access:** Azure Portal → Microsoft Entra ID → Sign-in logs
210 
211**What to check:**
212- Failed sign-in attempts
213- Error codes and messages
214- User consent status
215- Conditional Access policy failures
216 
217## Common Error Codes Reference
218 
219| Error Code | Meaning | Common Cause |
220|------------|---------|--------------|
221| AADSTS50011 | Redirect URI mismatch | URI not registered or doesn't match |
222| AADSTS50020 | Invalid tenant | Wrong tenant in authority URL |
223| AADSTS50034 | User not found | User doesn't exist in tenant |
224| AADSTS50053 | Account locked | Too many failed attempts |
225| AADSTS50055 | Password expired | User needs to reset password |
226| AADSTS50057 | Account disabled | User account disabled |
227| AADSTS50058 | Silent sign-in failed | Interactive auth required |
228| AADSTS50059 | Tenant not found | Invalid tenant ID |
229| AADSTS65001 | Consent required | User/admin hasn't consented |
230| AADSTS70000 | Grant declined | User denied consent |
231| AADSTS70001 | App disabled | App registration disabled |
232| AADSTS700016 | App not found | Invalid app ID or wrong tenant |
233| AADSTS7000215 | Invalid client secret | Wrong/expired secret |
234| AADSTS90014 | Missing field | Required parameter not sent |
235| AADSTS90072 | Consent needed | Admin consent required |
236 
237## Best Practices for Troubleshooting
238 
239### Systematic Approach
240 
2411. **Collect information:**
242   - Exact error message and code
243   - When it started happening
244   - What changed recently
245   - Environment (dev/test/prod)
246 
2472. **Check basics first:**
248   - App ID and tenant ID correct
249   - Permissions added and consented
250   - Redirect URIs configured
251   - Secrets/certificates valid
252 
2533. **Use debugging tools:**
254   - Decode tokens (jwt.ms)
255   - Check sign-in logs
256   - Enable MSAL logging
257   - Use network inspector
258 
2594. **Test incrementally:**
260   - Test with minimal permissions
261   - Add permissions one at a time
262   - Test different flows separately
263 
264## Getting Help
265 
266### Microsoft Resources
267 
268- [Microsoft Q&A](https://learn.microsoft.com/answers/)
269- [Microsoft Identity Platform Documentation](https://learn.microsoft.com/entra/identity-platform/)
270