Files
PaperClipAI/doc/connections/AWS.md
T
deacaf727c feat(connections): guided AWS role setup with a per-connection CloudFormation template (#22233)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The AWS connector (#22195) lets agents use AWS with credentials
minted per connection. Its role method stores no AWS keys
> - That method needs the customer to create an IAM role that trusts
exactly one Paperclip connection, but setup only offered the generic
form and a doc
> - The connect API also refused the draft step this method needs, so
the role method could not be set up through the UI at all
> - This pull request adds a guided setup screen. Paperclip saves a
draft, hands the user a prompt for their own agent that creates the
role, takes back the role ARN the agent reports, and tests the same
draft. CloudFormation and IAM steps are there under "Or do it by hand"
> - The benefit is that a person can connect AWS without stored keys and
without typing account details, using a template AWS has validated

## Linked Issues or Issue Description

Refs #22195.

**Subsystem affected**
Connections (AWS connector setup), UI, tool-access API.

**Problem or motivation**
The AWS role method must save a connection before AWS can trust it. The
API rejected `saveDraft` for every method except custom MCP servers, so
the UI could not complete this flow. There was also no screen that
showed the issuer, the subject, the trust policy or a template.

**Proposed solution**
- The connect API accepts `saveDraft` for methods that declare
`credentialMinter`.
- `GET /tool-connections/:id/aws-setup` returns the setup values and a
CloudFormation template generated for that connection.
- A new `AwsRoleSetup` step runs between saving the draft and testing
it. The role is named after the connection and CloudFormation fills in
the account, so the first form no longer asks for a role ARN; the user
pastes it back once the role exists.

**Alternatives considered**
- A one-click CloudFormation quick-create link. Rejected: AWS accepts
quick-create templates only from Amazon S3, so Paperclip would need to
host a public template bucket. The screen offers a download and a
console link instead.
- Instructions in a doc only. Rejected: too many hand-copied values.
- Asking for the role ARN up front. Rejected: the role does not exist
yet, so users had to invent an ARN and then match it exactly.
- Letting the user's agent report the role ARN to Paperclip itself,
through a short-lived link. Not done here: it needs a new
unauthenticated endpoint (and a Paperclip Cloud front-door change). The
user pastes the ARN instead.

## What Changed

- `packages/shared`:
  - The `saveDraft` validation allows methods with minted credentials.
  - New `AwsConnectionSetup` type.
- `server/src/services/connectors/aws/setup.ts` builds the setup values:
  - The issuer, audience and connection subject.
  - The provider host and the trust policy.
- A CloudFormation template with an optional identity provider
(`CreateIdentityProvider`), a role named `paperclip-<connection id>`,
`AccessPolicyArn` (`ReadOnlyAccess` by default for read-only
connections) and `AWSMCPSignInOAuthAccessPolicy`. The account comes from
CloudFormation, so the template needs no edits.
- The service method `getAwsSetup` and the route `GET
/api/tool-connections/{connectionId}/aws-setup`:
  - The route requires `connections:configure`.
  - It returns 422 for a connection that is not an AWS role connection.
- It reports whether the issuer key is published and any role ARN
already saved.
- It returns `available: false` (`address_changed`) when the instance
address changed after the draft was saved, since a role set up for the
old address could never pass the test.
  - It is registered in OpenAPI.
- UI:
- The AWS form no longer shows a Role ARN field (it is hidden with an
empty default).
- `AwsRoleSetup.tsx` shows, by default, only "Set it up with your agent"
(a copyable prompt that checks the AWS account, deploys the template
with `aws cloudformation deploy`, and reports the role ARN) and a field
to paste that ARN. "Or do it by hand" reveals the CloudFormation steps
(download, console link, parameter notes, IAM acknowledgement) and the
IAM console / AWS CLI steps with copyable values; the CLI commands read
the account ID themselves.
- It shows an access-key message when AWS cannot reach the instance, and
asks the user to save again when the instance address changed.
- Failed tests appear in place. AWS error codes show the server's own
plain message, because the shared error copy replaces every 502 with
"temporarily unavailable".
- `useAwsRoleSetupStep` owns the AWS sequence; `ConnectionSetupFlow`
only asks it for request options, hands back results and renders its
step:
- The first Connect for `aws-role` saves a draft and opens the AWS step.
  - "Test connection" resumes the same draft with the pasted role ARN.
- Back keeps the draft, so a later Connect updates it and does not
create a second one. Returning to an unfinished draft reopens the step.
- Docs: the `doc/connections/AWS.md` setup section and the plan's phase
table. The SDK public input pins are refreshed.

## Verification

- `server/src/__tests__/aws-mcp-connector.test.ts` covers a new
API-level case through the real route validation:
- Saving an `aws-role` draft over HTTP works without a role ARN, and
stores the keys the screen uses to reopen it.
- `aws-setup` returns the issuer, subject and the connection's role
name.
- The template's trust condition keys equal `<issuer host>:aud` and
`<issuer host>:sub`.
  - The template provider URL equals the issuer.
- After an address change it returns `address_changed`, and saving the
draft again records the new address.
  - An access-key connection returns 422.
  - No response field looks like a secret.
- `ui/src/features/connections/AwsRoleSetup.test.tsx` covers:
- Only the agent setup shows by default; Test connection stays off until
a valid role ARN is pasted, then sends it.
  - A saved role ARN is filled in.
- The by-hand steps and CLI commands; the agent prompt for read-only and
full access.
  - The template download (filename and object URL cleanup).
  - The unreachable-instance message.
  - The in-place error and the address-changed message.
  - The AWS message mapping.
- `ui/src/pages/apps/AppsConnect.test.tsx` covers the full two-step
flow: the form has no Role ARN field, the first Connect sends
`saveDraft: true` with no role ARN and does not finish, the AWS step
loads the setup, and "Test connection" resumes `aws-draft` with the
pasted role ARN and finishes. A second test reopens the step for a
returning draft.
- Red/green:
  - Removing the API change fails the API test.
  - Removing the draft-first wiring fails the flow test.
- Totals: server AWS, OpenAPI and connector tests (75), shared
`app-definitions` (42), UI connections and apps pages (1108). Typecheck
is clean for shared, server, UI (except Storybook's generated catalog,
which this worktree has not built) and all four server test-tree layers.
- Browser, on a real dev server with an HTTPS public address:
  - AWS appears in Connectors with its logo.
- The form has only region and access level. Connect saves the draft
(reusing an earlier one) and shows only the agent prompt and the role
ARN field; "Or do it by hand" reveals the CloudFormation and IAM steps.
- The copied prompt names the connection's role and stack, and the
template.
- Test connection with a pasted role ARN showed AWS's refusal in place
(no such role, placeholder issuer), as expected. An earlier run found
the generic 502 copy problem, which is fixed and re-checked.
- AWS CloudFormation `validate-template` (dev account, read-only)
accepts the current generated template (role named after the connection)
and reports `CAPABILITY_NAMED_IAM`. The screen tells the user to
acknowledge it.
- Not run: an agent actually running the prompt and creating a stack in
AWS, and Paperclip Cloud staging.

## Risks

- The feature is still behind `enableAwsConnector` (off by default). No
migration.
- The template creates IAM resources in the customer's account, and the
customer must acknowledge that. The role trusts only this connection's
subject.
- If the customer already has an identity provider for the issuer and
leaves `CreateIdentityProvider` at true, AWS fails the stack with a
clear error. The screen explains the parameter.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, the in-app browser against a local dev server, AWS
CLI `validate-template` in the dev account, an exploration subagent).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-19 10:53:53 -06:00

9.4 KiB

AWS

The AWS connection lets agents work in an AWS account through AWS's hosted MCP server (https://aws-mcp.<region>.api.aws/mcp). Paperclip stores no long-lived AWS key for the role method. For each connection, the control plane mints a one-hour bearer token at call time. Agents see the AWS tools like any other connector's tools and never receive AWS credentials.

It is behind the enableAwsConnector experimental setting (off by default). The design and the spike that proved it are in the AWS connector plan and the workload identity issuer.

Vendor

  • App key: aws
  • App name: AWS
  • Reuse classification: MCP-direct (AWS-hosted MCP server), with credentials minted by Paperclip.
  • Security tier: S4
  • Plugin needed? No

Transport and auth

  • Transport: mcp_remote. The endpoint is chosen from AWS's eight published regions. Tool calls need an initialized MCP session (mcpSessionRequired).

  • Auth: the method declares credentialMinter: "aws_mcp". Stored credential fields are inputs to the minter and are never sent as headers. The gateway and connection health checks resolve the Authorization header in server/src/services/connectors/aws/mcp-credentials.ts.

  • Role method (aws-role, recommended): no stored keys.

    1. The connection proves itself with a 5-minute token signed by the company's workload identity issuer (sub = connection:<id>, aud = sts.amazonaws.com).
    2. STS AssumeRoleWithWebIdentity returns role credentials.
    3. AWS Sign-in CreateOAuth2TokenWithIAM (client_credentials, resource aws-mcp.amazonaws.com) returns the bearer token.

    This method needs a public HTTPS address that AWS can reach.

  • Access-key method (aws-access-key): a dedicated IAM user's key, stored as this connection's vault secrets (credentials.accessKeyId, credentials.secretAccessKey). Read only uses GetFederationToken. Full access uses the key directly. With a role ARN, the minter uses AssumeRole. This method works on any instance, including local ones.

  • Access level is set per connection:

    • read_only (the default) adds ReadOnlyAccess and AWSMCPSignInOAuthAccessPolicy as session policies, so AWS refuses changes even when the role allows them. Without the second policy, the token exchange fails.
    • full uses everything the role or key allows.
  • Caching: the token is cached in memory for each connection and grant until about 55 minutes in. It is minted again when these change:

    • the saved settings;
    • the stored key references;
    • connection or grant status.

    When AWS answers 401, the gateway mints a fresh token and does not replay the call. The caller retries. Catalog discovery lists again automatically.

  • Revocation: delete the connection, or remove the role's trust or the IAM user's key in AWS. Tokens already issued expire within the hour.

