Principal name and preferred_username conflict

[sberyozkin]

@FroMage has noticed an obvious conflict in the JsonWebToken#getName() Java Docs, where preferred_username is mentioned as a fallback:

https://github.com/eclipse/microprofile-jwt-auth/blob/master/api/src/main/java/org/eclipse/microprofile/jwt/JsonWebToken.java#L40

(Also, that JavaDoc needs to be synced with the spec text which mentions sub as the final fallback).

However the very same OIDC docs for preferred_username to which MP JWT links to says:

The RP MUST NOT rely upon this value being unique

which conflicts with the Returns the unique name of this principal. message in JsonWebToken#getName() Java Docs.

My proposal would be to deprecate preferred_username as a possible fallback from upn.

Or, given how long preferred_username has been around as a fallback from upn, instead fix the java docs and explain the principal name is not guaranteed to be unique and advise users get either upn or sub claims directly

[sberyozkin]

Given that JsonWebToken#getName is coming from Principal#getName which does not have a uniqueness constraint, simplest can be fix the JavaDocs not to require a unique name - it is impossible to enforce given that preferred_username fallback exists. Removing to enforce the uniqueness constraint does not seem reasonable as it would change the message of Principal#getName

[sberyozkin]

marking it as resolved by #332 for now