Back to App
DocsHome
Docs/Troubleshooting/Connection Issues

Connection Issues

Diagnose and resolve Microsoft 365 tenant connection problems.

Invalid Credentials Error

Problem

Tenant sync fails with error: "Invalid credentials" or "Authentication failed"

Diagnosis

  • App registration credentials may have expired
  • Client secret was rotated but not updated in TrueConfig
  • Required Graph API permissions were revoked
  • Service principal was disabled or deleted

Resolution

Step 1: Verify App Registration

  1. Sign in to Azure Portal (portal.azure.com)
  2. Navigate to App Registrations
  3. Find your TrueConfig app registration
  4. Check Overview → Enabled: Should be "Yes"

Step 2: Check Client Secret Expiration

  1. In App Registration, go to Certificates & secrets
  2. Verify client secret has not expired
  3. If expired, create new client secret
  4. Copy the secret value (visible only once)

Step 3: Update Credentials in TrueConfig

  1. Navigate to Settings → Tenants → [Tenant Name]
  2. Click "Reconnect"
  3. Enter Application (client) ID
  4. Enter new client secret
  5. Enter Directory (tenant) ID
  6. Click "Save and Test Connection"
Client Secret Security
Client secrets should be rotated every 90 days for security. Set a calendar reminder to rotate secrets before expiration to prevent connection interruptions.

Insufficient Permissions Error

Problem

Sync fails with: "Insufficient privileges to complete the operation" or specific API endpoint access denied.

Diagnosis

Required Microsoft Graph API permissions are not granted or admin consent was not provided.

Required Permissions

The TrueConfig app registration requires these delegated permissions:

PermissionTypePurpose
Directory.Read.AllApplicationRead directory data
Policy.Read.AllApplicationRead Conditional Access policies
RoleManagement.Read.AllApplicationRead role assignments
User.Read.AllApplicationRead user profiles
AuditLog.Read.AllApplicationRead audit logs
Reports.Read.AllApplicationRead MFA registration details and user reports

Resolution

  1. In Azure Portal, navigate to App Registrations → [Your App] → API permissions
  2. Click "Add a permission" → Microsoft Graph → Application permissions
  3. Add each required permission listed above
  4. Click "Grant admin consent for [Organization]"
  5. Verify all permissions show green checkmarks
  6. Return to TrueConfig and retry the connection test
Admin Consent Required
Application permissions require Global Administrator or Privileged Role Administrator consent. Standard users cannot grant these permissions.

Multi-Factor Authentication Required

Problem

Connection test prompts for MFA or fails with authentication challenges.

Diagnosis

TrueConfig uses application (service principal) authentication, not interactive user authentication. If you're seeing MFA prompts, the connection is configured incorrectly.

Resolution

Verify you're using the correct authentication method:

Required Credentials:

  • Application (client) ID: A GUID from your app registration
  • Directory (tenant) ID: Your tenant's GUID
  • Client secret: The secret value you copied from App Registration

Do NOT use your email address and password - those are for interactive sign-in only.

Service Principal Authentication
TrueConfig connects to Microsoft Graph using service principal (app-only) authentication, which does not require user interaction or MFA challenges.

Conditional Access Blocking Connection

Problem

Connection test fails with: "Conditional Access policy blocks this request"

Diagnosis

A Conditional Access policy is blocking the service principal from accessing Microsoft Graph.

Resolution

  1. In Azure Portal, navigate to Microsoft Entra ID → Security → Conditional Access
  2. Review all policies with "All cloud apps" or "Microsoft Graph" in scope
  3. Check if policies apply to "Service principals and workload identities"
  4. Add TrueConfig service principal to exclusions if blocking legitimate access
Security Consideration
Excluding service principals from Conditional Access policies reduces security. Only exclude if necessary and document the exception in your security policy.

Rate Limit Exceeded

Problem

Sync fails with: "Rate limit exceeded" or HTTP 429 errors in logs.

Diagnosis

Microsoft Graph enforces rate limits on API calls. TrueConfig includes automatic retry logic, but sustained high-volume syncs may hit throttling limits.

Resolution

  1. Reduce sync frequency in Settings → Tenants → [Tenant] → Sync Schedule
  2. Avoid running manual full scans during automated sync windows
  3. If managing multiple tenants, stagger sync schedules by 30+ minutes
  4. Wait 5-10 minutes and retry - rate limits reset automatically
Automatic Retry
TrueConfig automatically retries throttled requests with exponential backoff. Most rate limit errors resolve without intervention.

Missing MFA Registration Data

Problem

ID-01 control shows "0% of users have MFA registered" even though Conditional Access policies enforce MFA.

Diagnosis

The Reports.Read.All permission is missing, preventing TrueConfig from accessing the MFA registration endpoint (/beta/reports/authenticationMethods/userRegistrationDetails).

Resolution

For new tenant connections:

  1. Disconnect and reconnect your tenant to trigger a new OAuth consent flow
  2. The updated consent screen will automatically request Reports.Read.All
  3. Accept the permissions and complete the connection
  4. Run a new scan - MFA registration data will now be collected

For existing tenant connections without reconnecting:

  1. In Azure Portal, navigate to App Registrations → [Your App] → API permissions
  2. Click "Add a permission" → Microsoft Graph → Application permissions
  3. Search for and add Reports.Read.All
  4. Click "Grant admin consent for [Organization]"
  5. Verify the permission shows a green checkmark
  6. Run a new scan in TrueConfig - MFA data will now be collected
Graceful Degradation
If Reports.Read.All is not granted, scans will continue successfully but ID-01 will only evaluate based on Conditional Access policies. The scan logs will show a warning: "MFA registration fetch failed (requires Reports.Read.All)".

Still Need Help?

If you've followed these troubleshooting steps and still cannot connect, collect the following information:

  • Application (client) ID from Azure Portal
  • Directory (tenant) ID from Azure Portal
  • Screenshot of granted API permissions showing green checkmarks
  • Error message from TrueConfig connection test
  • Tenant sync logs from Audit Logs page

Contact support at support@trueconfig.com with this information for assistance.

Scanning Process