pulumi · interurban · Feb 13, 2025 · Feb 13, 2025 · Feb 25, 2025 · Feb 25, 2025
@@ -0,0 +1,25 @@
+---
+title_tag: "Pulumi ESC: Identity & access Management"
+meta_desc: Learn how to use tokens, role-based access control, and OIDC with Pulumi ESC
+title: "Identity & access management"
+h1: "Pulumi ESC: Identity & access management"
+meta_image: /images/docs/meta-images/docs-meta.png
+
+menu:
+    esc:
+        parent: esc-home
+        identifier: pulumi-esc-access-management
+        weight: 10
+---
+
+Pulumi ESC provides identity and access management (IAM) controls to secure your environments, secrets, and configurations. Using role-based access control (RBAC), teams can enforce least-privilege access across environments, ensuring that users only have the permissions they need. ESC also supports access tokens for programmatic authentication and OpenID Connect (OIDC) for integrating with external identity providers.
+
+## Access controls in Pulumi ESC
+
+- [Teams and Role-based access control(RBAC)](/docs/pulumi-cloud/access-management/teams/): Manage permissions at the organization and environment levels.
+- [Access tokens](/docs/pulumi-cloud/access-management/access-tokens/): Securely authenticate and automate ESC operations.
+- [OpenID Connect (OIDC)](/docs/esc/access-management/oidc/): Integrate with trusted third-party identity providers to authenticate users.
+- [SAML single sign-on (SSO)](saml/): Configure SAML-based authentication for centralized access management.
+- [SCIM](scim/): Simplify user provisioning with the SCIM protocol
+
+For additional details on configuring environment-specific access controls, refer to the [Pulumi ESC access control](/docs/esc/access-management/access-control/) documentation.
@@ -5,8 +5,10 @@ h1: Pulumi ESC access control
 meta_desc: Pulumi ESC provides granular access control to manage permissions with roles like reader, opener, and editor.
 menu:
   esc:
-    parent: esc-environments
-    weight: 7
+    parent: pulumi-esc-access-management
+    weight: 1
+aliases:
+  - /docs/esc/environments/access-control/
 ---
 
 Pulumi ESC allows you to enforce least-privileged access across your environments through role-based access controls (RBAC). By assigning precise permissions at the organization and team levels, you ensure that users only have access to the environments they need. All changes, including environment updates and access modifications, are fully logged to provide complete auditing and compliance tracking, helping your organization maintain security best practices.

@@ -0,0 +1,30 @@
+---
+title_tag: Pulumi Cloud Environment Permissions
+meta_desc: Learn how to set organization wide environment permissions for the Pulumi Cloud.
+title: Environment Permissions
+h1: Environment organization permissions
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+  esc:
+    name: Environment permissions
+    parent: pulumi-esc-access-management
+    weight: 3
+aliases:
+  - /docs/pulumi-cloud/access-management/environment-permissions/
+---
+
+Pulumi ESC provides role-based access control (RBAC) to manage access to environments and their secrets and configurations. This ensures that users and teams only have the necessary permissions to view, modify, or use specific environments in infrastructure deployments.
+
+## Managing Access to Environments
+
+Pulumi ESC permissions can be set at two levels allowing you to follow a least-privilege model to ensure sensitive information remain secure:
+
+**Organization-wide permissions**: Define the default level of access for all members of an organization.
+
+**Team-based permissions**: Assign specific access roles to teams for granular control over who can read, modify, or manage environments.
+
+{{% notes "info" %}}
+By default, organization-wide environment access is set to write, but this can be adjusted to restrict permissions.
+{{% /notes %}}
+
+To learn more about configuring ESC access controls, including organization wide permission levels and team based permissions see [Pulumi ESC Access Control](/docs/esc/environments/access-management/access-control/).
@@ -0,0 +1,16 @@
+---
+title_tag: Configure OpenID Connect authentication | Pulumi ESC
+meta_desc: This page provides an overview of how Pulumi ESC can OIDC for authentication with a trusted identity provider.
+title: Configure OpenID authentication with ESC
+h1: Configure OpenID Connect authentication
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+  esc:
+    name: OIDC authentication
+    parent: pulumi-esc-access-management
+    weight: 3
+---
+
+Pulumi supports secure authentication by integrating with trusted external identity providers using OpenID Connect (OIDC). When configured as an OIDC client, Pulumi establishes a trust relationship with third-party providers such as Google, AWS or GitHub to accept and validate their issued OIDC tokens. After validation, these tokens are exchanged for short-lived Pulumi access tokens, which removes the need for hardcoded credentials.
+
+To integrate Pulumi with a third-party identity provider, see the detailed [OIDC Client documentation](/docs/pulumi-cloud/access-management/oidc/client/).
@@ -7,7 +7,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
   esc:
     parent: esc-home
-    weight: 11
+    weight: 12
     identifier: faq
 aliases:
   - /docs/pulumi-cloud/esc/faq

@@ -7,7 +7,7 @@ menu:
   esc:
     identifier: esc-kubernetes-integrations
     parent: esc-integrations
-    weight: 5
+    weight: 6
 aliases:
   - /docs/esc/kubernetes-integrations
 ---

@@ -0,0 +1,100 @@
+---
+title_tag: OpenID Connect provider integration | Pulumi ESC
+meta_desc: This page provides an overview of how to configure OpenID Connect integration between
+           Pulumi ESC and supported cloud providers.
+title: OpenID Connect provider integration with ESC
+h1: OpenID Connect provider integration for ESC
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+  esc:
+    name: OIDC Provider
+    parent: esc-integrations
+    weight: 5
+---
+
+Pulumi can be configured to act as an OpenID Connect (OIDC) provider, issuing signed, short-lived tokens. These tokens can then be exchanged by external systems for temporary cloud provider credentials, eliminating the need for hardcoded credentials.
+
+## OIDC authentication configuration
+
+Set up OIDC between Pulumi ESC and your cloud provider:
+
+- [Configuring OIDC for AWS](/docs/pulumi-cloud/oidc/provider/aws/)
+- [Configuring OIDC for Azure](/docs/pulumi-cloud/oidc/provider/azure/)
+- [Configuring OIDC for Google Cloud](/docs/pulumi-cloud/oidc/provider/gcp/)
+- [Configuring OIDC for Vault](/docs/pulumi-cloud/oidc/provider/vault/)
+
+### Pulumi ESC token claim
+
+The OIDC token issued by Pulumi ESC includes several claims that you can use to configure trust relationships with your cloud provider. The token contains the following claims:
+
+| Claim         | Description |
+|:--------------|:------------|
+| aud           | _(Audience)_ The name of the organization associated with the environment prefixed with the provider's platform name (`aws:{org}`, `azure:{org}`, `gcp:{org}`). |
+| iss           | _(Issuer)_ The issuer of the OIDC token: `https://api.pulumi.com/oidc`. |
+| current_env   | _(Current Environment)_ The name of the environment where the [ESC OIDC provider configuration](/docs/esc/integrations/) is defined. |
+| root_env      | _(Root Environment)_ The name of the environment that is opened first. This Root Environment in turn opens other imported environments. |
+| trigger_user  | _(Trigger User)_ The user whose credentials are used to open an environment. |
+| sub           | _(Subject)_ The subject of the OIDC token. Often used for configuring trust relationships, it contains information about the associated service. Each component is also available as a custom claim. |
+
+### Pulumi ESC custom claim
+
+The default format of the subject claim for this service is:
+
+`pulumi:environments:org:<organization name>:env:<project name>/<environment name>`
+
+To enforce more granular permissions you can customize the OIDC subject claims using the `subjectAttributes` property. This is especially useful if you plan to reference subject claims within your cloud provider’s trust policy. The default prefix when using `subjectAttributes` will be:
+
+`pulumi:environments:pulumi.organization.login:{ORGANIZATION_NAME}`
+
+Additional options for customization include:
+
+- `rootEnvironment.name`: the name of the environment that is opened first. This root environment in turn opens other imported environments
+- `currentEnvironment.name`: the name of the environment where the ESC login provider and `subjectAttributes` are defined
+- `pulumi.user.login`: the login identifier of the user opening the environment
+- `pulumi.organization.login`: the login identifier of the organization
+
+## Example: Resolving rootEnvironment.name and currentEnvironment.name
+
+Consider the following definitions for two environments, `Project/Environment-A` and `Project/Environment-B`:
+
+```yaml
+#Project/Environment-A
+values:
+  enva-rootEnv: ${context.rootEnvironment.name}
+  enva-currentEnv: ${context.currentEnvironment.name}
+
+#Project/Environment-B
+imports:
+- Project/EnvironmentA
+values:
+  envb-rootEnv: ${context.rootEnvironment.name}
+  envb-currentEnv: ${context.currentEnvironment.name}
+```
+
+When you open `Project/Environment-B`, the output would be:
+
+```
+{
+  "enva-currentEnv-name": "Project/Environment-A",
+  "enva-rootEnv-name": "Project/Environment-B",
+  "envb-currentEnv": "Project/Environment-B",
+  "envb-rootEnv": "Project/Environment-B"
+}
+```
+
+Notice how `enva-rootEnv-name` is resolved to `Project/Environment-B`. That's because Project/Environment-A is opened from Project/Environment-B which is the root, i.e. the top-level environment to be opened.
+
+When importing multiple environments into Pulumi IaC Stack Config, each environment is resolved separately. For example, if you import multiple environments into your Pulumi Stack with `rootEnvironment.name` attribute defined in all of them, then each `rootEnvironment.name` will resolve to the environment name where it is defined.
+
+## Configuring trust relationships
+
+As part of the process that exchanges your service's OIDC token for cloud provider credentials, the cloud provider must check the OIDC token's claims against the conditions configured in the provider's trust relationship. The configuration of a trust relationship varies depending on the cloud provider, but typically uses at least the **Audience**, **Subject**, and **Issuer** claims. These claims can be used to restrict trust to specific organizations, projects, stacks, environments:
+
+- The Issuer claim is typically used to validate that the token is properly signed. The issuer's public signing key is fetched and used to validate the token's signature.
+- The Audience claim contains the name of the organization, prefixed with the provider's platform (`aws`, `azure`, `gcp`). You can use this claim to restrict credentials to a specific organization or organizations.
+- The Subject claim contains a variety of information about the service. You can use this claim to restrict credentials to a specific organization/scope.
+- The various custom claims contain the same information as the Subject claim. If your cloud provider supports configuring trust relationships based on custom claims, you can use these claims for the same purposes as the Subject claim.
+
+The subject and custom claims are particularly useful for configuring trust relationships, as they allow you to set very fine-grained conditions for credentials.
+
+For further details on additional OIDC integration and managing Pulumi Cloud access see our [OIDC Overview documentation](/docs/pulumi-cloud/access-management/oidc/).
@@ -7,7 +7,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
   esc:
     parent: esc-home
