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

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 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 Installation Client ID

In the Nodinite installation wizard:

1. Navigate to General → Installation 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 Nodinite installation wizard:

1. Navigate to General → 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 Nodinite installation wizard:

1. Navigate to General → 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: Installation Client ID accidentally set to webClient's Application (client) ID.

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][Register Azure AD Apps]
• OAuth Security and Compliance Reference
• Managing the Web API – Code samples for OAuth 2.0 client credentials flow