First-class AWS SSO / IAM role assumption support in model execution

[andrewboyd79]

Problem

IAM users with long-lived access keys are a deprecated pattern. AWS SSO (IAM Identity Center) and role assumption are now the standard authentication approach across organisations. Today, swamp has no first-class support for this:

• Model globalArguments for AWS integrations only accept static credential fields (awsAccessKeyId, awsSecretAccessKey, awsSessionToken)
• When an SSO session expires mid-workflow, the failure surfaces deep inside a scan step with a generic credentials error rather than a clear, actionable message
• There is no pre-flight session validation hook in the workflow execution lifecycle
• Users must manually run aws sso login before each workflow run and hope the session does not expire during execution

Proposed Solution

First-class SSO/role assumption support should be a core capability, not a workaround. The following improvements would address this:

1. AWS profile support in execution context
Model execution should natively support an awsProfile concept that is resolved through the standard AWS credential chain (SSO token cache, credential process, instance profile, environment). A user should be able to declare the profile name and swamp handles the rest.

2. Pre-flight credential validation
Before executing any AWS-dependent model method, swamp should verify the resolved credentials are valid (e.g. via sts:GetCallerIdentity) and fail fast with a clear, actionable error if they are not — including a hint about how to refresh (e.g. aws sso login --sso-session <name>).

3. Credential process / auto-refresh support
Where the AWS profile is configured with a credential_process (e.g. aws-sso-util, custom scripts), swamp's execution environment should invoke it transparently at runtime rather than relying on statically resolved credentials baked into the model input.

4. Role chaining / assume-role
Support for specifying a role ARN to assume at execution time, using the resolved base credentials, so that cross-account access patterns work cleanly without pre-staging credentials.

Alternatives Considered

• Vault with credential rotation: Storing SSO-derived short-lived credentials in a swamp vault before each run. This requires a manual pre-step, reintroduces the rotation problem the user was trying to avoid, and is operationally brittle.
• Wrapper scripts: Shelling out to aws sso login as a first workflow job. aws sso login is inherently interactive (browser-based); it cannot run unattended.
• Environment variables: Exporting credentials into the shell environment before running the workflow. Works for single-account use cases but does not scale to multi-account workflows where each job needs a different identity.

Additional Context

This came up while building a multi-account S3 audit workflow. Five parallel scan jobs each target a different AWS account via SSO profiles. The workaround (adding awsProfile to the model schema and passing AWS_PROFILE through the execution environment) works once a session is established, but the workflow has no way to ensure the session is active, validate it before starting, or recover gracefully when it expires. SSO/role assumption is the norm in any organisation that takes security posture seriously — it should be a first-class citizen in swamp.

[stack72]

Hey @andrewboyd79

Thanks for opening the issue here - can you tell me what model you found this issue with? Was it something you generated?

Paul

[stack72]

Following up here with some findings after investigating:

Environment variable passthrough already works. Deno merges env vars with the parent environment rather than replacing it, so AWS_PROFILE, PATH, SSO token cache paths, etc. are all available to subprocesses even when a model passes additional env vars. The AWS SDK credential chain in the vault provider also picks up AWS_PROFILE from the parent environment automatically.

The globalArguments schema is defined by the model author, not the framework. A model can accept awsProfile as a global argument and pass it as --profile to every AWS CLI call, letting the SDK credential chain handle SSO, credential_process, and role assumption.

Pre-flight credential validation belongs in the model. The model is the domain expert for its service. Here's the pattern we'd recommend — adding a validateCredentials() helper that calls sts get-caller-identity before any real work and fails fast with an actionable error:

// extensions/models/vpc.ts
import { z } from "npm:zod@4";

const GlobalArgsSchema = z.object({
  cidrBlock: z.string(),
  region: z.string().default("us-east-1"),
  awsProfile: z.string().optional(),
});

const VpcSchema = z.object({
  VpcId: z.string(),
}).passthrough();

/** Run an AWS CLI command, injecting profile if configured. */
async function awsCli(
  args: string[],
  globalArgs: { region: string; awsProfile?: string },
) {
  const fullArgs = [...args, "--region", globalArgs.region, "--output", "json"];
  if (globalArgs.awsProfile) {
    fullArgs.push("--profile", globalArgs.awsProfile);
  }
  const cmd = new Deno.Command("aws", {
    args: fullArgs,
    stdout: "piped",
    stderr: "piped",
  });
  return await cmd.output();
}

/** Validate AWS credentials before doing real work. */
async function validateCredentials(
  globalArgs: { region: string; awsProfile?: string },
) {
  const output = await awsCli(["sts", "get-caller-identity"], globalArgs);
  if (output.code !== 0) {
    const stderr = new TextDecoder().decode(output.stderr);
    const profileHint = globalArgs.awsProfile
      ? `\n  aws sso login --profile ${globalArgs.awsProfile}`
      : "";
    throw new Error(
      `AWS credential check failed: ${stderr.trim()}\n\n` +
        `Ensure your credentials are valid.${profileHint}`,
    );
  }
}

export const model = {
  type: "@user/vpc",
  version: "2026.02.10.1",
  globalArguments: GlobalArgsSchema,
  resources: {
    "vpc": {
      description: "VPC resource state",
      schema: VpcSchema,
      lifetime: "infinite",
      garbageCollection: 10,
    },
  },
  methods: {
    create: {
      description: "Create a VPC",
      arguments: z.object({}),
      execute: async (_args, context) => {
        const { cidrBlock, region, awsProfile } = context.globalArgs;

        await validateCredentials({ region, awsProfile });

        const output = await awsCli(
          ["ec2", "create-vpc", "--cidr-block", cidrBlock],
          { region, awsProfile },
        );

        if (output.code !== 0) {
          const stderr = new TextDecoder().decode(output.stderr);
          throw new Error(`Failed to create VPC: ${stderr.trim()}`);
        }

        const vpcData =
          JSON.parse(new TextDecoder().decode(output.stdout)).Vpc;
        const handle = await context.writeResource("vpc", "vpc", vpcData);
        return { dataHandles: [handle] };
      },
    },
  },
};

The key patterns are:

• awsProfile as an optional global argument — lets each model instance target a different profile/account
• awsCli() helper — centralises --profile and --region injection
• validateCredentials() — calls sts get-caller-identity before any real work, with a clear aws sso login hint on failure

If you can share the model definition you were using, happy to suggest how to restructure it to work with this pattern.

[stack72]

IF you have any follow up questions then let us know and we can re-open this