docs: clarify organization tenancy, IdP-based security boundary, and access model

[marblom007]

Description

Clarifies the security / identity / tenancy model for Meshery Cloud (Layer5 Cloud) in the user-facing docs. The goal is to make explicit that identity, access, and authorization are decided by a combination of mechanisms — not by organization membership alone — and to answer the recurring question of whether per-organization subdomains are a security boundary.

The model now documented:

1. Organizations are the unit of tenancy and the core security boundary. Everything else composes on top of the organization.
2. Identity, access, and authorization come from three independent mechanisms:
   • Org-connected identity provider (authentication) — shared across organizations on the canonical host and on-eTLD custom subdomains, or brought per-organization via BYOC.
   • Keys -> keychains -> roles (generic authorization) — evaluated per (user, organization), so the same person has different capabilities in each organization.
   • Resource-access mappings (granular access) — deliberately cross organizational boundaries to share an individual resource; membership is not required.
3. Security boundary answers: an organization context is itself an authorization boundary; and from the host perspective, same identity provider source means the same security boundary — the DNS shape of the host is not the boundary, the identity provider behind it is.

Changed pages

• content/en/cloud/concepts/identity-and-security/_index.md — new "How Identity, Access, and Authorization Fit Together" and "Security Boundaries" sections.
• content/en/cloud/concepts/identity-and-security/organizations/_index.md — org named as the core security boundary; cross-org access reframed as deliberate resource-access mappings.
• content/en/cloud/concepts/identity-and-security/keys.md — clarifies effective keys are per (user, organization).
• content/en/cloud/guides/self-hosted/planning/identity-services.md — "The identity provider is the security boundary" section with the canonical / on-eTLD / off-eTLD host-class mapping.
• content/en/cloud/guides/self-hosted/white-labeling/_index.md — ties the same base domain / different base domain split to the authentication boundary, with cross-references.

This is documentation-only; no product behavior changes. The framing reflects the existing custom-domain / BYOC behavior already described on the Identity Services and white-labeling pages.

Test plan

• All cross-reference anchors verified to match generated Hugo heading slugs (#security-boundaries, #the-identity-provider-is-the-security-boundary, #social-sign-in-on-a-custom-domain); no custom autoHeadingIDType is configured, so default GitHub-style slugs apply.
• Added Markdown table is well-formed (consistent 4-column rows) and uses only shortcodes already present in these files ({{< alert >}}).
• Local hugo server render to eyeball the new sections and links (Hugo binary not available in the authoring environment; needs a reviewer with the site toolchain or the docs preview build).

[gemini-code-assist]

Code Review

This pull request updates the Layer5 Cloud documentation to clarify how identity, access, and authorization interact, explicitly defining security boundaries across authentication, authorization, and host perspectives. The review feedback suggests minor grammatical improvements by removing hyphens from adverb-adjective pairs (e.g., 'independently scoped' and 'fully custom') and recommends splitting a single combined link into individual, precise links for keys, keychains, and roles to improve documentation navigation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Copilot]

Pull request overview

This PR updates the Layer5 Cloud documentation to more explicitly describe the tenancy/security model, clarifying how authentication (IdP), authorization (keys/keychains/roles), and cross-organization sharing (resource-access mappings) compose—especially to address whether per-organization subdomains constitute a security boundary.

Changes:

• Adds new conceptual sections describing how identity/access/authorization fit together and clarifies “security boundary” definitions.
• Reframes organizations as the core security boundary and documents intentional cross-org sharing via resource-access mappings.
• Adds an “identity provider is the security boundary” explanation for self-hosted/custom-domain host classes and ties it into white-labeling guidance.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
content/en/cloud/concepts/identity-and-security/_index.md	Adds new sections explaining the layered model and security boundary framing.
content/en/cloud/concepts/identity-and-security/organizations/_index.md	Strengthens org-as-boundary language and explains cross-org access via resource-level sharing.
content/en/cloud/concepts/identity-and-security/keys.md	Clarifies that effective keys/permissions vary per (user, organization), linking back to boundary docs.
content/en/cloud/guides/self-hosted/planning/identity-services.md	Adds a host-class table and explicit IdP-based boundary explanation for BYOC and custom domains.
content/en/cloud/guides/self-hosted/white-labeling/_index.md	Connects base-domain split to authentication boundaries and cross-links into identity/security concept docs.

[github-actions]

PR Preview Action v1.6.3
Preview removed because the pull request was closed.
2026-06-05 23:20 UTC