Setup Aws Iam
Connect a new AWS account to Nuphos with the user's local aws CLI: pick a role, grant the Nuphos connector trust, and register it with createconnector.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Setup Aws Iam when an AI agent needs a reusable SKILL.md workflow for this job: Connect a new AWS account to Nuphos with the user's local aws CLI: pick a role, grant the Nuphos connector trust, and register it with createconnector.
When not to use it
Skip Setup Aws Iam when the task is outside the productivity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/setup-aws-iam # Save SKILL.md to ~/.claude/skills/setup-aws-iam/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/setup-aws-iam/SKILL.md. For a shared project, commit the folder at .claude/skills/setup-aws-iam/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Setup Aws Iam skill for this task: Use Setup Aws Iam when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 76/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Setup AWS IAM (local aws cli)
Use this skill to onboard a fresh AWS account into Nuphos end-to-end, driven by the **user's own `aws` cli** on their local machine. The end state is an AWS role that the Nuphos connector can assume, registered as a team binding.
This is the bootstrap path for an account Nuphos is **not yet connected to**. Once a role is bound, use the `aws` skill (sandbox, Nuphos-minted creds) for day-to-day operations instead.
## CRITICAL — two execution environments
This flow spans two different tools. Getting this wrong is the #1 failure mode:
| Steps | Tool | Credentials | Why | | --- | --- | --- | --- | | 1–3 (list roles, set trust policy) | **`local_exec`** | the user's local `~/.aws` (their IAM-admin identity) | The account isn't bound yet, so the sandbox cannot mint creds for it. Only the user's own cli can read/modify IAM here. | | 4 (bind) | **`create_connector` MCP tool** | current conversation’s user and team | Reuses the Add connector validation and saves the connection directly. |
Do **not** try to run the IAM setup commands through the sandbox `bash` tool — the sandbox has no access to the user's local AWS credentials. Run every step-1-to-3 command via the `local_exec` tool.
## How the Nuphos connector authenticates
Nuphos uses OIDC web-identity federation. It pins the role to the user's team cryptographically (AWS verifies the `sub` claim in a Nuphos-signed token), so no other team can assume the role through Nuphos and no long-lived AWS credentials exist anywhere in the chain.
Discover the issuer first: `GET /.well-known/openid-configuration` on the Nuphos API base URL returns `{ "issuer": "https://<issuer-host>", ... }`. A 404 with `oidc_not_configured` means AWS account binding is unavailable on that server until its OIDC signing key is configured. You also need the user's **team id** (the hex id from `/teams`).
The customer account needs (a) an IAM OIDC identity provider for the issuer (one per AWS account), and (b) a role trusting it:
```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::<customer-account-id>:oidc-provider/<issuer-host>" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "<issuer-host>:aud": "sts.amazonaws.com", "<issuer-host>:sub": "nuphos:team:<team-id>" } } } ] } ```
The `sub` condition is the security boundary — never write it with a wildcard or omit it.
## Workflow
### 1. Confirm the local identity and target account (`local_exec`)
```bash aws sts get-caller-identity ```
Show the user the `Account` and `Arn`. Confirm this is the account they want to connect and that the identity can manage IAM (create/update roles). If the wrong account/profile is active, ask them to set `AWS_PROFILE` or `--profile` and stop.
### 2. List existing roles (`local_exec`)
```bash aws iam list-roles --query 'Roles[].RoleName' --output text # Inspect one role's current trust policy before touching it: aws iam get-role --role-name <name> \ --query 'Role.AssumeRolePolicyDocument' ```
### 3. Grant the Nuphos connector trust (`local_exec`)
**Prefer a dedicated role.** Widening an existing high-privilege role's trust to an external principal is risky — recommend creating a purpose-built role unless the user insists on an existing one.
**Create a dedicated role with OIDC trust:**
```bash # One-time per AWS account — register the Nuphos OIDC provider. If it already # exists (EntityAlreadyExists), reuse it. aws iam create-open-id-connect-provider \ --url https://<issuer-host> \ --client-id-list sts.amazonaws.com
cat > /tmp/nuphos-trust.json <<JSON { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::<customer-account-id>:oidc-provider/<issuer-host>" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "<issuer-host>:aud": "sts.amazonaws.com", "<issuer-host>:sub": "nuphos:team:<team-id>" } } } ] } JSON
aws iam create-role \ --role-name nuphos-connector \ --assume-role-policy-document file:///tmp/nuphos-trust.json \ --description "Assumed by the Nuphos BYOS connector (OIDC web identity)"
# Attach whatever permissions Nuphos should have. Scope to least privilege; # confirm the policy set with the user before attaching. Example (read-only): aws iam attach-role-policy --role-name nuphos-connector \ --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess ```
**Or add OIDC trust to an existing role (only if requested):**
`update-assume-role-policy` **replaces** the whole trust document. Never clobber existing trusted principals — fetch the current policy with `get-role` (step 2), merge the Nuphos principal in, then write the merged document back. Warn the user that this widens who can assume that role.
After either option, capture the role ARN:
```bash aws iam get-role --role-name nuphos-connector --query 'Role.Arn' --output text ```
### 4. Finish the connection (`create_connector` MCP)
Once the requested role is ready, call `create_connector` with a short `label` and:
```json { "connector": { "provider": "aws", "roleArn": "arn:aws:iam::<account>:role/nuphos-connector" } } ```
The current conversation supplies the team and acting user. The user must be a team **ADMINISTRATOR**. Do not ask them to copy the ARN or press Add connector; their request to connect the account includes this final registration step. Never submit access keys, tokens, or a different team ID to the tool.
The backend **verifies it can actually assume the role before it persists the binding** using OIDC web identity — the only way Nuphos assumes an AWS role. It retries briefly for IAM propagation. If it returns `400 role_not_assumable`, the trust policy from step 3 hasn't propagated or is wrong — wait a few seconds and retry, or re-check the trust document; the `sub` must be exactly `nuphos:team:<team-id>` for the binding team. A successful tool result means the binding is live and already assume-verified.
### 5. Confirm it works
Round-trip a read route on the new account to prove end-to-end access, e.g.:
```bash ac /teams/$TEAM/aws-accounts | python3 -m json.tool # or list the account's EKS clusters via the documented route ```
## Safety
- **Never run IAM-mutating commands without the user's explicit go-ahead.** Summarize the exact role name, trust principal, and attached policies first. - **`create-role` / `attach-role-policy` / `update-assume-role-policy` are mutations** — they happen on the user's real account via their own creds. Treat them like any other confirmed write. - **Least privilege.** Don't default to `AdministratorAccess`. Propose the narrowest managed/custom policy that satisfies what the user wants Nuphos to do. - **Don't echo secrets.** If any command surfaces keys or tokens, summarize rather than printing them.
Intended uses
- Use Setup Aws Iam when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.