From 3cae6854e6fa81336592233cf0ca4c1f0e5600c0 Mon Sep 17 00:00:00 2001
From: liyu-ma <liyuma.dit@gmail.com>
Date: Tue, 28 Apr 2026 11:00:22 +1000
Subject: [PATCH 1/2] Add AWS benchmarking authentication documentation

---
 docs/aws-benchmarking-auth.md | 66 +++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 docs/aws-benchmarking-auth.md

diff --git a/docs/aws-benchmarking-auth.md b/docs/aws-benchmarking-auth.md
new file mode 100644
index 0000000000..33339e1f9e
--- /dev/null
+++ b/docs/aws-benchmarking-auth.md
@@ -0,0 +1,66 @@
+# AWS Benchmarking Authentication
+
+This document describes how Telescope pipelines authenticate to AWS for benchmark runs, covering the current OIDC-based approach and the infrastructure setup required.
+
+## Overview
+
+Telescope uses **OIDC (OpenID Connect) federation** to authenticate Azure DevOps (ADO) pipelines to AWS. Instead of storing long-lived static IAM access keys, the pipeline obtains short-lived temporary credentials at runtime through the AWS Toolkit for Azure DevOps extension.
+
+### Authentication Flow
+
+```
+ADO Pipeline
+  └─ AWSShellScript@1 task (AWS Toolkit extension)
+       ├─ ADO issues an OIDC token via the service connection
+       ├─ AWS Toolkit exchanges the token with AWS STS (AssumeRoleWithWebIdentity)
+       └─ Injects AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
+            └─ Pipeline exports these as pipeline variables
+                 └─ Shared "AWS Login" step configures the AWS CLI
+```
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `steps/cloud/aws/login.yml` | Central AWS auth template used by all AWS pipelines |
+| `jobs/competitive-test.yml` | Job template that passes `credential_type` to login |
+| `steps/setup-tests.yml` | Passes `credential_type` from job to cloud login |
+
+## Credential Types
+
+The `credential_type` parameter controls how AWS credentials are obtained. It flows from the pipeline → `jobs/competitive-test.yml` → `steps/setup-tests.yml` → `steps/cloud/aws/login.yml`.
+
+### `service_connection` (required for OIDC)
+
+Uses the **AWS Toolkit for Azure DevOps** extension (`AWSShellScript@1` task) with an ADO service connection. This is required for OIDC authentication.
+
+- The service connection is referenced via the `$(AWS_SERVICE_CONNECTION)` pipeline variable
+- The extension automatically handles the OIDC token exchange and returns temporary credentials (access key, secret key, session token)
+
+```yaml
+# Pipeline usage
+credential_type: service_connection
+```
+
+## Pipeline Configuration
+
+The ADO service connection `AWS-for-Telescope-OIDC` has been configured with a role in the AWS benchmarking account. To use OIDC authentication, pipelines need to set the following variables:
+
+### `AWS_SERVICE_CONNECTION`
+
+Set this pipeline variable to `AWS-for-Telescope-OIDC`:
+
+```yaml
+variables:
+  AWS_SERVICE_CONNECTION: AWS-for-Telescope-OIDC
+```
+
+### `aws.rolecredential.maxduration`
+
+Set this to control the credential lifetime in seconds. The maximum allowed value is `43200` (12 hours). Choose a value that covers the full duration of your benchmark run:
+
+```yaml
+variables:
+  aws.rolecredential.maxduration: 43200
+```
+

From 86051eed0596cd9b4d67319a95e64f5778543a71 Mon Sep 17 00:00:00 2001
From: liyu-ma <liyuma.dit@gmail.com>
Date: Tue, 28 Apr 2026 16:44:16 +1000
Subject: [PATCH 2/2] Update AWS auth doc with variable_group note and
 credential duration details

---
 docs/aws-benchmarking-auth.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/aws-benchmarking-auth.md b/docs/aws-benchmarking-auth.md
index 33339e1f9e..e9f95e0e6d 100644
--- a/docs/aws-benchmarking-auth.md
+++ b/docs/aws-benchmarking-auth.md
@@ -42,6 +42,8 @@ Uses the **AWS Toolkit for Azure DevOps** extension (`AWSShellScript@1` task) wi
 credential_type: service_connection
 ```
 
+> **Note:** The `variable_group` credential type stores static IAM access keys in an ADO variable group, so it does not support OIDC.
+
 ## Pipeline Configuration
 
 The ADO service connection `AWS-for-Telescope-OIDC` has been configured with a role in the AWS benchmarking account. To use OIDC authentication, pipelines need to set the following variables:
@@ -57,7 +59,7 @@ variables:
 
 ### `aws.rolecredential.maxduration`
 
-Set this to control the credential lifetime in seconds. The maximum allowed value is `43200` (12 hours). Choose a value that covers the full duration of your benchmark run:
+Controls the credential lifetime in seconds. The AWS IAM role is configured with a maximum session duration of `43200` (12 hours). Pipelines must set `aws.rolecredential.maxduration` to a value less than or equal to `43200` that covers the full duration of the benchmark run:
 
 ```yaml
 variables: