From 851e341757622f318eeee1a585c48a8602818035 Mon Sep 17 00:00:00 2001 From: saipavanyerra Date: Fri, 11 Sep 2026 01:37:22 +0000 Subject: [PATCH] feat(aws-healthomics): add steering for session policy on StartRun/StartRunBatch --- aws-healthomics/POWER.md | 1 + aws-healthomics/steering/batch-runs.md | 2 + .../steering/running-a-workflow.md | 6 ++ aws-healthomics/steering/session-policy.md | 83 +++++++++++++++++++ 4 files changed, 92 insertions(+) create mode 100644 aws-healthomics/steering/session-policy.md diff --git a/aws-healthomics/POWER.md b/aws-healthomics/POWER.md index be07604f..2608b3fd 100644 --- a/aws-healthomics/POWER.md +++ b/aws-healthomics/POWER.md @@ -29,6 +29,7 @@ Whenever you are asked to perform a task related to any of the following scenari - Managing HealthOmics VPC configurations (creating, listing, getting, or deleting configurations) -> use `./steering/healthomics-configuration.md` - Running workflows with VPC connectivity, public internet access, cross-region access, or access to private VPC resources -> use `./steering/vpc-connected-workflow-runs.md` - Understanding regional feature availability, GPU instance limitations, or troubleshooting region-specific errors -> use `./steering/regional-capabilities.md` +- Scoping down a workflow run's IAM permissions with an inline session policy (the StartRun / StartRunBatch `sessionPolicy` parameter) -> use `./steering/session-policy.md` # Onboarding diff --git a/aws-healthomics/steering/batch-runs.md b/aws-healthomics/steering/batch-runs.md index 83018e6b..9e6d636d 100644 --- a/aws-healthomics/steering/batch-runs.md +++ b/aws-healthomics/steering/batch-runs.md @@ -64,6 +64,7 @@ The IAM service role passed in `roleArn` requires the same permissions as for in - `roleArn` — IAM service role ARN (check `.healthomics/config.toml`). - `outputUri` — S3 output location (check `.healthomics/config.toml`). - `storageType` — Use `DYNAMIC` (recommended). + - `sessionPolicy` — Optional; an inline IAM policy (JSON) that scopes down the permissions of `roleArn` for every run in the batch (effective permissions = the intersection of the role's policies and this policy). Applies uniformly to all runs in the batch. See the [Session Policies SOP](./session-policy.md). - `parameters` — Common parameters shared across all runs (e.g., reference genome). 3. Prepare per-run configurations, each with a unique `runSettingId` and any parameter overrides. @@ -223,3 +224,4 @@ The S3 file at `s3://my-bucket/configs/run-configs.json` is a JSON array with th - **Ready2Run workflows** — Not supported with batch runs. - **Inline limit** — `inlineSettings` supports up to 100 entries. For larger batches, use `s3UriSettings`. - **S3 file immutability** — Do not modify the S3 configuration file after submitting the batch. +- **Session policy is batch-wide, not per-run** — `sessionPolicy` lives in `defaultRunSetting` and applies to every run in the batch identically; individual run settings (`inlineSettings`/`s3UriSettings`) cannot override it. See the [Session Policies SOP](./session-policy.md). diff --git a/aws-healthomics/steering/running-a-workflow.md b/aws-healthomics/steering/running-a-workflow.md index 81341851..a256f37b 100644 --- a/aws-healthomics/steering/running-a-workflow.md +++ b/aws-healthomics/steering/running-a-workflow.md @@ -35,6 +35,12 @@ Follow this SOP WHEN: 2. Call `GetAHORun` to check status. 3. WHEN the workflow completes, outputs will be at the specified output location. +### Session Policy + +`StartRun` accepts an optional `sessionPolicy` — an inline IAM policy (JSON string) that further scopes down the permissions of the run's `roleArn` for that run. The run's effective permissions are the intersection of the role's policies and this session policy, so it can only restrict, never grant, access. Pass it only when the user wants to limit what the run's tasks can reach (for example, restrict S3 access to specific buckets). For batch runs it is set in `defaultRunSetting`. See the [Session Policies SOP](./session-policy.md). + +> **Tooling support**: `sessionPolicy` is part of the HealthOmics REST API but is not exposed by every AWS CLI/SDK/MCP client version. Confirm the client you use accepts it before relying on it (e.g., `aws omics start-run help` should list `--session-policy`); older clients reject it as an unknown parameter. + ### Engine Settings `StartRun` accepts an `engineSettings` map that customizes how HealthOmics invokes the workflow engine. The map is engine-agnostic in concept; today only Nextflow keys are implemented, so pass it only for Nextflow workflows. Pass it only when the user requests the corresponding behavior. diff --git a/aws-healthomics/steering/session-policy.md b/aws-healthomics/steering/session-policy.md new file mode 100644 index 00000000..ed431b07 --- /dev/null +++ b/aws-healthomics/steering/session-policy.md @@ -0,0 +1,83 @@ +# Session Policies + +## Purpose + +This document describes how to scope down the IAM permissions of a HealthOmics +workflow run using an inline **session policy**, supplied via the `sessionPolicy` +parameter on `StartRun` (and `StartRunBatch`). + +## When to Reference This Document + +Reference this document when: +- The user wants to restrict what a run's tasks are allowed to access (for + example, limit S3 access to specific buckets/prefixes) beyond what the run's + IAM role already grants. +- The user asks about the `sessionPolicy` parameter on `StartRun` or `StartRunBatch`. +- The user encounters a `ValidationException` referencing `sessionPolicy`, or an + `AccessDenied` / `403` at run time that may be caused by a restrictive session policy. + +## What It Is + +`sessionPolicy` is an **optional inline IAM policy, provided as a JSON string**, +that further scopes down the permissions of the IAM role passed in `roleArn` for +that run. The run's effective permissions are the **intersection** of the role's +identity-based policies and this session policy — a session policy can only +*restrict*, never *grant*, permissions. + +This is the same concept as an AWS STS assume-role session policy: HealthOmics +assumes the run's role with the customer-provided policy attached, so every task +in the run operates under the intersected permissions. + +## How to Specify It + +- **Single run:** pass `sessionPolicy` on `StartRun`. +- **Batch run:** pass `sessionPolicy` inside `defaultRunSetting` on `StartRunBatch`; + it applies to every run in the batch. + +`GetRun` returns the `sessionPolicy` that was supplied for a run. + +## Constraints + +- Must be a valid JSON **object** (an IAM policy document). +- Length **1–2048 characters** (the AWS STS session-policy limit). +- A malformed (non-JSON / non-object) or oversized (>2048 character) policy is + rejected synchronously at `StartRun` / `StartRunBatch` with a `ValidationException`. + +## Runtime Behavior + +Because the effective permissions are the intersection, a session policy that +denies (or fails to allow) a resource the run legitimately needs will cause the +run's tasks to fail at run time with an access error (for example, a `403` on an +S3 object). When helping a user debug a failed run that uses a session policy, +check whether the policy is too restrictive for the resources the workflow accesses. + +## Example + +A session policy that scopes the run's S3 access down to just its own output +bucket (the role's other permissions still apply only if this policy also allows +them, since the effective set is the intersection): + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:ListBucket" + ], + "Resource": [ + "arn:aws:s3:::", + "arn:aws:s3:::/*" + ] + } + ] +} +``` + +## Related Documentation +- For running a workflow, see [Running a Workflow SOP](./running-a-workflow.md) +- For batch runs, see [Batch Runs SOP](./batch-runs.md) +- For diagnosing run failures, see [Diagnose Run Failure SOP](./diagnose-run-failure.md)