Stirling PDF with Entra ID: preferred_username is null

Entra ID sign-in succeeds, but Stirling PDF then refuses access because an attribute such as preferred_username cannot be null. In the archived v3.2.2 report, the claim existed in the ID token but was absent from UserInfo. Only the actually reproduced parts of that report are used here as incident evidence. Q1

Distinguish the two information sources

Microsoft documents different information coverage for ID tokens and UserInfo. A claim visible in the token therefore need not appear in the UserInfo response, whose contents cannot be arbitrarily extended. Q3 Additional scopes or token claims are not a demonstrated repair until you know which source the failing code reads.

Compare the sign-in sequence

1. Preserve administrative access. Save the current configuration and a working administration path before changing SSO settings. A claim experiment should not lock out the entire organisation.
2. Record version and callback details. Capture Stirling version, provider name, issuer and registered redirect URL without secrets. Check the callback path exactly. An incorrect return URL is a different failure from a missing user attribute.
3. Identify the claim source. Using an authorised test account, locate the stage producing the null error. Compare claim names in the ID token and UserInfo separately. Avoid recording complete tokens. If temporary diagnostic logging is needed, protect the output and disable it again afterwards. Q2
4. Check supported configuration. Current Stirling documentation restricts useAsUsername values and explicitly excludes sub, upn and oid. Q2 Do not turn a proposed source-code change from an issue into an assumed available production setting.
5. Preserve account continuity. Before changing the identifying attribute, establish whether the same person will still map to the correct existing account. Successful login into a newly created account can make previous permissions or documents appear to have vanished.

Verify a bounded correction

Use configuration supported by the installed version or a vendor correction shown to apply to that version. Test sign-in, sign-out and repeat access for an authorised account. Also verify that an unauthorised test account does not gain unintended access. Disabling authentication is not an appropriate substitute for resolving the mapping failure.

For handoff, prepare version, sanitised configuration, claim names with their respective sources and the first meaningful error. Do not put client secrets, access tokens or real personal claim values into the contact form. Keep the earlier configuration available while evaluating the corrected mapping.

Frequently asked questions

Can I just set useAsUsername=sub?

The currently reviewed Stirling documentation does not permit that value. A code proposal is not necessarily a supported configuration option.

Does a claim in the ID token prove it is available everywhere?

No. What matters is the response the application actually processes at the failing step.

Describe your case