OAuth 2.0 Validation Failures During Installation

During the Nodinite installation pre-flight check, you may encounter one or both of these validation failures:

• Error [10.3] – OAuth2 client credentials validation failed
• Error [10.4] – Token claims validation failed for InstallationClient

This guide provides detailed root cause analysis, quick-reference checklists, and step-by-step solutions for all OAuth 2.0 validation scenarios.

Understanding OAuth 2.0 Validation Architecture

How Pre-Flight Validation Works

The Nodinite installation wizard performs a three-tier validation before attempting to connect to your identity provider:

Diagram: The pre-flight validation workflow proceeds through three tiers. Failures at any tier halt installation with specific error codes.

OAuth Configuration Components

The Installation Client fields are on the Portal's Auth step, in the Installation Client group of the OAuth2 settings section, directly below the Discovery URL. For each field's meaning and its Entra ID value, see OAuth2 settings: Discovery URL and Installation Client.

Error [10.3] – OAuth2 Client Credentials Validation Failed

What This Error Means

Error [10.3] appears when the pre-flight validation cannot obtain a valid OAuth 2.0 access token from your identity provider using the Installation Client's Client ID and secret. This is a configuration or credentials issue detected at Tier 1 or 2 of validation.

Common Error Messages

ERROR: [10.3] OAuth2 client credentials validation failed for InstallationClient.
       Response status code does not indicate success: 401 (Unauthorized).

ERROR: [10.3] OAuth2 client credentials validation failed for InstallationClient.
       One or more errors occurred: 'InvalidClientSecret' or 'Unknown_UserType'

Root Cause Analysis

Work through this table to identify which root cause matches your scenario:

Quick Fix Checklist – Error [10.3]

Follow these steps in order. Most cases are resolved by steps 1–3:

✅ Step 1: Verify the Installation Client: Client ID

In the Portal, on the Auth step:

1. Go to OAuth2 settings → Installation Client → Client ID (see Installation Client: Client ID).
2. Copy the value into Notepad (to check for hidden spaces).
3. Compare character-by-character with the value in Azure AD:
   • Open Azure Portal > Microsoft Entra ID > App registrations.
   • Search for NodiniteInstallationClient.
   • Go to Overview.
   • Copy the Application (client) ID.
4. Match exactly – IDs are case-sensitive GUIDs.

Common mistakes:

• ❌ Copying from webClient app registration instead of NodiniteInstallationClient
• ❌ Copying from the URL (which may have partial IDs)
• ❌ Extra spaces at beginning or end

✅ Step 2: Regenerate Installation Client Secret

Installation Client Secrets cannot be viewed twice – Azure AD only displays them during creation. If you cannot find the original secret, regenerate it:

1. Azure Portal > Microsoft Entra ID > App registrations > NodiniteInstallationClient.
2. Go to Certificates & secrets.
3. Under Client secrets, if you have an expired secret:
   • Click the ⋯ (three dots) next to the expired secret.
   • Select Delete.
4. Click + New client secret.
   • Description: Nodinite Installation Client Secret (or your naming convention)
   • Expires: Choose based on your policy (e.g., 24 months)
   • Click Add.
5. Copy the Value immediately (shown under Value column).
   • This is the only time Azure AD displays it.
   • Store securely (password manager, secure note).
6. Paste this value into your Nodinite configuration (where required by your setup process).
   • Ensure no extra spaces at beginning or end.

Verification:

• Open Notepad.
• Paste the secret.
• Check for leading/trailing spaces.
• If found, re-copy without spaces.

✅ Step 3: Verify Installation Client Scopes

In the Portal, on the Auth step:

1. Go to OAuth2 settings → Installation Client → Installation Client Scopes (see Installation Client Scopes).
2. Confirm the value is exactly:

   api://<webApi-client-id>/.default
   

3. Replace <webApi-client-id> with the Application (client) ID from your webApi app registration in Azure AD.

Example:

api://d731e991-1234-5678-90ab-cdef12345678/.default

Common mistakes:

• ❌ Missing the .default suffix (e.g., api://d731e991-1234-5678-90ab-cdef12345678)
• ❌ Including only generic scopes (e.g., openid or profile)
• ❌ Incomplete GUID

✅ Step 4: Verify Admin Consent Granted

In Azure AD, confirm admin consent is granted for the Installation Client:

1. Azure Portal > Microsoft Entra ID > App registrations > NodiniteInstallationClient.
2. Go to API permissions.
3. Look for the entry AppRole_WebApi_all from the webApi app.
4. Check the Status column:
   • ✅ Should say: Granted for [Tenant Name]
   • ❌ If it says: Not granted or has a warning icon
5. If not granted, click Grant admin consent for [Tenant Name] and confirm.
   • Only Global Administrators can do this – contact your Azure AD administrator if needed.

✅ Step 5: Verify NodiniteInstallationClient Exists

Check the app registration exists and is configured:

1. Azure Portal > Microsoft Entra ID > App registrations.
2. In the filter menu, ensure All applications is selected (not just "Owned by me").
3. Search for NodiniteInstallationClient.
4. If not found:
   • Follow Register Nodinite Applications in Azure AD to create it.
5. If found but missing API permissions:
   • Go to API permissions.
   • If AppRole_WebApi_all is missing, add it:
     • Click + Add a permission.
     • Select My APIs > webApi.
     • Choose Application permissions (not Delegated).
     • Tick AppRole_WebApi_all.
     • Click Add permissions.
     • Grant admin consent.

✅ Step 6: Test Network Connectivity

If Tier 1–5 pass but you still see 401 errors:

On the machine running the Nodinite installation, verify connectivity to Azure AD:

# Test HTTPS connectivity to Azure AD token endpoint
$uri = "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token"
$result = Invoke-WebRequest -Uri $uri -Method POST -Body "grant_type=client_credentials" -ErrorAction SilentlyContinue
$result.StatusCode
# Expected: 400 Bad Request (not 401 Unauthorized or timeout)
# A successful connection returns 400 because we didn't provide credentials

If you see:

• ✅ 400 Bad Request – Network is OK, issue is credentials
• ❌ Timeout – Firewall likely blocking outbound HTTPS
• ❌ Connection refused – Firewall blocking

Error [10.4] – Token Claims Validation Failed

What This Error Means

Error [10.4] appears when the pre-flight validation obtains a valid OAuth 2.0 token successfully (Tier 2 passes) but the token lacks required claims or scopes specified in your configuration (Tier 3 fails).

This typically means:

• The token was generated successfully (credentials are correct)
• Admin consent was not granted for the required permissions in Azure AD
• The token claims are missing the required role or scope values

Common Error Messages

ERROR: [10.4] Token claims validation failed for InstallationClient.
       Required scope 'api://<webApi-client-id>/.default' not satisfied

ERROR: [10.4] Token claims validation failed for InstallationClient.
       Required claim 'http://schemas.microsoft.com/ws/2008/06/identity/claims/role' is missing

ERROR: [10.4] Token claims validation failed for InstallationClient.
       Required claim value 'AppRole_WebApi_all' not found in token

Root Cause Analysis – Error [10.4]

Quick Fix Checklist – Error [10.4]

✅ Step 1: Verify Admin Consent for App Roles

This is the most common cause of Error [10.4]:

1. Azure Portal > Microsoft Entra ID > App registrations > NodiniteInstallationClient.
2. Go to API permissions.
3. Find the entry AppRole_WebApi_all (from webApi app).
4. Check the Status column:
   • ✅ Granted for [Tenant Name] = Correct
   • ⚠️ Not granted = Problem – click "Grant admin consent" and confirm
   • ❌ Entry missing entirely = Add it (see Step 4 in Error [10.3] checklist)

Important:

• Admin consent appears under the permission entry, not as a button.
• If you see "Grant admin consent for [Tenant Name]" button, click it now.
• Wait 1-2 minutes for Azure AD to update tokens.

✅ Step 2: Verify Installation Client Claims Configuration

In the Portal, on the Auth step:

1. Go to OAuth2 settings → Installation Client → Installation Client Claims (see Installation Client Claims).
2. Verify the KEY and VALUE pair:

3. Common mistakes:
   • ❌ Using shortened KEY like roles instead of full URL
   • ❌ VALUE is the description instead of the value (e.g., "Application permission for..." instead of "AppRole_WebApi_all")
   • ❌ Extra spaces in either field

✅ Step 3: Verify AppRole_WebApi_all Exists on webApi

Confirm the app role is created on the webApi app registration:

1. Azure Portal > Microsoft Entra ID > App registrations > webApi.

2. Go to App roles.

3. Look for AppRole_WebApi_all with:

   • Allowed member types: Applications
   • Value: AppRole_WebApi_all
   • State: Enabled

4. If missing, create it:

   • Click + Create app role.
   • Display name: AppRole_WebApi_all
   • Allowed member types: Applications
   • Value: AppRole_WebApi_all
   • Description: Application permission for Nodinite installation and background services
   • State: Enabled
   • Click Apply / Create.

5. After creating the role, return to NodiniteInstallationClient > API permissions and grant admin consent again.

✅ Step 4: Verify Installation Client Scopes (Reprise)

Even though this affects Error [10.3], it can cause Error [10.4] symptom "Scope not satisfied":

1. Installation Client Scopes must end with .default:

   api://<webApi-client-id>/.default
   

2. If it's missing .default, add it now and restart installation.

Common Mistakes & How to Avoid Them

Mistake #1: Copy-Paste Includes Extra Spaces

Problem: Pasting IDs or secrets from email, chat, or browser developer tools often includes hidden spaces.

Symptoms: Error [10.3] - 401 Unauthorized every attempt

Prevention:

# Paste value into Notepad first
# Check for leading/trailing spaces
# Copy from Notepad without spaces

Mistake #2: Using webClient ID Instead of NodiniteInstallationClient ID

Problem: The Installation Client's Client ID is set to the webClient's Application (client) ID by mistake. The Web Client group has its own, separate Client ID field for that value.

Symptoms: Error [10.3] - 401 Unauthorized; webClient app permissions insufficient

Prevention:

• webClient → Used for interactive web users
• NodiniteInstallationClient → Used for automated installation (what you need here)

Mistake #3: Skipping Admin Consent

Problem: Configuration looks correct but token claims are missing.

Symptoms: Error [10.4] - Required claim missing

Prevention:

• After adding API permissions, always click Grant admin consent for [Tenant Name]
• Wait 1-2 minutes for the token claims to update in Azure AD

Mistake #4: Wrong App Role Name in Claims

Problem: Installation Client Claims VALUE field contains description instead of the actual value.

Symptoms: Error [10.4] - Required claim value not found

Example (Wrong):

KEY: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
VALUE: Application permission for Nodinite installation

Example (Correct):

KEY: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
VALUE: AppRole_WebApi_all

Mistake #5: Scopes Don't Match webApi Application ID

Problem: Installation Client Scopes references wrong webApi ID.

Symptoms: Error [10.4] - Required scope not satisfied

Prevention:

• Always use the Application (client) ID from webApi > Overview
• Verify it's the 36-character GUID format
• Include .default suffix

Mistake #6: Installation Client Secret Expired

Problem: Secret was created 24 months ago and has now expired.

Symptoms: Intermittent Error [10.3] - suddenly fails after passing for weeks/months

Prevention:

• Set secret expiry to match your rotation policy (e.g., 12 months)
• Calendar reminder to regenerate 30 days before expiry
• Regenerate: Azure AD > App registrations > NodiniteInstallationClient > Certificates & secrets > + New client secret

Mistake #7: Using Tenant Name Instead of Tenant ID in Discovery URL

Problem: Discovery URL includes human-friendly tenant name instead of GUID.

Symptoms: Error [10.3] - 404 Not Found or 400 Bad Request

Example (Wrong):

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration

Example (Correct):

https://login.microsoftonline.com/a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6/v2.0/.well-known/openid-configuration

Prevention:

• Use the Directory (Tenant) ID from Azure AD > Overview (36-character GUID)

Debugging Tips

Enable Detailed Logging

If errors aren't clear, enable more verbose logging:

1. Before running installation, set environment variable:

   $env:NODINITE_INSTALLATION_DEBUG = $true
   

2. Run installation again.
3. Check logs at: C:\Installation\Nodinite7-DEV-Installation-Package_7.x\InstallationScripts\CommonScripts\userInputValidation-functions.ps1 output
4. Look for HTTP status codes and response body details.

Test Token Generation Manually

Verify the Installation Client can obtain tokens:

# Install REST client if needed
Install-Module -Name RestSharp -Force

# Set variables
$tenantId = "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6"  # Your Directory (Tenant) ID
$clientId = "f1e2d3c4-b5a6-7890-abcd-ef1234567890"  # NodiniteInstallationClient ID
$clientSecret = "your-secret-value-here"
$webApiId = "d731e991-1234-5678-90ab-cdef12345678"  # webApi Application ID

# Build token request
$tokenUri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"
$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = "api://$webApiId/.default"
}