Connection flow

sequenceDiagram
    participant Agent
    participant Gateway as Paperclip control plane
    participant STS as AWS STS
    participant Signin as AWS Sign-in
    participant MCP as AWS MCP server
    Agent->>Gateway: tools/call aws___run_script
    Gateway->>Gateway: sign connection token (cached bearer skips the next three steps)
    Gateway->>STS: AssumeRoleWithWebIdentity (role, token, read-only policies)
    STS->>Gateway: fetches issuer JWKS, returns role credentials
    Gateway->>Signin: CreateOAuth2TokenWithIAM (SigV4 with role credentials)
    Signin->>Gateway: bearer token (1 hour)
    Gateway->>MCP: tools/call with Authorization Bearer
    MCP->>Gateway: result (AWS ran the script in its sandbox)
    Gateway->>Agent: result
  • Issuer discovery: GET /oidc/companies/<companyId>/.well-known/openid-configuration
  • Issuer keys: GET /oidc/companies/<companyId>/jwks.json
  • Paperclip callback: none.
  • Paperclip ID / Paperclip Connect involvement: none. The instance is its own OIDC issuer.

Administrator setup

The role method takes two steps, because the role must trust a connection that already exists. The setup screen walks through them:

  1. Turn on AWS connector in Instance Settings, Experimental.

  2. In Connectors, open AWS. Choose the endpoint region and the access level, then click Connect. There is no role ARN to enter yet: the role does not exist until the next step creates it.

  3. Paperclip saves a draft without contacting AWS and publishes the company's issuer. The role is named after the connection (paperclip-<connection id>), and CloudFormation fills in the account, so nothing is typed by hand. The screen shows one thing by default:

    • Set it up with your agent copies a prompt for an agent (Claude Code, Codex) on a computer signed in to the AWS account. The agent checks which account the CLI uses, checks for an existing identity provider, deploys the template with aws cloudformation deploy and reports the stack's RoleArn output. For full access it asks which policy to attach. The prompt holds no secret.
    • Paste that role ARN into the field below the prompt.

    Or do it by hand shows the same setup without an agent:

    • With CloudFormation. Download the template, create a stack from it in the AWS account, set CreateIdentityProvider to false if the account already has an identity provider for this issuer, choose AccessPolicyArn for full access, and acknowledge that the stack creates IAM resources (CAPABILITY_NAMED_IAM). Copy RoleArn from the stack's outputs.
    • In the IAM console or AWS CLI. Add an OpenID Connect provider with the shown provider URL and audience, then create the role with the shown trust policy (replace ACCOUNT_ID), which trusts only connection:<id>. Attach AWSMCPSignInOAuthAccessPolicy and the agents' permissions. The CLI commands read the account ID themselves and print the role ARN.

    If the instance's address changed after the draft was saved, the screen shows no steps and asks you to go back and click Connect again, which saves the draft with the current address.

  4. Click Test connection. Paperclip saves the role ARN, mints a token, lists the tools and finishes setup. If AWS refuses, the screen shows why, in place.

