Refresh RBAC org-level defaults: add Organization-wide role settings page

content/docs/administration/access-identity/access-tokens.md

@@ -36,29 +36,9 @@ When using tokens, be mindful of the following security best practices:
 * Tokens can optionally be assigned an expiration period of up to two years, at which point the token will no longer be valid for any Pulumi operation. Expired tokens cannot be refreshed or reactivated. It's strongly recommended that you assign an expiration to your token to encourage token rotation and improve your organization's security posture.
 * Access tokens can create stacks if the organization's access management settings permit all members to do so, or if the token's assigned role includes the `stack:create` scope. Admin organization tokens always have this capability. The stack creator will automatically become its owner and will have all stack permissions, including deletion. See [RBAC](/docs/administration/access-identity/rbac/) for more on how org-wide settings and role scopes interact.
 
-## Access token permissions
-
-### Personal tokens
-
-Personal access tokens carry the same permissions as the user who created them. This includes all organization memberships, team memberships, and role assignments that apply to the user across every Pulumi Cloud organization they belong to.
-
-### Organization tokens
-
-Organization tokens act on behalf of the organization itself. Rather than mapping to a fixed set of capabilities, organization tokens derive their permissions from the [RBAC role](/docs/administration/access-identity/rbac/roles/) assigned to them at creation time. This means you can tailor the exact level of access an organization token has—from read-only access to a subset of stacks, to full administrative control—by assigning the appropriate role.
-
-Organization tokens that are assigned no explicit role receive the organization's [default member role](/docs/administration/access-identity/rbac/roles/). The token's access is automatically limited to the single organization it was created in, unlike a personal token which spans all of a user's organizations.
-
-### Team tokens
-
-Team tokens act on behalf of a specific team within the organization. A team token's effective permissions are determined by the [roles assigned to that team](/docs/administration/access-identity/rbac/teams/) at the time each request is evaluated. If a team's role assignments change, those changes are immediately reflected in what the team token can do.
-
-Team tokens are useful for CI/CD pipelines that should be scoped to only the resources a particular team manages, without requiring a personal token from any individual team member.
-
-For a detailed reference on how permissions are structured and evaluated, see [Role-Based Access Control (RBAC)](/docs/administration/access-identity/rbac/).
-
 ## Personal access tokens
 
-Personal access tokens have the same permissions as your Pulumi Cloud user. This includes your respective permissions for all Pulumi Cloud organizations in which your user is a member.
+Personal access tokens carry the same permissions as your Pulumi Cloud user. This includes all organization memberships, team memberships, and role assignments that apply to you across every Pulumi Cloud organization you belong to.
 
 ### Creating personal access tokens
 
@@ -142,7 +122,7 @@ Both token types continue to work. The admin/standard distinction maps directly
 
 ## OIDC issued tokens
 
-OIDC-issued access tokens generated in CI/CD workflows (such as GitHub Actions) do not receive admin privileges by default. To perform operations that require elevated access—such as creating or deleting stacks—you must explicitly request the admin scope when exchanging the OIDC token.
+OIDC-issued access tokens generated in CI/CD workflows (such as GitHub Actions) do not receive admin privileges by default. To perform operations that require elevated access—such as creating or deleting stacks—you must explicitly request the admin scope when exchanging the OIDC token. For how to register and configure an issuer for these tokens, see [OIDC Issuers](/docs/administration/access-identity/oidc-issuers/).
 
 For example:
 

content/docs/administration/access-identity/rbac/_index.md

@@ -13,59 +13,65 @@ menu:
     identifier: administration-access-identity-rbac
 ---
 
-Role-Based Access Control (RBAC) in Pulumi Cloud provides a flexible and secure way to manage access to your organization's resources. This allows you to exercise fine-grained control over who can access what resources in your organization and what actions they can perform.
+Role-Based Access Control (RBAC) in Pulumi Cloud controls who can access which resources in your organization and what actions they can take. You compose access from reusable building blocks — scopes, permission sets, and roles — and assign it to users, teams, and machine tokens.
 