# Request token
try {
    $response = Invoke-RestMethod -Uri $tokenUri -Method POST -Body $body
    Write-Host "✅ Token obtained successfully!"
    Write-Host "Token claims:"
    $decodedToken = $response.access_token | ConvertFrom-Json
    $decodedToken | ConvertTo-Json
} catch {
    Write-Host "❌ Token request failed:"
    Write-Host $_.Exception.Message
}

Review Azure AD Application Permissions

Sometimes permissions get removed or reset:

1. Azure Portal > Microsoft Entra ID > App registrations > NodiniteInstallationClient.
2. Go to API permissions.
3. Verify:
   • ✅ AppRole_WebApi_all is present
   • ✅ Status shows Granted for [Tenant Name]
   • ✅ No warning icons
4. If anything is missing:
   • Delete the permission (if incorrect)
   • Add it again
   • Grant admin consent

Check Certificate/Key Configuration

If using certificate-based authentication instead of secrets:

1. Verify certificate is installed in LocalMachine > Personal on the server
2. Verify certificate private key is readable by the service account
3. Use PowerShell to test:

   Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Thumbprint -eq "your-thumbprint" }
   

Next Steps

Once Error [10.3] or [10.4] is resolved:

1. Retry the installation wizard – Should proceed to Tier 3
2. Monitor the rest of pre-flight validation – Additional checks may follow
3. Verify successful connection – After installation, test Web API access with your Installation Client credentials
4. Plan secret rotation – Set calendar reminder to regenerate client secret before expiry

Related Topics

• Install Nodinite v7 – OpenID Connect
• Register Nodinite Applications in Azure AD (Entra ID) with OpenID Connect
• OAuth Security and Compliance Reference
• Managing the Web API – Code samples for OAuth 2.0 client credentials flow