-    weight: 10
+    weight: 11
     identifier: esc-vs
 aliases:
 ---

@@ -17,6 +17,7 @@ Pulumi Cloud offers a number of identity and access management controls.
 - [Accounts](accounts/)
 - [Teams and Role-based access control](teams/)
 - [Access tokens](access-tokens/)
+- [Environment permissions](environment-permissions/)
 - [OpenID](oidc/)
 - [Billing managers](billing-managers/)
 - [SAML single sign-on (SSO)](saml/)

@@ -35,16 +35,7 @@ The token contains the standard audience, issuer, and subject claims:
 
 ### Pulumi ESC
 
-The token contains the following claims:
-
-| Claim         | Description |
-|:--------------|:------------|
-| aud           | _(Audience)_ The name of the organization associated with the environment prefixed with the provider's platform name (`aws:{org}`, `azure:{org}`, `gcp:{org}`). |
-| iss           | _(Issuer)_ The issuer of the OIDC token: `https://api.pulumi.com/oidc`. |
-| current_env   | _(Current Environment)_ The name of the environment where the [ESC OIDC provider configuration](/docs/esc/integrations/) is defined. |
-| root_env      | _(Root Environment)_ The name of the environment that is opened first. This Root Environment in turn opens other imported environments. |
-| trigger_user  | _(Trigger User)_ The user whose credentials are used to open an environment. |
-| sub           | _(Subject)_ The subject of the OIDC token. Often used for configuring trust relationships, it contains information about the associated service. Each component is also available as a custom claim. |
+For details on how Pulumi ESC environments interact with OIDC token claims, see [Configuring OIDC for Pulumi ESC](/docs/esc/access-management/oidc/).
 
 ## Custom claims
 
@@ -70,51 +61,7 @@ Valid custom claims for this service are listed in the table below:
 
 ### Pulumi ESC
 
-The default format of the subject claim for this service is:
-
-`pulumi:environments:org:<organization name>:env:<project name>/<environment name>`
-
-If you want to have granular permissions, then we recommend using `subjectAttributes` property to customize the OIDC subject claims if you plan to use subject claims in your cloud provider trust policy. The default prefix when using `subjectAttributes` will be
-
-`pulumi:environments:pulumi.organization.login:{ORGANIZATION_NAME}`
-
-Additional options for customization include:
-
-* `rootEnvironment.name`: the name of the environment that is opened first. This root environment in turn opens other imported environments
-* `currentEnvironment.name`: the name of the environment where the ESC login provider and `subjectAttributes` are defined
-* `pulumi.user.login`: the login identifier of the user opening the environment
-* `pulumi.organization.login`: the login identifier of the organization
-
-Let's explain how `rootEnvironment.name` and `currentEnvironment.name` work with an example. Consider the following definitions for two environments, `Project/Environment-A` and `Project/Environment-B`:
-
-```yaml
-#Project/Environment-A
-values:
-  enva-rootEnv: ${context.rootEnvironment.name}
-  enva-currentEnv: ${context.currentEnvironment.name}
-
-#Project/Environment-B
-imports:
-- Project/EnvironmentA
-values:
-  envb-rootEnv: ${context.rootEnvironment.name}
-  envb-currentEnv: ${context.currentEnvironment.name}
-```
-
-If you open `Project/Environment-B`, the output would be:
-
-```
-{
-  "enva-currentEnv-name": "Project/Environment-A",
-  "enva-rootEnv-name": "Project/Environment-B",
-  "envb-currentEnv": "Project/Environment-B",
-  "envb-rootEnv": "Project/Environment-B"
-}
-```
-
-Notice how `enva-rootEnv-name` is resolved to `Project/Environment-B`. That's because Project/Environment-A is opened from Project/Environment-B which is the root, i.e. the top-level environment to be opened.
-
-When importing multiple environments into Pulumi IaC Stack Config, each environment is resolved separately. For example, if you import multiple environments into your Pulumi Stack with `rootEnvironment.name` attribute defined in all of them, then each `rootEnvironment.name` will resolve to the environment name where it is defined.
+For details on how Pulumi ESC environments interact with OIDC custom claims, see [Configuring OIDC for Pulumi ESC](/docs/esc/access-management/oidc/).
 
 ## Configuring trust relationships