fix: correct step numbering, clarify role mapping rules, and fix Okta/Entra doc copy errors

[impoiler]

Summary

Fixes several inaccuracies and inconsistencies in the Entra and Okta SSO setup documentation, including incorrect step numbering, a copy-paste error referencing Okta in the Entra guide, and outdated role mapping behavior descriptions.

Changes

• Clarified the Step 6 note in the Entra guide to inform users that configuring claims via the App Manifest JSON (Step 9) overrides UI-based token configuration
• Fixed step numbering in the Entra Bifrost configuration section (steps 5–7 renumbered to 4–6)
• Corrected a copy-paste error where "Okta claims" was written instead of "Entra claims" in the Entra attribute mappings section
• Consolidated the role mapping evaluation rules note into the bullet list for both Entra and Okta guides, removing the redundant <Note> block that incorrectly stated the first user to sign in receives Admin
• Updated the manifest troubleshooting reference from "Step 8" to "Step 9" in the Entra guide
• Fixed step numbering in the Okta user assignment section (step 4 renumbered to 3)
• Improved the alt text for the Okta configuration form image to be more descriptive
• Removed a misplaced "Click Save Configuration" step from the Okta attribute mappings section

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Review the rendered documentation pages for the Entra and Okta setup guides to confirm step numbering is correct, the role mapping evaluation rules are accurate, and no references to the wrong identity provider remain.

Breaking changes

• No

Related issues

Security considerations

None.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

Summary by CodeRabbit

• Documentation
  • Clarified claim mapping configuration options for Microsoft Entra setup (UI vs. App Manifest, with manifest as source of truth)
  • Added explicit verification and confirmation steps before enabling provider configuration
  • Corrected Attribute Mappings section to reference Entra claims
  • Simplified role assignment behavior: unmatched users are denied login
  • Enhanced Okta role mapping documentation to specify highest-privilege role assignment when multiple rules match

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates enterprise SSO setup documentation for Microsoft Entra and Okta. The Entra guide clarifies claim mapping configuration options and adds UI verification steps; it corrects attribute mapping references and simplifies evaluation rule descriptions. The Okta guide adjusts step numbering, refreshes screenshot alt text, and expands role assignment rule behavior when multiple mappings match.

Changes

Entra Setup Guide Updates

Layer / File(s)	Summary
Configuration steps clarification docs/enterprise/setting-up-entra.mdx	Step 6 is clarified that claim mappings can be set via UI or App Manifest JSON, with the manifest overriding UI-based token configuration. Step 10 adds explicit verification and enablement workflow steps before saving provider configuration. Attribute Mappings section is corrected to reference Entra claims instead of Okta claims.
Evaluation rules and troubleshooting updates docs/enterprise/setting-up-entra.mdx	Evaluation rules are rewritten to remove prior special-case explanation about default Admin/Viewer assignment and instead state that unmatched users are not allowed to log in. Troubleshooting guidance is updated to reference Step 9 (App Manifest) instead of Step 8 when confirming the optional roles claim is present.

Okta Setup Guide Updates

Layer / File(s)	Summary
Configuration step and evaluation rule updates docs/enterprise/setting-up-okta.mdx	Step 6 item "Click Save and Go Back" is renumbered from 4 to 3. Step 9 embedded image alt text is updated to describe the Bifrost Okta configuration form. Evaluation rules are expanded to clarify that when a user matches multiple role mapping rules, the highest-privilege role is assigned.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested reviewers

• akshaydeo

Poem

🐰 A doc review swift, a rabbit's delight,
Claims and roles now mapped just right,
Entra and Okta, both shining anew,
Clarity flows through each step they pursue,
Enterprise SSO—our work is complete! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main changes: correcting step numbering and fixing documentation copy errors in Okta/Entra guides.
Description check	✅ Passed	The description is well-structured with clear summary, detailed changes, appropriate type selection, and affected areas marked; it comprehensively documents the documentation fixes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 05-28-docs_entra_and_okta_docs_typo_fixes

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[impoiler]