The screen reads GET /api/tool-connections/{connectionId}/aws-setup, which returns the issuer, audience, subject, trust policy and template, and never a secret. AWS hosts quick-create links only for templates stored in Amazon S3, so Paperclip offers a download instead of a hosted template.

For the access-key method, create a dedicated IAM user with AWSMCPSignInOAuthAccessPolicy, sts:GetFederationToken and the agents' permissions. Then connect with the key. Setup lists the tools immediately.

Verify: the connection lists 8 tools. A test call of aws___run_script that runs ListBuckets succeeds. With read-only access, a CreateBucket call is refused by AWS with "no session policy allows".

Tools and risk

Reviewed tool risk is declared in the app definition:

  • Writes: aws___run_script (the only tool that calls AWS APIs) and aws___get_presigned_url.
  • Reads: documentation search and read, skills, regions, regional availability and task status.
  • Unlisted tools: treated as writes.

Read-only connections are enforced by AWS through the session policy, not by hiding run_script.

Failure codes

Each code appears on the connection's health with a plain message. AWS's own error text is never shown, because it can contain account IDs and ARNs.

Code Health Meaning
aws_mcp_settings_invalid error Saved settings are incomplete, or the URL is not AWS's endpoint for the saved region.
aws_identity_unavailable error The role method needs a stable public HTTPS address.
aws_issuer_changed error The instance's address changed since setup. Register the new issuer in AWS (and update the role's trust), then reconnect: reconnecting records the current address.
aws_role_access_denied error AWS refused the role: it is missing, or its trust does not match this connection.
aws_access_key_invalid error The access key is invalid or inactive, or the user cannot call GetFederationToken.
aws_mcp_signin_denied error The token exchange was refused. Attach AWSMCPSignInOAuthAccessPolicy.
aws_unavailable degraded AWS did not respond, or throttled the request.

Verification record

On 2026-11-18, the integrated path ran against the Paperclip dev AWS account. It used Paperclip's own setup, catalog and gateway code, real STS and Sign-in, and AWS's MCP server. The issuer was behind a temporary public tunnel.

  • Access key, read only: 8 tools listed. run_script ListBuckets succeeded in 8.9 s (cold sandbox). CreateBucket was refused by the session policy.
  • Role: the draft was saved without contacting AWS, and the issuer was published. After the IAM provider and a role trusting only that connection were created, resuming setup listed 8 tools. ListBuckets succeeded in 12.8 s (cold sandbox). CreateBucket was refused by the role's own permissions.

All IAM users, keys, roles, providers and buckets were deleted afterwards.

Not live-tested yet: Paperclip Cloud staging, the CloudFormation template (not built yet), and AssumeRole from an access key with a role ARN (covered by unit tests only).