Support non-numeric OIDC principal ID claims in the default principal mapper

[zhang-arvin]

Fixes #5569

The default OIDC principal mapper assumed the configured ID claim is convertible to a Java long:

.map(id -> id instanceof Number number ? number.longValue() : Long.parseLong(id.toString()))

An identity provider that issues a non-numeric subject — Keycloak's sub is a UUID — therefore fails the
conversion, and the Keycloak integration example can only work by hard-coding principal_id = 0, which
collapses every user onto one principal in a real multi-user deployment.

Why this does not need an interface change

PrincipalMapper.mapPrincipalId already returns OptionalLong, and DefaultAuthenticator already falls
back to findPrincipalByName when the mapped ID is empty. The mapper was simply throwing instead of
yielding empty. Non-numeric and non-long-representable claims now yield empty (with a debug log) so the
principal resolves by name, while numeric claims — both Number and numeric String — keep byte-identical
behavior, including the existing rejection of values outside the long range.

What changed

• DefaultPrincipalMapper — tolerate non-numeric ID claims instead of throwing; numeric behavior unchanged.
• Javadoc on PrincipalMapper.mapPrincipalId and OidcTenantConfiguration#idClaimPath documenting the
  optional/non-numeric contract.
• DefaultPrincipalMapperTest — UUID-style claim, plus empty, non-numeric, short and overflow cases, and a
  UUID-to-name fallback test.

Verification

• ./gradlew format compileAll — clean (Java 21).
• :polaris-runtime-service:test --tests DefaultPrincipalMapperTest — 12 tests, 0 failures.

Notes

The issue asks for UUID/String principal IDs to be usable. This change makes such an IdP configuration work
by resolving the principal through its name claim rather than by extending the principal ID type; if
maintainers would rather thread a string principal identifier through the model, that is a larger change to
PrincipalEntity and the persistence layer and I am happy to follow a different direction.

[adutra]

@zhang-arvin As I explained in #5569, I don't think this goes in the right direction.

[adutra]

The ID claim path is optional. If no numerical ID claim exists, simply doesn't set the ID claim path at all.

[zhang-arvin]

You're right, and thanks for pointing back to #5569 — I had read the report but not your comment on it, which is the part that settles this. I've now read it: the ID claim path is optional and using Keycloak means leaving id-claim-path unset and matching principals by name, so the reported failure is a configuration problem rather than a defect in DefaultPrincipalMapper.

Closing this as not a fix for #5569. My apologies for the review noise.

One thing worth keeping from the attempt, only if you think it is worth its own change: the failure mode was a thrown Long.parseLong surfacing as an unmapped principal with no hint that a property was misconfigured. A clearer error or a startup warning when id-claim-path points at a non-numeric claim would have made the misconfiguration self-evident — but that is a suggestion, not something I am pushing into this PR.