• fix: correct step numbering, clarify role mapping rules, and fix Okta/Entra doc copy errors #3860 👈 (View in Graphite)
• feat: add MCP auth required error handling with inline banner and retry support #3856
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Confidence Score: 4/5

Safe to merge — all changes are documentation-only with no impact on runtime behaviour.

The fixes are accurate and improve clarity, but two small issues remain: the Entra guide retains an orphaned numbered step that the Okta guide correctly had removed, and both guides now contain a self-contradictory evaluation-rule bullet ('first match wins' alongside 'highest privilege for multiple matches') that could lead users to misconfigure their role mappings.

docs/enterprise/setting-up-entra.mdx — orphaned step and contradictory evaluation rule; docs/enterprise/setting-up-okta.mdx — same contradictory evaluation rule.

Important Files Changed

Filename	Overview
docs/enterprise/setting-up-entra.mdx	Fixed step numbering, corrected 'Okta claims' copy-paste error, updated Note text and manifest step reference — but leaves behind an orphaned '5. Click Save Configuration' item in the Attribute Mappings section, and the new evaluation-rule bullet contains a logical contradiction.
docs/enterprise/setting-up-okta.mdx	Fixed step numbering in user assignment section, improved image alt text, removed misplaced Save Configuration step, and updated evaluation rules — same logical contradiction introduced in the role mappings description as in the Entra guide.

_{Reviews (1): Last reviewed commit: "docs: entra and okta docs typo fixes" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/enterprise/setting-up-okta.mdx (1)

279-385: ⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Add required Web UI / API / config.json tabs to the Okta configuration section.

This MDX setup section is still single-path (“Using the Bifrost UI”) and does not include the required Web UI / API / config.json tab structure, so it currently misses the docs standard for provider configuration pages.

As per coding guidelines: "docs/**/*.mdx: Mintlify MDX documentation must have Web UI / API / config.json tabs; validate config.json examples against transports/config.schema.json".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/enterprise/setting-up-okta.mdx` around lines 279 - 385, The Okta
provider doc under "Step 9: Configure Bifrost" is missing the required tabbed
structure (Web UI / API / config.json); update this MDX to split the
configuration section into three tabs showing: 1) Web UI (existing step-by-step
UI instructions and screenshots), 2) API (example API payloads and endpoints for
creating/updating a provider), and 3) config.json (a JSON config example
containing keys like issuerUrl, authServerType, clientId, clientSecret,
audience, attributeRoleMappings, attributeTeamMappings,
attributeBusinessUnitMappings); ensure the config.json example validates against
transports/config.schema.json and mention authServerType values (`org` |
`custom`) and audience behavior for each.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/enterprise/setting-up-okta.mdx`:
- Around line 279-385: The Okta provider doc under "Step 9: Configure Bifrost"
is missing the required tabbed structure (Web UI / API / config.json); update
this MDX to split the configuration section into three tabs showing: 1) Web UI
(existing step-by-step UI instructions and screenshots), 2) API (example API
payloads and endpoints for creating/updating a provider), and 3) config.json (a
JSON config example containing keys like issuerUrl, authServerType, clientId,
clientSecret, audience, attributeRoleMappings, attributeTeamMappings,
attributeBusinessUnitMappings); ensure the config.json example validates against
transports/config.schema.json and mention authServerType values (`org` |
`custom`) and audience behavior for each.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 29a39b24-609f-4015-8ba6-f2a1020dc2e6

📥 Commits

Reviewing files that changed from the base of the PR and between 9f27dc8 and d3ceaf6.

📒 Files selected for processing (2)

• docs/enterprise/setting-up-entra.mdx
• docs/enterprise/setting-up-okta.mdx

[akshaydeo]

Merge activity

• May 28, 5:16 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 28, 5:17 PM UTC: @akshaydeo merged this pull request with Graphite.