creating new access mgmt ESC section

content/docs/esc/access-management/_index.md

@@ -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.

content/docs/esc/environments/access-control.md → content/docs/esc/access-management/access-control.md

@@ -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.

content/docs/esc/access-management/oidc-authentication.md

@@ -0,0 +1,16 @@
+---
+title_tag: Configure OpenID Connect authentication | Pulumi ESC
+meta_desc: This page provides an overview of how Pulumi ESC can be configured for OIDC 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/).

content/docs/esc/environments/configuring-oidc.md

@@ -0,0 +1,98 @@
+---
+title_tag: Configuring OpenID Connect | Pulumi ESC
+meta_desc: This page provides an overview of how to configure OpenID Connect integration between Pulumi ESC and supported cloud providers.
+title: Configuring OIDC
+h1: Configuring OIDC for ESC
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+  esc:
+    parent: esc-environments
+    weight: 6
+---
+
+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](https://openid.net/specs/openid-connect-core-1_0.html#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/).

content/docs/esc/environments/webhooks.md

@@ -7,7 +7,7 @@ meta_image: /images/docs/meta-images/docs-meta.png
 menu:
   esc:
     parent: esc-environments
-    weight: 6
+    weight: 7
 aliases:
 - /docs/esc-cli/commands/
 - /docs/esc/webhooks/

content/docs/esc/faq.md

@@ -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

content/docs/esc/get-started/use-short-term-credentials.md

@@ -0,0 +1,126 @@
+---
+title_tag: Use Short Term Cloud Credentials | Pulumi ESC
+title: Use short term cloud credentials
+h1: "Use Short Term Cloud Credentials to Run Commands Without Local Secrets"
+meta_desc: This page provides an overview on how to get short term cloud credentials and run commands without using local secrets using the "esc run" command.
+weight: 6
+menu:
+  esc:
+    parent: esc-get-started
+---
+
+Managing cloud credentials presents significant challenges for organizations of all sizes. Static, long-lived credentials, especially those stored in local environments introduce security risks and operational issues. Pulumi ESC’s built-in support for [dynamic login providers](/docs/esc/integrations/dynamic-login-credentials/), allows for best-practices like generating signed, short-term, scoped credentials issued via OIDC. These credentials can then be used in both Pulumi IaC workflows and external CLIs such as `aws`, `kubectl`.
+
+In this example you will use the `esc run` command to execute AWS cli operations without having to manually configure AWS credentials in your local environment.
+
+## Create the AWS OIDC configuration
+
+To use dynamic credentials, you need to configure [OpenID Connect (OIDC)](/docs/esc/environments/configuring-oidc/) between Pulumi ESC and AWS. This requires creating two resources in AWS:
+
+1. An IAM OIDC provider
+2. An IAM role that trusts this provider and provides the necessary permissions
+
+### Create the OIDC provider
+
+1. Navigate to the [IAM console](https://console.aws.amazon.com/iam/)
+2. In the navigation pane, choose **Identity providers**, then **Add provider**
+3. Select **OpenID Connect** as the provider type
+4. For the Provider URL, enter: `https://api.pulumi.com/oidc`
+5. For the Audience, enter your Pulumi organization name
+6. Click **Add provider**
+
+### Create the IAM role
+
+1. After creating the provider, click **Assign role** in the notification prompt
+2. Select **Create a new role**
+3. Ensure **Web identity** is selected, and verify:
+   - The `api.pulumi.com/oidc` provider is selected
+   - Your Pulumi organization is selected as the audience
+4. Click **Next**
+5. Select the permissions your role needs (e.g. **AmazonS3FullAccess** for S3 operations)
+6. Click **Next**
+7. Name your role (e.g., `pulumi-esc-s3-role`) and add an optional description
+8. Click **Edit** on the Select trusted entities' section
+9. Ensure the "Condition" subject claim includes `aws:` before your organization name (i.e.`"api.pulumi.com/oidc:aud": "aws:myorg"` )
+10. Review and click **Create role**
+
+Note the ARN of your new role as you'll need it in the next step.
+
+{{< notes type="info" >}}
+If you want to set environment level or even granular permissions in your trust policy, then we recommend using `subjectAttributes` property. See the [aws-login documentation](/docs/esc/integrations/dynamic-login-credentials/aws-login/) for more information.
+{{< /notes >}}
+
+## Create a Pulumi ESC environment
+
+1. Navigate to the [Pulumi Cloud Console](https://app.pulumi.com/)  
+2. Click **Environments** and then **Create environment**
+3. Enter a name for your environment (e.g., `aws-s3-access`)
+4. Click **Create environment**
+
+## Configure the AWS Provider integration
+
+In the environment editor, replace the default content with:
+
+```yaml
+values:
+  aws:
+    login:
+      fn::open::aws-login:
+        oidc:
+          duration: 1h
+          roleArn: <your-oidc-iam-role-arn>
+          sessionName: pulumi-environments-session
+  environmentVariables:
+    AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
+    AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
+    AWS_SESSION_TOKEN: ${aws.login.sessionToken}
+```
+
+Be sure to replace `<your-oidc-iam-role-arn>` with the ARN of the IAM role you created.
+
+![An image of the ESC environment editor role trust policy](/docs/esc/assets/esc-environment-editor.png)
+
+Click **Save** to store your environment configuration.
+
+## Use esc run to execute AWS commands
+
+`esc run` is a [Pulumi ESC command](/docs/esc/cli/commands/esc_run/) that securely injects environment variables, including secrets and dynamically generated credentials, into a command’s execution environment. Now you can use it to run AWS CLI commands without local credential configuration:
+
+```bash
+esc run <your-org-name>/<your-project-name>/<your-environment-name> aws s3 ls
+```
+
+You should be presented with a list of S3 buckets in the account associated with your credentials.
+
+```bash
+
+# example command and output
+esc run pulumi/my-project/dev-environment aws s3 ls
+
+2023-12-10 02:52:46 my-bucket-4a67543
+2023-11-16 21:37:40 my-bucket-4b1e6cb
+2023-10-27 21:04:59 my-bucket-50da4ad
+2023-11-02 18:57:36 my-bucket-51385eb
+```
+
+Behind the scenes, Pulumi ESC dynamically generated short-lived AWS credentials by assuming the IAM role you configured. These credentials are injected into the command environment as variables, allowing the AWS CLI to use them for authentication.
+
+ESC dynamic credentials and the `esc run` command can be used for various scenarios:
+
+- **CI/CD pipelines**: Use dynamic credentials in your automation workflows
+- **Application testing**: Run tests against cloud resources without managing credentials
+- **Secure script execution**: Execute scripts that interact with AWS without embedding credentials
+- **Team collaboration**: Provide team members with secure, scoped access to resources
+
+## Additional OIDC authentication configurations
+
+See the following guides to set up OIDC between Pulumi ESC and your specific 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/)
+
+In the next section, you will learn how to retrieve secret values from external sources.
+
+{{< get-started-stepper >}}

content/docs/esc/integrations/kubernetes/_index.md

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

content/docs/esc/vs/_index.md

@@ -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:
 ---

content/docs/pulumi-cloud/access-management/_index.md

@@ -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/)

content/docs/pulumi-cloud/access-management/oidc/provider/_index.md

@@ -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