[FEATURE] Override preferred_username mapping

[hermetic-charm]

Hi, thank you for this project! Would it be possible to use a claim other than preferred_username when mapping the user?

Use case: I am trying to use my Synology NAS as OIDC provider, it has a built-in package called SSO Server which can do this. Unfortunately, it does not provide preferred_username as a claim, instead it appears to use username.

From the well known URL for Synology NAS:

{
   "authorization_endpoint" : "https://nasexample.host/webman/sso/SSOOauth.cgi",
   "claims_supported" : [ "aud", "email", "exp", "groups", "iat", "iss", "sub", "username" ],
   "code_challenge_methods_supported" : [ "S256", "plain" ],
   "grant_types_supported" : [ "authorization_code", "implicit" ],
   "id_token_signing_alg_values_supported" : [ "RS256" ],
   "issuer" : "https://nasexample.host/webman/sso",
   "jwks_uri" : "https://nasexample.host/webman/sso/openid-jwks.json",
   "response_types_supported" : [ "code", "code id_token", "id_token", "id_token token" ],
   "scopes_supported" : [ "email", "groups", "openid" ],
   "subject_types_supported" : [ "public" ],
   "token_endpoint" : "https://nasexample.host/webman/sso/SSOAccessToken.cgi",
   "token_endpoint_auth_methods_supported" : [ "client_secret_basic", "client_secret_post" ],
   "userinfo_endpoint" : "https://nasexample.host/webman/sso/SSOUserInfo.cgi"
}

Note: There is no configuration possible on the Synology NAS side to, for example, change the claims. It is baked in, as-is.

I was able to in general get tinyauth working with the Synology NAS using the generic setup, however, I am not getting the username in tinyauth, example log line below:
tinyauth | 2025-09-23T20:36:27.459435476Z 2025-09-23T20:36:27Z DBG Got user user={"email":"someemail@host.com","groups":["group1","group2"],"name":"","preferred_username":""}

I am getting the email for this user, and I know in the docs tinyauth can generate a stand-in username based on the email however two points specific to the Synology NAS 1. A user's email can be blank and 2. A user's email is non-unique (i.e. on this system multiple users can be created with the same email)

Working Example: As an example of this working, I also setup Jellyfin using the community created SSO plugin also using the Synology NAS as OIDC provider. In their plugin they have the option to specify custom scopes as well as explicitly set which claim to use for the username. When I set the claim to username there, I can see the usernames coming through with that setup. Here is an example of how I setup the config there just as an example:

Possible enhancement: Maybe an environment variable could be added which overrides the preferred_username field to some custom value, like:
OAUTH_CUSTOM_USERCLAIM=username

[steveiliop56]

Hello,

I have decided against allowing custom claims in Tinyauth and instead support only the ones mentioned in the OpenID specification. This decision was made to avoid writing tons of OIDC provider specific code. The claims below are the ones that are supported by Tinyauth:

Member	Type	Description
name	string	End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.
preferred_username	string	Shorthand name by which the End-User wishes to be referred (e.g., janedoe, j.doe). Not guaranteed unique.
email	string	End-User's preferred email address. MUST conform to RFC 5322. Not guaranteed unique.

The groups claim is also used despite not being mentioned in the specification since it's used by the majority of the OIDC servers and even with it I had to write custom code because some providers just returned the groups as one string (e.g. "groups": "group1,group2") instead of an array (e.g. "groups":["group1","group2"]). I believe it would be interested to contact Synology and ask them about this decision. Ideally they should include the prefered_username claim too. Please let me know if you get a response from them. In the meantime, I am sorry for the inconvenience.

[steveiliop56]

Hmm although it could be possible to read the well known endpoint and try to do some claim mapping against a list of predefined ones. Would you like to create a feature request for using the claims_supported from the well known response to get the name, username and email from the user info endpoint?