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

content/en/cloud/concepts/identity-and-security/_index.md

@@ -51,6 +51,30 @@ Access is granted through Role-Based Access Control (RBAC). Roles are assigned a
 
 ![permission](images/permissions.svg "image-center-shadow")
 
+## How Identity, Access, and Authorization Fit Together
+
+It is tempting to assume that organization membership alone decides what a user can see and do. It does not. Identity, access, and authorization in Layer5 Cloud are decided by a *combination* of three independent mechanisms that compose on top of the organization:
+
+* **Authentication — the organization's connected identity provider (IdP).** Each organization is connected to an identity provider that establishes *who* a user is. More than one organization can — and commonly does — share the same identity provider. An organization may instead **bring its own** identity provider (BYOC), in which case it authenticates against its own dedicated provider. See [Identity Services](/cloud/guides/self-hosted/planning/identity-services/).
+* **Generic authorization — keys → keychains → roles.** Permission [keys](/cloud/concepts/identity-and-security/keys/) roll up into [keychains](/cloud/concepts/identity-and-security/keychains/), which are assigned to [roles](/cloud/concepts/identity-and-security/roles/), which are assigned to users. This decides *what operations* a user may perform — and it is evaluated per organization. The same person can hold different roles, and therefore a different effective set of capabilities, in each organization they belong to.
+* **Granular access — resource-access mappings.** A specific resource (for example, a single design) can be shared with an individual user. These mappings grant access to that one resource and **deliberately cross organizational boundaries**: a user does not need to be a member of an organization to open a resource in it when a mapping grants that access. This is by design — it is what makes cross-organization collaboration possible.
+
+The practical consequence is that the same human can be a member of several organizations and have a *different* set of capabilities in each, while also being able to reach individual shared resources in organizations they do not belong to at all.
+
+## Security Boundaries
+
+Because identity and authorization are layered, "where is the boundary?" has two complementary answers, depending on which layer you mean.
+
+**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.
+
+**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:
+
+> **Same identity provider source means the same security boundary.**
+
+Organizations that share an identity provider — typical for the canonical host and for custom subdomains that use the shared, central provider — sit within the *same* authentication boundary. An organization that brings its own identity provider (BYOC) is a *distinct* authentication boundary, regardless of how its host is named. The DNS shape of the host is not the boundary; the identity provider behind it is. See [Identity Services](/cloud/guides/self-hosted/planning/identity-services/) and [Social sign-in on a custom domain](/cloud/guides/self-hosted/white-labeling/#social-sign-in-on-a-custom-domain) for how this plays out across host types.
+
 ## Key Management and Tokens
 
 Beyond structural roles, Layer5 Cloud uses cryptographic and session-based security:

content/en/cloud/concepts/identity-and-security/keys.md

@@ -21,6 +21,8 @@ For instance, consider a system shipped default key `Create Organization`, which
 
 {{< /alert >}}
 
+Because every key is evaluated in the context of an organization, a user's *effective* set of keys can — and will — differ from one organization to another. The same person holds whatever capabilities their role(s) grant them **within each specific organization**, so being able to perform an action in one organization implies nothing about the same action in another. This is why an organization context is itself an authorization boundary. For how this fits with authentication and cross-organization resource sharing, see [Identity and Security → Security Boundaries](/cloud/concepts/identity-and-security/#security-boundaries).
+
 ### Keys Types
 
 Generally, there are four types of keys:

content/en/cloud/concepts/identity-and-security/organizations/_index.md

@@ -10,7 +10,7 @@ aliases:
 
 ---
 
-Organizations are the basic unit of multi-tenancy inside of Layer5 Cloud. Organizations can have any number of teams. Teams can have any number of users. Users can belong to any number of teams. Users may belong to any number of organizations.
+Organizations are the basic unit of multi-tenancy — and the core security boundary — inside of Layer5 Cloud. Everything else (teams, workspaces, roles, keychains, and keys) composes on top of the organization, and resources, billing, and access control are isolated per organization. Organizations can have any number of teams. Teams can have any number of users. Users can belong to any number of teams. Users may belong to any number of organizations.
 
 Outside of grouping users together, teams offer control access to workspaces and to workspace resources such as environments and managed and unmanaged connections
 
@@ -54,6 +54,12 @@ Stellar Dynamics is a separate tenant of Constellation Cloud and an enterprise c
 
 Users of one organization may be granted access to resources (workspaces, designs) in another organization. Entitlements are org-scoped: the permissions a user has in Orbital Labs do not automatically apply in Stellar Dynamics, and vice versa.
 
+Cross-organization access works through **resource-access mappings** — a grant attached to an individual resource (such as a single design) that names the user it is shared with. These mappings **deliberately cross the organization boundary**: a user does *not* need to be a member of an organization to open a resource that has been shared with them there. For example, when Maya at Orbital Labs shares the `stellar-saas-platform` design with Marcus at Stellar Dynamics, Marcus can open that one design even though he is not a member of Orbital Labs. This is intentional — it is the mechanism that makes cross-org collaboration possible — and it is distinct from organization membership and from the org-scoped roles described below. Sharing a single resource grants access to *that resource only*; it does not make the recipient a member of the organization or grant them any of its other resources.
+
+{{< alert type="info" >}}
+Identity and authorization are decided by a combination of mechanisms, not by organization membership alone. For how the connected identity provider, org-scoped roles, and resource-access mappings fit together — and what counts as a security boundary — see [Identity and Security → Security Boundaries](/cloud/concepts/identity-and-security/#security-boundaries).
+{{< /alert >}}
+
 {{< alert type="info" >}}
 See [Meet Five and the Cast](/cloud/getting-started/meet-five) for the full narrative reference, including team structure and workspace inventory.
 {{< /alert >}}

content/en/cloud/guides/self-hosted/planning/identity-services.md

@@ -42,6 +42,25 @@ Whether BYOC is *optional* or *required* depends on your organization's [custom
 
 On a fully-custom domain **without** BYOC, the Google and GitHub buttons are hidden on the login and sign-up screens. 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; configuring the organization's own identity providers restores them on that domain.
 
+### The identity provider is the security boundary
+
+When you are reasoning about which organizations sit inside the *same* authentication boundary, look at the connected identity provider — not at the name or DNS shape of the host:
+
+> **Same identity provider source means the same security boundary.**
+
+Organizations that share an identity provider sit within the same authentication boundary; an organization that brings its own provider (BYOC) is a distinct authentication boundary. This holds regardless of which *class* of host an organization is reached on:
+
+| Host class | Example | Identity provider it uses | Authentication boundary |
+| --- | --- | --- | --- |
+| **Canonical host** | `cloud.layer5.io` | The deployment's shared, central provider | The shared boundary |
+| **On-eTLD custom host** (a subdomain under the same base domain as the canonical host) | `partner.layer5.io` on a `cloud.layer5.io` deployment | The same shared, central provider | The **same** shared boundary as the canonical host |
+| **Off-eTLD custom host** (a fully-custom domain on a different base domain) | `meshery.yourcompany.com` pointed at `cloud.layer5.io` | The organization's own (BYOC) provider | A **distinct** boundary |
+| **Any host, with BYOC** | any of the above, after configuring BYOC | The organization's own dedicated provider | A **distinct** boundary |
+
+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](/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).
+
 {{< alert type="info" >}}
 For the custom-domain setup walkthrough and the on-eTLD vs. off-eTLD distinction, see [White-labeling → Social sign-in on a custom domain](/cloud/guides/self-hosted/white-labeling/#social-sign-in-on-a-custom-domain).
 {{< /alert >}}

content/en/cloud/guides/self-hosted/white-labeling/_index.md

@@ -194,6 +194,8 @@ Whether social sign-in (Google and GitHub) works on a custom domain depends on h
 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 authentication boundary, while an organization that brings its own (BYOC) provider is a distinct authentication boundary: **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).
+
 ## Frequently asked questions about white labeling
 
 <details>