docs: clarify organization tenancy, IdP-based security boundary, and access model#1078
Open
marblom007 wants to merge 1 commit into
Open
docs: clarify organization tenancy, IdP-based security boundary, and access model#1078marblom007 wants to merge 1 commit into
marblom007 wants to merge 1 commit into
Conversation
…access model Make explicit that identity, access, and authorization in Layer5 Cloud are decided by a combination of three independent mechanisms rather than by organization membership alone: - the organization's connected identity provider (authentication; shared across orgs or brought per-org via BYOC), - org-scoped keys -> keychains -> roles (authorization, evaluated per (user, organization)), and - resource-access mappings that deliberately cross org boundaries to share an individual resource. Add a Security Boundaries section to the Identity and Security overview and document the host-class (canonical / on-eTLD / off-eTLD) view in Identity Services, stating that the same identity provider source means the same security boundary. Tie the keys, organizations, and white-labeling pages into the same model via cross-references. Signed-off-by: Lee Calcote <lee.calcote@layer5.io>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
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.
|
|
||
| **The organization is the unit of tenancy and the core security boundary.** Everything else — teams, workspaces, roles, keychains, keys — composes on top of the organization. Resources, billing, and access control are isolated per organization. | ||
|
|
||
| **From the authorization perspective, an organization context is itself a boundary.** Because keys, keychains, and roles are evaluated per (user, organization), a user acting in the context of one organization has an independently-scoped set of capabilities from the same user acting in another — including when those organizations are reached through different per-organization subdomains. Operating "inside" one organization's subdomain does not carry a user's permissions from another organization with them. |
Contributor
There was a problem hiding this comment.
Adverbs ending in '-ly' (such as 'independently') should not be hyphenated to the participles or adjectives they modify. It is grammatically correct to write 'independently scoped' without a hyphen.
Suggested change
| **From the authorization perspective, an organization context is itself a boundary.** Because keys, keychains, and roles are evaluated per (user, organization), a user acting in the context of one organization has an independently-scoped set of capabilities from the same user acting in another — including when those organizations are reached through different per-organization subdomains. Operating "inside" one organization's subdomain does not carry a user's permissions from another organization with them. | |
| **From the authorization perspective, an organization context is itself a boundary.** Because keys, keychains, and roles are evaluated per (user, organization), a user acting in the context of one organization has an independently scoped set of capabilities from the same user acting in another — including when those organizations are reached through different per-organization subdomains. Operating "inside" one organization's subdomain does not carry a user's permissions from another organization with them. |
|
|
||
| **From the authorization perspective, an organization context is itself a boundary.** Because keys, keychains, and roles are evaluated per (user, organization), a user acting in the context of one organization has an independently-scoped set of capabilities from the same user acting in another — including when those organizations are reached through different per-organization subdomains. Operating "inside" one organization's subdomain does not carry a user's permissions from another organization with them. | ||
|
|
||
| **From the host perspective, the authentication boundary is set by the connected identity provider — not by the shape of the URL.** Layer5 Cloud organizations may be reached on the canonical host, on a custom subdomain that sits under the same parent (base) domain as that canonical host, or on a fully-custom domain on a different base domain. Across all of these: |
Contributor
There was a problem hiding this comment.
Adverbs ending in '-ly' (such as 'fully') should not be hyphenated to the adjectives they modify. It is grammatically correct to write 'fully custom' without a hyphen.
Suggested change
| **From the host perspective, the authentication boundary is set by the connected identity provider — not by the shape of the URL.** Layer5 Cloud organizations may be reached on the canonical host, on a custom subdomain that sits under the same parent (base) domain as that canonical host, or on a fully-custom domain on a different base domain. Across all of these: | |
| **From the host perspective, the authentication boundary is set by the connected identity provider — not by the shape of the URL.** Layer5 Cloud organizations may be reached on the canonical host, on a custom subdomain that sits under the same parent (base) domain as that canonical host, or on a fully custom domain on a different base domain. Across all of these: |
|
|
||
| The canonical host and on-eTLD custom hosts typically draw on the shared, central identity provider, so organizations reached through them are within one shared authentication boundary. An organization with its own (BYOC) identity provider is its own boundary, no matter how its host is named. The DNS shape of the host is not the boundary — the identity provider behind it is. | ||
|
|
||
| This is the authentication (host-class) view of the boundary. It composes with the **authorization** view — where each organization context independently scopes what a user is permitted to do via [keys, keychains, and roles](/cloud/concepts/identity-and-security/keys/) — and with **granular** resource-access sharing that can cross organizations. For the complete picture of how these layers fit together, see [Identity and Security → Security Boundaries](/cloud/concepts/identity-and-security/#security-boundaries). |
Contributor
There was a problem hiding this comment.
Linking the entire phrase 'keys, keychains, and roles' to the keys page is misleading since keychains and roles have their own dedicated documentation pages. Linking each term individually to its respective page provides a much better user experience and more precise cross-references.
Suggested change
| This is the authentication (host-class) view of the boundary. It composes with the **authorization** view — where each organization context independently scopes what a user is permitted to do via [keys, keychains, and roles](/cloud/concepts/identity-and-security/keys/) — and with **granular** resource-access sharing that can cross organizations. For the complete picture of how these layers fit together, see [Identity and Security → Security Boundaries](/cloud/concepts/identity-and-security/#security-boundaries). | |
| This is the authentication (host-class) view of the boundary. It composes with the **authorization** view — where each organization context independently scopes what a user is permitted to do via [keys](/cloud/concepts/identity-and-security/keys/), [keychains](/cloud/concepts/identity-and-security/keychains/), and [roles](/cloud/concepts/identity-and-security/roles/) — and with **granular** resource-access sharing that can cross organizations. For the complete picture of how these layers fit together, see [Identity and Security → Security Boundaries](/cloud/concepts/identity-and-security/#security-boundaries). |
Contributor
There was a problem hiding this comment.
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. |
| On a fully-custom domain **without** its own identity providers, the Google and GitHub buttons are **hidden** on the login and sign-up screens — they would otherwise lead to a sign-in that cannot complete. **Email-and-password sign-in and sign-up both remain fully available** — the **Log In / Sign Up** toggle stays visible, so new users can still register and existing users can still sign in. Only the social buttons are hidden. They reappear automatically once your organization configures its own identity providers. See [Identity Services](/cloud/guides/self-hosted/planning/identity-services/) for what BYOC is and when it is required. | ||
| {{< /alert >}} | ||
|
|
||
| The same base domain / different base domain split above is not only about whether social buttons appear — it also marks an **authentication boundary**. Organizations that share an identity provider (the canonical host and on-eTLD custom subdomains that use the shared, central provider) sit within the same security boundary, while an organization that brings its own (BYOC) provider is a distinct one: **same identity provider source means the same security boundary**, regardless of how the host is named. See [Identity Services → The identity provider is the security boundary](/cloud/guides/self-hosted/planning/identity-services/#the-identity-provider-is-the-security-boundary) and [Identity and Security → Security Boundaries](/cloud/concepts/identity-and-security/#security-boundaries). |
Contributor
|
🚀 Preview deployment: https://layer5io.github.io/docs/pr-preview/pr-1078/
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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
#security-boundaries,#the-identity-provider-is-the-security-boundary,#social-sign-in-on-a-custom-domain); no customautoHeadingIDTypeis configured, so default GitHub-style slugs apply.{{< alert >}}).hugo serverrender 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).