- 6 minutes to read

Token Claims Validation Failed for InstallationClient (Error 10.4)

Tip

For comprehensive troubleshooting of both Error [10.3] and Error [10.4], including common mistakes and debugging tips, see Troubleshooting OAuth 2.0 Validation Failures.

When a Nodinite v7 Environment uses OAuth2 mode, the installer CLI (Step 7) runs a pre-flight validation before it changes the server. Error [10.4] has two forms, required scope not satisfied and required claim missing, and both point to the installation client's App Roles, scopes, or claims. It may stop with a VALIDATION FAILED message and one or both of these errors:

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

You may also see a preceding warning:

WARNING: [10.3] No InstallClientId/InstallClientSecret values were provided in agent
         configuration. Skipping live OAuth2 client_credentials token validation.

Why This Happens

Check [10.4] verifies that the Installation Client Scopes and Installation Client Claims from the Portal Step 2: Auth are set correctly. If either is empty or misconfigured, the CLI aborts with VALIDATION FAILED.

# Error Message Root Cause
1 Required scope 'api://.../.default' not satisfied The Installation Client Scopes field is empty or contains the wrong value
2 Required claim '…/claims/role' is missing The Installation Client Claims key/value pair is missing or incorrect

Even when both fields are correct, the installation fails at runtime if admin consent hasn't been granted for the AppRole_WebApi_all application permission in Entra ID. The [10.3] warning means the CLI got no installation client secret, so it skipped the live token test and only the configuration check ran; a consent problem then surfaces later in the installation. Pass the secret at the CLI prompt or with --oauth2-agentinstall-secret to run the live test; see Client Secrets.

How the Role Claim Reaches the Token

flowchart LR Role["fa:fa-id-badge App role AppRole_WebApi_all
on webApi"] --> Permission["fa:fa-key Application permission
on NodiniteInstallationClient"] Permission --> Consent{"Admin consent
granted?"} Consent -->|"No"| Missing["roles claim missing
Error 10.4"] Consent -->|"Yes"| Token["fa:fa-ticket Version 2 token
roles: AppRole_WebApi_all"] Token --> Check{"Matches Scopes
and Claims in the Portal?"} Check -->|"No"| Mismatch["Error 10.4"] Check -->|"Yes"| Ok["Pre-flight check passes"] style Role fill:#9E59BB style Permission fill:#9E59BB style Missing fill:#c33d34 style Mismatch fill:#c33d34 style Token fill:#2678BD style Ok fill:#93d16d

Purple nodes are what you configure in Entra ID (sections 1.3.1 and 3.2 of the app registration guide), blue is the token Entra ID issues to the installation client, red marks the two places where Error [10.4] arises, and green is a passing check against the Installation Client Claims.

How to Fix

Work through the checklist below. Most cases are resolved by completing steps 1–3.

Step 1: Verify the Installation Client Scopes Field

In the Portal, on the Auth step, go to OAuth2 settings → Installation Client → Installation Client Scopes (see Installation Client Scopes) and confirm the value is api://<webApi-client-id>/.default, with the Application (client) ID of your webApi app registration, for example:

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

The .default suffix instructs Entra ID to include all application permissions that have been granted admin consent for the client. If this field is blank or contains only scopes like openid or profile, the scope check fails.

Step 2: Verify the Installation Client Claims Fields

In the Portal, on the Auth step, go to OAuth2 settings → Installation Client → Installation Client Claims (see Installation Client Claims) and confirm:

Field Required Value
Key http://schemas.microsoft.com/ws/2008/06/identity/claims/role
Value AppRole_WebApi_all

This tells Nodinite which claim in the access token identifies the installation client as an authorized daemon. If the key is missing or uses a shortened form (e.g., roles) the validation fails.

In the Microsoft Entra admin center, confirm that admin consent has been granted for the AppRole_WebApi_all application permission on the NodiniteInstallationClient app registration.

  1. Navigate to Microsoft Entra ID > App registrations > NodiniteInstallationClient.
  2. Select API permissions from the left menu.
  3. Confirm AppRole_WebApi_all is listed under Configured permissions.
  4. Check the Status column — it must show Granted for [Your Tenant].
  5. If the status shows Not granted, click Grant admin consent for [Your Tenant Name] and confirm.

Warning

Granting tenant-wide admin consent needs an administrator role that is allowed to grant it, such as Global Administrator or Privileged Role Administrator. If you don't see the Grant admin consent button, contact your Entra ID administrator.

Without admin consent, Entra ID doesn't include the AppRole_WebApi_all role in the access token, even if all Portal settings are correct. The roles claim is absent and Nodinite denies the request.

Step 4: Verify the Application Permission Exists

In some cases the application permission was never added to the NodiniteInstallationClient. Confirm it is configured:

  1. Navigate to Microsoft Entra ID > App registrations > NodiniteInstallationClient > API permissions.
  2. Check that AppRole_WebApi_all is listed under Configured permissions with type Application.
  3. If it is missing, add it:
    • Click + Add a permission > My APIs > webApi.
    • Select Application permissions (not Delegated).
    • Tick AppRole_WebApi_all and click Add permissions.
    • Grant admin consent (see Step 3).

If the app role itself is missing on webApi, create it first as in section 1.3.1.

Step 5: Verify requestedAccessTokenVersion on webApi

The NodiniteInstallationClient uses the client credentials flow. Entra ID issues a v2 token only when the receiving API (webApi) declares version 2. With version 1 tokens, the roles claim format differs and validation may fail.

  1. Navigate to Microsoft Entra ID > App registrations > webApi > Manifest.
  2. Find "requestedAccessTokenVersion" and confirm it is set to 2.
  3. If missing or set to null / 1, update it to 2 and click Save. See section 1.6.

Verification After Fixing

Rerun the pre-flight check with the CLI validate command (see Step 7). A successful check [10.4] looks like:

[10.4] INFO: InstallationClient token claims validation passed.

To inspect the token's aud, ver, and roles claims yourself, use the script in Test Token Generation Manually. If you still see errors, collect the full CLI output and contact Nodinite Support.

Quick Reference Checklist

  • ✅ Installation Client Scopes = api://<webApi-client-id>/.default
  • ✅ Installation Client Claims Key = http://schemas.microsoft.com/ws/2008/06/identity/claims/role
  • ✅ Installation Client Claims Value = AppRole_WebApi_all
  • ✅ AppRole_WebApi_all application permission added to NodiniteInstallationClient
  • ✅ Admin consent granted for AppRole_WebApi_all
  • ✅ requestedAccessTokenVersion = 2 in the webApi manifest

Next Steps