[RDE-534] Document OIDC cloud authentication for RDE sessions

docs/bitrise-platform/integrations/oidc-authentication/oidc-authentication-overview.mdx

@@ -17,7 +17,7 @@ The service that receives the token evaluates the token's claims against its OID
 
 Bitrise supports the use of OIDC tokens in two ways:
 
-- To enable your Bitrise builds to authenticate to external systems such as AWS, GCP, Azure, container registries, secret management or artifact stores.
+- To enable your Bitrise builds and Remote Dev Environment sessions to authenticate to external systems such as AWS, GCP, Azure, container registries, secret management or artifact stores.
 - To use foreign OIDC tokens to authenticate to Bitrise and receive short-lived Bitrise tokens.
 
 
@@ -86,6 +86,16 @@ You can find more information about claim fields in the [AWS documentation](http
 | `build_number` | Build number |
 | `workflow` | Name of the triggered workflow |
 
+### Identity tokens for Remote Dev Environments
+
+A Remote Dev Environment session can request an identity token the same way a build can. The token comes from the same issuer with the same signing keys, so a cloud provider that already trusts Bitrise for builds also trusts it for sessions. The subject describes the session instead of the build:
+
+```text
+rde:workspace:WORKSPACE_ID:template:TEMPLATE_ID:session-owner:OWNER_TYPE:OWNER_ID
+```
+
+Because the subject starts with `rde:`, a trust policy written for builds never matches a session, and the other way around. For the full list of claims and how to request a token from a session, see [Cloud authentication with OIDC](/bitrise-rde/configuration/oidc-cloud-authentication).
+
 
 ## Authentication to Bitrise with OIDC
 

docs/bitrise-platform/integrations/oidc-authentication/oidc-for-aws.mdx

@@ -1,6 +1,6 @@
 ---
 title: "OIDC for AWS"
-description: "Generate OIDC tokens during your Bitrise build to exchange them for scoped access tokens with"
+description: "Use OIDC tokens to let your Bitrise builds and Remote Dev Environment sessions authenticate to AWS without long-lived access keys."
 sidebar_position: 2
 slug: /bitrise-platform/integrations/oidc-authentication/oidc-for-aws
 ---
@@ -9,14 +9,19 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import GlossTerm from '@site/src/components/GlossTerm';
 
-Generate OpenID Connect (OIDC) tokens during your Bitrise build to exchange them for AWS Identity and Access Management (IAM) roles with AWS-scoped permissions.
+OpenID Connect (OIDC) lets Bitrise prove to AWS who is making a request, without a long-lived access key. Bitrise issues an identity token that describes the build or session, and AWS exchanges it for temporary credentials from an AWS Identity and Access Management (IAM) role with AWS-scoped permissions.
+
+You can use OIDC tokens for AWS in two places:
+
+- **CI builds**: get the token with either the [**Get OIDC identity token**](https://github.com/bitrise-steplib/bitrise-step-get-identity-token) <GlossTerm baseform="step">Step</GlossTerm> or the [**Authenticate with Amazon Web Services (AWS)**](https://github.com/bitrise-steplib/bitrise-step-authenticate-with-aws) Step.
+- **Remote Dev Environment sessions**: the session's `rde-agent` command requests the token whenever the AWS CLI or SDKs need credentials. See [Cloud authentication with OIDC](/bitrise-rde/configuration/oidc-cloud-authentication).
 
 To use OIDC tokens for AWS, you'll need to:
 
 - Create an IAM OIDC provider in your AWS account.
 - Add a custom trust policy: this means writing the rules for the identity tokens.
 
-On Bitrise, you can get the tokens by using either the [**Get OIDC identity token**](https://github.com/bitrise-steplib/bitrise-step-get-identity-token) <GlossTerm baseform="step">Step</GlossTerm> or the [**Authenticate with Amazon Web Services (AWS)**](https://github.com/bitrise-steplib/bitrise-step-authenticate-with-aws) Step.
+The IAM OIDC provider is the same for builds and sessions. The trust policy differs, because they use different subjects.
 
 
 ## Adding an OIDC identity provider in IAM
@@ -107,6 +112,12 @@ Our guide helps you set up your AWS policy for your Bitrise builds. You can read
    ```
 
    You can also use wildcards with the `StringLike` operation instead of `StringEquals`: [Wildcard matching](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String-wildcard).
+
+   :::info[Remote Dev Environment sessions]
+
+   Tokens requested from a Remote Dev Environment session use a different subject, starting with `rde:`, so they need their own trust policy. See [Cloud authentication with OIDC](/bitrise-rde/configuration/oidc-cloud-authentication).
+
+   :::
 1. When done, click **Next**.
 1. Select the required permission for the role.
 

docs/bitrise-platform/integrations/oidc-authentication/oidc-for-gcp.mdx

@@ -1,6 +1,6 @@
 ---
 title: "OIDC for GCP"
-description: "Generate OIDC tokens during your Bitrise build to exchange them for scoped access tokens with Google Cloud Platform"
+description: "Use OIDC tokens to let your Bitrise builds and Remote Dev Environment sessions authenticate to Google Cloud Platform without long-lived service account keys."
 sidebar_position: 3
 slug: /bitrise-platform/integrations/oidc-authentication/oidc-for-gcp
 ---
@@ -9,14 +9,19 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import GlossTerm from '@site/src/components/GlossTerm';
 
-Generate OIDC tokens during your Bitrise build to exchange them for scoped access tokens with Google Cloud Platform (GCP).
+OpenID Connect (OIDC) lets Bitrise prove to Google Cloud Platform (GCP) who is making a request, without a long-lived service account key. Bitrise issues an identity token that describes the build or session, and GCP exchanges it for a scoped access token through Workload Identity Federation.
+
+You can use OIDC tokens for GCP in two places:
+
+- **CI builds**: get the token with either the [**Get OIDC Identity Token**](https://github.com/bitrise-steplib/bitrise-step-get-identity-token) <GlossTerm baseform="step">Step</GlossTerm> or the [**Authenticate with Google Cloud Platform (GCP)**](https://github.com/bitrise-steplib/bitrise-step-authenticate-with-gcp) Step.
+- **Remote Dev Environment sessions**: the session's `rde-agent` command provides the token whenever gcloud or the Google client libraries need credentials. See [Cloud authentication with OIDC](/bitrise-rde/configuration/oidc-cloud-authentication).
 
 To use OIDC tokens for GCP, you'll need to:
 
 - Create a workload identity pool.
 - Connect a Google service account to the identity pool.
 
-On Bitrise, you can get the tokens by using either the [**Get OIDC Identity Token**](https://github.com/bitrise-steplib/bitrise-step-get-identity-token) <GlossTerm baseform="step">Step</GlossTerm> or the [**Authenticate with Google Cloud Platform (GCP)**](https://github.com/bitrise-steplib/bitrise-step-authenticate-with-gcp) Step.
+The setup is the same for builds and sessions, except for the attribute mapping and the principal filter, which match the claims of the build or the session.
 
 
 ## Creating a workload identity pool
@@ -43,7 +48,7 @@ Read more about how authentication with Workload Identity Federation works on GC
 1. Click **Continue**.
 1. Under **Configure provider attributes**, configure the required attribute mapping values:
 
-   - The `google.subject` key is a unique identifier for the user. You can use `assertion.sub` to identify the build that requests the token.
+   - The `google.subject` key is a unique identifier for the user. You can use `assertion.sub` to identify the build or the Remote Dev Environment session that requests the token. Session subjects start with `rde:`; see [Cloud authentication with OIDC](/bitrise-rde/configuration/oidc-cloud-authentication).
    - Use the `attribute.NAME` format to add up to 50 custom attributes, each with a value in the `assertion.VALUE` format. You can find the list of available attributes in the Bitrise token here: [Information in the OIDC token](/bitrise-platform/integrations/oidc-authentication/oidc-authentication-overview#information-in-the-oidc-token).
 
    :::important[Explicit mapping required]
@@ -85,7 +90,7 @@ To start using OIDC authentication for GCP services, you need to connect a workl
 1. Select the service account you've created.
 1. Select the principals: identities that can access the service account.
 
-   The available options are limited to the keys from the provider attribute mapping of the identity pool. For example, if you use the attribute mapping `google.subject=assertion.sub`, set **Attribute name** to `subject` and **Attribute value** to `sub`. You can see the available values in the Bitrise token here:
+   The available options are limited to the keys from the provider attribute mapping of the identity pool, and a filter matches the attribute's value exactly. For example, if you use the attribute mapping `google.subject=assertion.sub`, set **Attribute name** to `subject` and **Attribute value** to the subject of the build, in the `app:APP_SLUG:workflow:WORKFLOW` format. You can see the available values in the Bitrise token here: [Information in the OIDC token](/bitrise-platform/integrations/oidc-authentication/oidc-authentication-overview#information-in-the-oidc-token).
 1. Click **Save**.
 1. In the dialog, select the provider you created for Bitrise OIDC tokens.
 1. Add the OIDC ID token path: https://token.builds.bitrise.io and set the format to **text**.

docs/bitrise-rde/configuration/managing-rde-access.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Managing RDE access"
 description: "Grant and revoke Remote Dev Environments access for workspace members and groups from the Collaboration page, or automate it with SCIM."
-sidebar_position: 6
+sidebar_position: 7
 slug: /bitrise-rde/configuration/managing-rde-access
 sidebar_label: "Managing access"
 ---