docs: document Keycloak session reuse behavior and password-grant session growth caveat

[Copilot]

Users on the resource-owner password grant have observed Keycloak sessions accumulating unbounded over time (#309), even though the provider caches and reuses its Keycloak client per ProviderConfig. The root cause lives upstream in terraform-provider-keycloak's token-refresh path, which isn't something this repo can fix directly, but the behavior and workaround weren't documented anywhere for users hitting it.

• ProviderConfig reference

  • New "Authentication Sessions" section explaining client/session caching and pooling per ProviderConfig
  • Documents that password-grant credentials re-authenticate on every access-token expiry, creating a new Keycloak session each time
  • Recommends the Client Credentials Grant as the unaffected alternative

• Troubleshooting reference

  • New "Growing Number of Keycloak Sessions" entry with symptom, cause, and workaround, cross-linked to the ProviderConfig section

• Generated docs

  • Regenerated llms.txt / llms-full.txt to stay in sync with the content changes

[Breee]

Needs in Person verification

[Breee]

@copilot build me multiple test scenarios that i can validate locally. For this Provider and for opentofu hcl so I can Compare them. In Addition tooling to Check keycloak Sessions

[Copilot]

@copilot build me multiple test scenarios that i can validate locally. For this Provider and for opentofu hcl so I can Compare them. In Addition tooling to Check keycloak Sessions

Added in commit fb2... (see dev/session-reuse-tests/):

• crossplane/scenario-password-grant and crossplane/scenario-client-credentials: ProviderConfig + resource manifests for this provider.
• opentofu/scenario-password-grant and opentofu/scenario-client-credentials: equivalent HCL using the same terraform-provider-keycloak dependency, plus scripts/run-apply-loop.sh to simulate repeated reconciliation with tofu apply.
• scripts/check-sessions.sh: queries the Admin REST API for active session counts per user/client (with --watch/--json options) so you can compare session growth across scenarios.
• scripts/setup-client-credentials-client.sh: bootstraps the service-account client needed for the client-credentials scenarios.

README.md in that directory walks through all four scenarios end-to-end. Also linked from the troubleshooting docs.