Update OIDC docs with new auth policy guidance

themes/default/content/docs/pulumi-cloud/oidc/client/_index.md

@@ -63,7 +63,11 @@ When a new OIDC issuer is registered, a default authorization policy is provisio
 
 When configuring a policy, it is required to explicitly state what kind of token can be requested and what team or user the token should be scoped to.
 
-It is also required to configure at least one claim validation rule. When defining the claim key, it is possible to target nested claims by defining the claim path. For example, having the following structure:
+It is also required to configure at least one claim validation rule. It is recommended to always verify the token audience and subject claims according to the provider security recommendations:
+
+![Sample github policies](./sample-github-policies.png)
+
+When defining the claim key, it is possible to target nested claims by defining the claim path. For example, having the following structure:
 
 ```json
 {

themes/default/content/docs/pulumi-cloud/oidc/client/github.md

@@ -10,7 +10,7 @@ menu:
         weight: 1
 ---
 
-This document outlines the steps required to configure Pulumi to accept Github id_tokens to be exchanged by Organization access tokens
+This document outlines the steps required to configure Pulumi to accept Github id_tokens to be exchanged by Organization access tokens.
 
 ## Prerequisites
 
@@ -27,42 +27,26 @@ Please note that this guide provides step-by-step instructions based on the offi
    ![Register Github](../register-github.png)
 1. Submit the form
 
-## Conrigure the Authorization Policies
+## Configure the Authorization Policies
 
 1. Click on the issuer name
 1. Change the policy decision to `Allow`
 1. Change the token type to `Organization`
-1. Add a new rule and configure it to verify the token audience to match your github organization url: `aud: https://github.com/octo-org`. For further information about Github token claims refer to the [official Github documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token).
-   ![Github policy example](../github-policies.png)
+1. Update the policy to verify the configured token audience: `aud: urn:pulumi:org:YOUR_ORGANIZATION`
+1. Update the policy to verify the token subject matching your organization and repository: `sub: repo:octo-org/octo-repo:pull_request`. For further information about Github token claims refer to the [official Github documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token).
+   ![Github policy example](../sample-github-policies.png)
 1. Click on update
 
-## Set up the Github Actions step to fetch the OIDC token
+## Set up the Github Actions to use Pulumi's authentication action
 
 ```yaml
-- name: Fetch OIDC token
-  run: |
-    OIDC_GH_TOKEN=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL"  | jq -r '.value')
-    echo "OIDC_GH_TOKEN=$OIDC_GH_TOKEN" >> $GITHUB_ENV
-```
-
-## Set up the Github Actions step to exchange it for a Pulumi access token
-
-```yaml
-- name: Fetch Pulumi access token
-  run: |
-    PULUMI_ACCESS_TOKEN=$(curl -X POST  \
-    -H 'Content-Type: application/x-www-form-urlencoded' \
-    -d 'audience=urn:pulumi:org:ORG_NAME \
-    -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
-    -d 'subject_token_type=urn:ietf:params:oauth:token-type:id_token' \
-    -d 'requested_token_type=urn:pulumi:token-type:access_token:organization' \
-    -d 'subject_token=${{ env.OIDC_GH_TOKEN }}' \
-    https://api.pulumi.com/oauth/token | jq -r '.access_token')
-    echo "::add-mask::$PULUMI_ACCESS_TOKEN"
-    echo "PULUMI_ACCESS_TOKEN=$PULUMI_ACCESS_TOKEN" >> $GITHUB_ENV
+      - uses: pulumi/auth-actions@v1
+        with:
+          organization: org-name
+          requested-token-type: urn:pulumi:token-type:access_token:organization
 ```
 
-Replace ORG_NAME with the right Pulumi organization
+Replace `org-name` with the right Pulumi organization.
 
 ## Sample Github Actions workflow
 
@@ -81,35 +65,15 @@ jobs:
     timeout-minutes: 30
 
     steps:
-      - name: Checkout repo
-        uses: actions/checkout@v3
-
-      - name: Install pulumi
-        uses: pulumi/actions@v4
-
-      - name: Install deps
-        run: yarn
-
-      - name: Fetch OIDC token
-        run: |
-          OIDC_GH_TOKEN=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL"  | jq -r '.value')
-          echo "OIDC_GH_TOKEN=$OIDC_GH_TOKEN" >> $GITHUB_ENV
-
-      - name: Fetch Pulumi access token
-        run: |
-          PULUMI_ACCESS_TOKEN=$(curl -X POST  \
-            -H 'Content-Type: application/x-www-form-urlencoded' \
-            -d 'audience=urn:pulumi:org:ORG_NAME' \
-            -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
-            -d 'subject_token_type=urn:ietf:params:oauth:token-type:id_token' \
-            -d 'requested_token_type=urn:pulumi:token-type:access_token:organization' \
-            -d 'subject_token=${{ env.OIDC_GH_TOKEN }}' \
-            https://api.pulumi.com/api/oauth/token | jq -r '.access_token')
-          echo "::add-mask::$PULUMI_ACCESS_TOKEN"
-          echo "PULUMI_ACCESS_TOKEN=$PULUMI_ACCESS_TOKEN" >> $GITHUB_ENV
-
-      - uses: pulumi/actions@v4
+      - uses: actions/checkout@v4
+
+      - uses: pulumi/auth-actions@v1
+        with:
+          organization: org-name
+          requested-token-type: urn:pulumi:token-type:access_token:organization
+
+      - uses: pulumi/actions@v5
         with:
-          command: up
-          stack-name: ...
+          command: preview
+          stack-name: org-name/stack-name
 ```