We need a much better documentation for configuring external OIDC

[zalanszak]

A more comprehensive and elaborate documentation is needed for configuring external oidc as it is very confusing for a lot of our customers: https://docs.camunda.io/docs/self-managed/setup/guides/connect-to-an-oidc-provider/

It would be great to have every configuration in one place (settings in the idp, mapping rule configs, audience configs and how they should match, helm values/env vars on the identity component, helm values/env vars on other components - most importantly connectors and Operate. Clarifying which env vars are corresponding which helm values in which components etc.

E.g. the env variable CAMUNDA_OPERATE_AUDIENCE on the Identity component is not documented anywhere, and this was needed to solve a customer issue: https://jira.camunda.com/browse/SUPPORT-24458

[akeller]

@FarkasRabai, this is quite a large chunk of work and would not be something DevEx could support on our own. Can you prioritize this against an Identity epic, or link it to an existing one?

Followed up on ask-identity.

[garima-camunda]

@FarkasRabai - I just wanted to add that customer's issue in SUPPORT-24458 is still not fully resolved. They have been facing issues at every step and it seems that some of those are due to missing/hard to find config properties. Support has been struggling to provide the guidance due to lack of proper docs.

[alexcorremans]

Another example: SUPPORT-24782

[akeller]

@FarkasRabai is this captured in a PDP epic? It seems to be generating regular feedback from support.