docs: add preferusernameclaim to property reference

[Ben-Sheppard]

Description

With the merge of camunda/camunda#39049 we introduced a new configuration option that allows the control of what token claim to prefer during principal extraction (username or client ID), this PR adds this configuration to the properties reference page as a start but in a later PR we need made this more visible when configuring (in our experience) MS entra.

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
• This is already available but undocumented and should be released within a week. (add available & undocumented label)
• This is on a specific schedule and the assignee will coordinate a release with the Documentation team. (create draft PR and/or add hold label)
• This is part of a scheduled alpha or minor. (add alpha or minor label)
• There is no urgency with this change (add low prio label)

PR Checklist

• The commit history of this PR is cleaned up, using {type}(scope): {description} commit message(s)

• My changes are for an upcoming minor release and are in the /docs directory (version 8.8).
• My changes are for an already released minor and are in a /versioned_docs directory.

• I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:
  • Engineering team review
  • Technical writer review via @camunda/tech-writers unless working with an embedded writer.

[github-actions]

👋 🤖 🤔 Hello, @Ben-Sheppard! Did you make your changes in all the right places?

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.8/.

• docs/self-managed/components/orchestration-cluster/core-settings/configuration/properties.md

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

[ThorbenLindhauer]

Thanks for preparing this. Please have a look at the comments. Are you planning to raise a second PR with the adjustment of https://docs.camunda.io/docs/next/self-managed/components/orchestration-cluster/identity/connect-external-identity-provider/#step-1-configure-the-oidc-client-id-claim or should it be included here?

[ThorbenLindhauer]

Order-wise, I suggest we put this below client-id-claim because this property directly relates to it (and username claim). In that sense, I'd also argue to make the order like this: username claim, client id claim, prefer username claim, group claim.

Lastly, I suggest we explain more specifically what this setting does, e.g.:

Determines if a token that contains both, the configured username claim and the configured client id claim, is treated as a user or a client. If set to true, it is treated as a user. If set to false, it is treated as a client.