-Leveraging Pulumi's RBAC features empower Enterprise organizations to follow best practices:
+This model lets you:
 
-- **Granular Access Control**: Define precise access levels for different resources.
-- **Simplified Management**: Easily manage access as they grow by building out reusable RBAC elements.
-- **Security**: Enforce least privilege access to resources.
+- Define precise access levels for each type of resource.
+- Reuse permission sets and roles instead of configuring access one resource at a time.
+- Enforce least-privilege access across the organization.
 
 ## Principals
 
-Roles can be assigned to three kinds of principals in Pulumi Cloud:
+Roles apply to these kinds of principals in Pulumi Cloud:
 
-- **Users**: Organization members can have a baseline organization role (Admin, Member, Billing Manager, or a custom role). When your organization has custom roles and "Assign custom roles to users" is enabled, admins can assign any custom role to individual members.
-- **Teams**: Teams can be assigned one or more roles. Members of a team receive the union of the team's roles and their own user role. Team role assignments are available when the organization has custom roles enabled.
-- **Organization access tokens**: Machine tokens can be assigned one role that defines the token's permissions across the organization.
+- **Users**: Each organization member has exactly **one** organization role (Admin, Member, Billing Manager, or a custom role). When your organization has custom roles and "Assign custom roles to users" is enabled, admins can replace a member's role with any custom role.
+- **Teams**: A team can be assigned **one or more** roles. Members of a team receive the union of the team's roles and their own user role. Team role assignments are available when the organization has custom roles enabled.
+- **Team tokens**: Machine tokens that act on behalf of a team. A team token's permissions are the union of the roles assigned to its team, evaluated on each request — they are not assigned a role directly. See [Team tokens](/docs/administration/access-identity/access-tokens/#team-access-tokens).
+- **Organization access tokens**: Machine tokens that are assigned exactly **one** role defining the token's permissions across the organization. See [Organization Access tokens](/docs/administration/access-identity/access-tokens/#creating-an-organization-access-token)
 
 ## Where roles apply
 
 - **User role**: Each member has a single baseline organization role (Admin, Member, Billing Manager, or a custom role). When "Assign custom roles to users" is enabled, admins can override this per user.
-- **Organization default role**: When your organization has custom roles, you can set a **default role for members**. That custom role becomes the baseline for members who have the Member organization role and have not been given an explicit custom role.
+- **Organization-wide defaults**: [Organization-wide role settings](/docs/administration/access-identity/rbac/organization-wide-role-settings) define the baseline permissions every member receives by default. They apply to members who have the Member organization role and have not been given an explicit custom role.
 - **Team roles**: Teams can have **role assignments** (one or more roles). Members of a team effectively get the union of those roles plus their own user role in the organization. See [Teams](/docs/administration/access-identity/rbac/teams#team-role-assignments) for details.
 
 ## How permissions accumulate
 
 Access in Pulumi Cloud is built up progressively. A user's effective permissions are the union of every grant that applies to them — from the broadest organizational constraints down to the most resource-specific automatic grants.
 
-### Organization-wide settings {#organization-wide-settings}
+{{% notes "info" %}}
+All grants are strictly **additive**: no rule can revoke access that another rule provides.
+{{% /notes %}}
 
-The outermost layer is a set of **organization-wide access settings** at **Settings** > **Access Management**. These on/off toggles cover capabilities such as creating or deleting stacks, creating teams, and creating Insights accounts. When a setting is **enabled**, that capability is granted to all members unconditionally, regardless of their role. When a setting is **disabled**, only members whose role explicitly includes the corresponding RBAC scope retain the capability. These settings are distinct from RBAC scopes: RBAC scopes (e.g. `stack:create`, `team:create`) are granted per-role, while org-wide settings apply to everyone when enabled.
+### Organization-wide role settings {#organization-wide-settings}
 
-### Team roles
+The [organization-wide role settings](/docs/administration/access-identity/rbac/organization-wide-role-settings) at **Settings** > **Access management** > **Roles** tab > **View organization-wide role settings** configure the built-in **Member** role: the access level members have to stacks, environments, and accounts, plus toggles for capabilities such as creating stacks, teams, and accounts. (They adjust part of the Member role; the role also carries a fixed baseline of scopes the panel doesn't expose.) They apply **only to members on the Member role** — a member with an explicitly assigned custom role uses that role instead, so these settings do not apply to them (see [User role](#user-role) below). When a capability toggle is **disabled**, creating that resource requires a role that includes the corresponding RBAC scope (e.g. `stack:create`, `team:create`).
 
-Members who belong to teams inherit all roles assigned to those teams, on top of their own individual role. Users in multiple teams accumulate permissions from all of them. Team roles can include tag-based (ABAC) rules that automatically apply a permission set to any resource whose tags match specified conditions, without requiring per-resource grants.
+### User role
 
-### Organization role
+Every member of a Pulumi organization has a user role — a built-in role (Admin, Member, or Billing Manager) or, where enabled, a custom role assigned by an admin. An explicitly assigned custom role applies in place of the default. Members with the Member organization role who have not been assigned a custom role receive the baseline permissions defined in [Organization-wide role settings](/docs/administration/access-identity/rbac/organization-wide-role-settings).
 
-Every member has a baseline organization role (Admin, Member, Billing Manager, or a custom role). Members with the Member organization role who have not been assigned an explicit custom role inherit the organization's default custom role, if one has been configured.
+### Team roles
 
-### Creator grants
+Members who belong to teams inherit all roles assigned to those teams, on top of their own individual role. Users in multiple teams accumulate permissions from all of them. Team roles can include tag-based (ABAC) rules that automatically apply a permission set to any resource whose tags match specified conditions, without requiring per-resource grants.
 
-Any user who creates a stack is automatically granted the Stack Admin permission set on that stack, regardless of their organization role or team memberships.
+### Creator grants
 
-All grants are strictly **additive**: no grant can reduce what another provides.
+Any user who creates a stack is automatically granted the Stack Admin permission set on that stack, regardless of their organization role or team memberships. A stack's owner can be changed after creation from the stack's details page, under **Access** > **Settings** > **Change owner**.
 
 ## RBAC Constructs
 
 Pulumi Cloud's RBAC system is built on these core concepts:
 
 - [**Scopes**](/docs/administration/access-identity/rbac/scopes): Granular access rights that define specific actions on resources
 - [**Permission sets**](/docs/administration/access-identity/rbac/permission-sets): Predefined bundles of scopes that are commonly used together
-- [**Roles**](/docs/administration/access-identity/rbac/roles): Collections of permission sets applied to resources and assigned to principals
+- [**Entities**](/docs/administration/access-identity/rbac/permission-sets#entities): The Pulumi Cloud objects that permission sets are granted on — stacks, environments, and insights accounts. (Pulumi uses "entity" rather than "resource" here to avoid confusion with cloud infrastructure resources.)
+- [**Roles**](/docs/administration/access-identity/rbac/roles): Collections of permission sets applied to entities and assigned to principals
 - [**Teams**](/docs/administration/access-identity/rbac/teams): Groups of users that can be assigned roles
 
+These constructs build on one another. Scopes are bundled into permission sets; a permission set applied to a set of entities forms an entity access rule; and a role combines one or more entity access rules with an organization access level. The completed role is then assigned to principals. See [Roles](/docs/administration/access-identity/rbac/roles) for a diagram of how a role is composed.
+
 Custom roles can also include **tag-based (ABAC) rules**: when resource tags match a rule's conditions, the role grants a chosen permission set on that resource. Details are in [Roles](/docs/administration/access-identity/rbac/roles#tag-based-abac-rules).
 
 ### Customization