Skip to content

docs(enterprise): draft Okta SAML integration guide - #960

Open
rajshah4 wants to merge 15 commits into
mainfrom
codex/okta-saml-integration-guide
Open

rajshah4 wants to merge 15 commits into
mainfrom
codex/okta-saml-integration-guide

Conversation

@rajshah4

Copy link
Copy Markdown
Member

Summary

Add an Okta SAML guide under Enterprise → SAML SSO, covering administrator app/group setup, required profile attributes, deployment through the shared SAML guide, multi-user verification, and the separate administrator and user steps for GitHub access. Explain the Okta→Keycloak SAML and Keycloak→OpenHands OIDC protocol boundaries. Include the tested claims screenshot and link the page from the SAML overview and navigation.

Draft only — do not merge or publish until the release and validation gates below are met. The page retains an explicit draft warning. No supported minimum fixed release has been established, and it does not document unreleased enforcement flags or manual Kubernetes repairs as customer setup.

Dependencies and Merge Gates

  • Release the SAML certificate transport fix: fix(keycloak): preserve SAML certificate JSON during provisioning OpenHands-Cloud#1422.
  • Release the SAML profile import mappings: fix(keycloak): import enterprise SAML profile attributes OpenHands-Cloud#1423.
  • Record the minimum supported app/chart/Replicated package versions and validate clean managed provisioning without manual repairs.
  • Validate an organization-owned private GitHub App with an eligible employee, including private repository checkout/read and Connect after session expiry.
  • Validate the supported signing-certificate rotation/metadata-refresh procedure and provider-token renewal.
  • Resolve or explicitly scope existing-account migration and session/credential-revocation behavior with maintainers.
  • Replace the draft warning and confirm the final page in the Mintlify preview before publication.

The broader Okta-only requirement additionally depends on the matching application/chart candidates, OpenHands/enterprise#838 and OpenHands/OpenHands-Cloud#1424, plus live restart/redeployment/rollback validation. That work is deferred to the upgraded Helm evaluation; this PR explicitly says SAML enablement alone does not enforce Okta-only login. Maintainers may scope the first publication to SAML sign-in and separate Git access, keeping enforcement documented as unavailable until validated.

Evidence and Limits

Azure Replicated package 0.75.0 / app 1.68.0 / Keycloak 26.3.0 was tested with explicitly approved certificate/profile provisioning repairs. Two group-assigned users signed in, retained separate accounts/history, and were denied access to each other's private conversations. Removing an app assignment blocked the next sign-in but did not immediately revoke an existing OpenHands session.

One Okta-backed user connected a second GitHub identity and checked out/read a selected private repository. This required a temporary public, personally owned GitHub App and manual linking-only guard; both were rolled back, and the test installation was removed. It does not validate the candidate code, organization-owned private app rollout, token renewal, persistent enforcement, or an unmodified supported release. Internal logs, credentials, tenant identifiers, and live test URLs are excluded from this PR.

Validation

  • Opus 5.5 independently reviewed the guide and coverage; its editorial/protocol corrections are addressed. Review outcome: appropriate as a maintainer-review draft, not publication-ready.
  • Both changed MDX pages compile; navigation JSON parses and the new page occurs once in the Enterprise navigation.
  • Mintlify broken-links: no broken links found (Node 24 LTS).
  • git diff --check passes. The included screenshot was inspected for credentials and user/tenant details.
  • Full visual preview and supported-release acceptance remain merge gates above.

@mintlify

mintlify Bot commented Oct 17, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
all-hands-ai 🟢 Ready View Preview Oct 20, 2026, 5:32 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

openhands-release-bot Bot and others added 6 commits October 19, 2026 03:18
Syncs the Enterprise Cookbook tab with OpenHands/enterprise-cookbook@2fb0f51.

Every file under `cookbook/` and the Enterprise Cookbook tab in `docs.json` are generated from that repository. Change them there, not here; edits made directly in this repository are overwritten by the next sync.

_Opened automatically by the docs-publish workflow in OpenHands/enterprise-cookbook ([run](https://github.com/OpenHands/enterprise-cookbook/actions/runs/39214962875))._

Co-authored-by: openhands-release-bot[bot] <290150379+openhands-release-bot[bot]@users.noreply.github.com>
* docs: add tested Google Cloud Replicated quick start

* docs: split Enterprise quick start into AWS and Generic VM guides

* docs: add Azure Replicated quick start

* Correct quick-start sizing references and direct installation links

* Link directly to the Replicated installation skill

* Clarify validated Azure VM path after independent review

* docs: group Enterprise quick starts under VM Install
* docs: add AWS Bedrock gateway guide for Helm and Replicated

* docs: clarify adding Bedrock models in Replicated and Helm

* docs: clarify Bedrock Admin Console authentication fields

* Align Bedrock managed gateway profiles with provider guides
* docs: add Google Vertex AI and Gemini gateway guide

* Preserve measured validation and clarify supported configuration scope

* Use verified profile UI fields and tested organization API overrides

* State Google profile validation scope precisely

* Clarify Replicated Google credential distribution
* docs: update documentation for OpenHands v1.28.0

Add release notes page for Agent Canvas 1.28.0 and update the affected
docs based on the release review in #977.

- Add openhands/usage/agent-canvas/release-notes/v1.28.0.mdx and a
  docs.json navigation entry.
- secrets-settings: document agent-requested secrets (inline chat card,
  value never shown, status-only result, local-backend scope).
- prebuilt-automations: document the six templates hidden on self-hosted
  cloud backends.
- conversations: document the missing-runtime archived presentation and
  drop the removed overview-drawer panels.
- plugins: document the Local launch plugin-parameter limitation.
- application-settings: add the supported UI languages, including Bahasa
  Indonesia.

Co-authored-by: openhands <openhands@all-hands.dev>

* Remove self-hosted recommended automations section

Removed section about recommended automations on self-enterprise when inside agent canvas section

---------

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Devin <devinvinson@gmail.com>
* docs: link GKE guide to Google LLM gateway setup

* docs: cross-link AWS and Azure installation gateway guides
@jpelletier1
jpelletier1 self-requested a review October 20, 2026 17:12
@jpelletier1
jpelletier1 marked this pull request as ready for review October 20, 2026 17:12
@ak684

ak684 commented Oct 20, 2026

Copy link
Copy Markdown
Contributor

Holding for the release. Before taking this out of draft:

  1. The description says the page keeps a draft warning, but a6eddea removed it. Add a minimum-version notice.
  2. The GitHub Connect steps need the Connect fix in fix(auth): route SSO-first Git connections through the authenticated provider enterprise#838. Add it to the gate.
  3. This conflicts with docs(enterprise): document Google Workspace SAML for Helm and Replicated #964 and docs(enterprise): add Microsoft Entra ID SAML setup guide #967 on docs.json and the provider sentence in saml-sso.mdx; see the order suggested on docs(enterprise): clarify generic SAML setup and access management #965.
  4. Nit: recapture okta-claims.png; it shows a text-selection highlight and the cursor.

This branch was successfully deployed

1 active deployment
staging — 2ad59061 Deployed Oct 20, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants