docs: improve advanced sso page

[wvandeun]

Summary by cubic

Clarifies and restructures the Advanced SSO docs to explain group mapping workflows: map to existing groups, auto-create from claims (regex filters, multiple patterns, per-login cap, audit events, provenance), and default group fallback. Adds IdP group-claim setup steps, log examples, a membership-resolution overview, and sets toc_max_heading_level: 4.

^{Written for commit 9f708f9. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 1 file

Confidence score: 4/5

• This PR looks safe to merge overall, but there is a minor documentation accuracy issue in docs/docs/deploy-manage/user-management/sso/advanced-sso.mdx.
• The summary currently states all three group-mapping approaches require IdP group claims, which conflicts with the documented default-group path intended for setups without group claims.
• Because the issue is low severity (3/10) and limited to wording, risk is minimal, but it could still mislead SSO configuration decisions for readers.
• Pay close attention to docs/docs/deploy-manage/user-management/sso/advanced-sso.mdx - ensure the summary distinguishes the no-group-claims default-group flow from claim-dependent mappings.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/docs/deploy-manage/user-management/sso/advanced-sso.mdx">

<violation number="1" location="docs/docs/deploy-manage/user-management/sso/advanced-sso.mdx:57">
P3: The new summary incorrectly says all three group-mapping approaches require IdP group claims, but the default-group path is explicitly for cases with no group claims.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The new summary incorrectly says all three group-mapping approaches require IdP group claims, but the default-group path is explicitly for cases with no group claims.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/deploy-manage/user-management/sso/advanced-sso.mdx, line 57:

<comment>The new summary incorrectly says all three group-mapping approaches require IdP group claims, but the default-group path is explicitly for cases with no group claims.</comment>

<file context>
@@ -47,13 +48,15 @@ oidc_providers = ["provider1", "provider2"]
+- **[Auto-create groups](#auto-create-groups-from-claims)** — let Infrahub create groups from the claims on first login.
+- **[Set a default group](#set-a-default-group)** — assign a fallback group when no claim maps to one.
+
+All three rely on your identity provider sending group information in the first place. Configure that first, then pick an approach. [How Infrahub resolves membership](#how-infrahub-resolves-membership) explains how the approaches interact on each login.
 
-### Step 1: Configure group claims in your identity provider
</file context>

Suggested change

	All three rely on your identity provider sending group information in the first place. Configure that first, then pick an approach. [How Infrahub resolves membership](#how-infrahub-resolves-membership) explains how the approaches interact on each login.
	Map-to-existing and auto-creation rely on your identity provider sending group information. You can also set a default group for users when no claim grants membership. Configure claims first, then pick an approach. [How Infrahub resolves membership](#how-infrahub-resolves-membership) explains how the approaches interact on each login.