(the explanation of the default value is redundant with the default value column, so I wouldn't repeat that.

[ThorbenLindhauer]

Same feedback as for the property-

[Ben-Sheppard]

Hey @ThorbenLindhauer - as discussed I added a new section (and revised another) to increase transparency around how we determine the principal and what the user can do to change that default flow.

[christinaausley]

Minor tweaks in my latest commit, but will let @ThorbenLindhauer have the final say 👍

[ThorbenLindhauer]

Thanks for working in the feedback. The properties reference looks fine now. I have some detailed feedback on the installation guide part.

[github-actions]

[prettier] _{reported by reviewdog 🐶}

camunda-docs/docs/self-managed/components/orchestration-cluster/core-settings/configuration/properties.md

Lines 653 to 667 in bb9753f

	| Property | Description | Default value |
	| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
	| `camunda.security.authentication.oidc.client-id` | The client ID for OIDC authentication. | |
	| `camunda.security.authentication.oidc.client-secret` | The client secret for OIDC authentication. | |
	| `camunda.security.authentication.oidc.issuer-uri` | The issuer URI for OIDC authentication. If set, the individual endpoints of your OIDC provider will be fetched from its [well-known configuration endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). In this case, any individually configured token, authorization, and JWKS URIs do not take effect. | |
	| `camunda.security.authentication.oidc.redirect-uri` | The URI for redirects from the OIDC provider to the Orchestration Cluster after user login. | `http://localhost:8080/sso-callback` |
	| `camunda.security.authentication.oidc.username-claim` | The JWT claim that identifies a user. Extracted from a token, this claim value becomes the user's username. This setting is evaluated on any token-based access, regardless of the underying OIDC/OAuth flow. | `sub` |
	| `camunda.security.authentication.oidc.groups-claim` | The JWT claim that contains a user's or client's groups. Expects an array of String values. If not set, groups can be managed in the Orchestration Cluster through its REST APIs. | |
	| `camunda.security.authentication.oidc.client-id-claim` | The JWT claim that identifies a client. Extracted from a token, this claim value becomes the clients's ID. This setting is evaluated on any token-based access, regardless of the underying OIDC/OAuth flow. | |
	| `camunda.security.authentication.oidc.prefer-username-claim` | Determines if a token that contains both, the configured username claim and the configured client id claim, is treated as a user or a client. If set to true, it is treated as a user. If set to false, it is treated as a client. | `false` |
	| `camunda.security.authentication.oidc.audiences` | Comma-separated list of audiences to validate in the OIDC token. | |
	| `camunda.security.authentication.oidc.scope` | Comma-separated list of scopes to request in the OIDC token. | `openid, profile` |
	| `camunda.security.authentication.oidc.jwk-set-uri` | Sets the OIDC provider's JWK Set URI explicitly. Only takes effect if `camunda.security.authentication.oidc.issuer-uri` is not set. | |
	| `camunda.security.authentication.oidc.authorization-uri` | Sets the OIDC provider's authorization URI explicitly. Only takes effect if `camunda.security.authentication.oidc.issuer-uri` is not set. | |
	| `camunda.security.authentication.oidc.token-uri` | Sets the OIDC provider's token URI explicitly. Only takes effect if `camunda.security.authentication.oidc.issuer-uri` is not set. | |

[github-actions]

[prettier] _{reported by reviewdog 🐶}

camunda-docs/docs/self-managed/components/orchestration-cluster/core-settings/configuration/properties.md

Lines 734 to 748 in bb9753f

	| Property | Description | Default value |
	| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_CLIENTID` | The client ID for OIDC authentication. | |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_CLIENTSECRET` | The client secret for OIDC authentication. | |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_ISSUERURI` | The issuer URI for OIDC authentication. If set, the individual endpoints of your OIDC provider will be fetched from its [well-known configuration endpoint](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). In this case, any individually configured token, authorization, and JWKS URIs do not take effect. | |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_REDIRECTURI` | The URI for redirects from the OIDC provider to the Orchestration Cluster after user login. | `http://localhost:8080/sso-callback` |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_USERNAMECLAIM` | The JWT claim that identifies a user. Extracted from a token, this claim value becomes the user's username. This setting is evaluated on any token-based access, regardless of the underying OIDC/OAuth flow. | `sub` |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_GROUPSCLAIM` | The JWT claim that contains a user's or client's groups. Expects an array of String values. If not set, groups can be managed in the Orchestration Cluster through its REST APIs. | |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_CLIENTIDCLAIM` | The JWT claim that identifies a client. Extracted from a token, this claim value becomes the clients's id. This setting is evaluated on any token-based access, regardless of the underying OIDC/OAuth flow. | |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_PREFERUSERNAMECLAIM` | Determines if a token that contains both, the configured username claim and the configured client id claim, is treated as a user or a client. If set to true, it is treated as a user. If set to false, it is treated as a client. | `false` |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_AUDIENCES` | Comma-separated list of audiences to validate in the OIDC token. | |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_SCOPE` | Comma-separated list of scopes to request in the OIDC token. | `openid, profile` |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_JWKSETURI` | Sets the OIDC provider's JWK Set URI explicitly. Only takes effect if `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_ISSUERURI` is not set. | |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_AUTHORIZATIONURI` | Sets the OIDC provider's authorization URI explicitly. Only takes effect if `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_ISSUERURI` is not set. | |
	| `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_TOKENURI` | Sets the OIDC provider's token URI explicitly. Only takes effect if `CAMUNDA_SECURITY_AUTHENTICATION_OIDC_ISSUERURI` is not set. | |

[christinaausley]

@Ben-Sheppard Looks like properties.md should also be applied to 8.8?

[ThorbenLindhauer]

Thanks, looks good to me.

As Christina mentions, you'll have to copy it into the 8.8 section, too.