home / skills / plurigrid / asi / aws-sso-auth-guide

aws-sso-auth-guide skill

needs review

This skill guides you through discovering, configuring, and using AWS SSO from the terminal, simplifying profile setup and login workflows.

npx playbooks add skill plurigrid/asi --skill aws-sso-auth-guide

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.0 KB

---
name: aws-sso-auth-guide
description: AWS SSO discovery, configuration, and terminal usage
license: MIT
tags:
  - aws
  - sso
  - authentication
  - iam-identity-center
metadata:
  author: Stakpak <[email protected]>
  version: "1.0.2"
---

# AWS SSO Terminal Guide

## Discovery: Finding SSO Configuration

### Get SSO Instance & Portal URL

```bash
# From management account
aws sso-admin list-instances --profile <mgmt-profile>
# Returns: InstanceArn, IdentityStoreId (d-xxxxxxxxxx), OwnerAccountId

# Portal URL format: https://d-xxxxxxxxxx.awsapps.com/start
```

### List Accounts & Permission Sets

```bash
# List organization accounts
aws organizations list-accounts --profile <mgmt-profile>

# List permission sets
aws sso-admin list-permission-sets \
  --instance-arn <instance-arn> \
  --profile <mgmt-profile>

# Get permission set name
aws sso-admin describe-permission-set \
  --instance-arn <instance-arn> \
  --permission-set-arn <ps-arn> \
  --profile <mgmt-profile>

# Check account assignments
aws sso-admin list-account-assignments \
  --instance-arn <instance-arn> \
  --account-id <account-id> \
  --permission-set-arn <ps-arn> \
  --profile <mgmt-profile>
```

## Configuration

### Profile Structure (Recommended)

```ini
# ~/.aws/config

[profile my-profile]
sso_session = my-sso
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = us-east-1

[sso-session my-sso]
sso_start_url = https://d-xxxxxxxxxx.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access
```

**Benefits:** Token reuse across profiles, automatic refresh (CLI v2.22.0+)

### Interactive Configuration

```bash
aws configure sso
```

## Authentication

### Login Flow

```bash
# Login (PKCE auth - default in CLI v2.22.0+)
aws sso login --profile my-profile

# Login with device code (for headless/remote)
aws sso login --profile my-profile --use-device-code

# Verify
aws sts get-caller-identity --profile my-profile
```

**Token Cache:** `~/.aws/sso/cache/`

## Key Endpoints & Flow

- `oidc.{region}.amazonaws.com` - OIDC authentication
- `portal.sso.{region}.amazonaws.com` - SSO portal
- Auth flow: `RegisterClient` → `StartDeviceAuthorization` → `CreateToken`

## Troubleshooting

**Missing SSO Configuration:**

```bash
# Error: Missing sso_start_url, sso_region
# Fix: aws configure sso
```

**Expired Token:**

```bash
# Error: Token is expired
# Fix: aws sso login --profile my-profile
```

**Proxy SSL Issues:**

```bash
# Error: SSL certificate verification failed
# Fix: Set AWS_CA_BUNDLE to proxy CA certificate
export AWS_CA_BUNDLE=/path/to/proxy-ca.crt
```

**Access Denied:**

```bash
# Check permission set assignments
aws sso-admin list-account-assignments \
  --instance-arn <arn> \
  --account-id <id> \
  --permission-set-arn <ps-arn>
```

## Quick Reference

**CLI Versions:**

- v2.22.0+: PKCE auth (default), auto-refresh
- < v2.22.0: Device code auth

**Authorization Types:**

- **PKCE**: Same-device, browser required
- **Device Code**: Cross-device, browser optional

Overview

This skill provides a focused command-line guide for discovering, configuring, and using AWS Single Sign-On (SSO) from the terminal. It explains how to find SSO instances, build reusable profiles, perform CLI logins (including headless flows), and resolve common issues. The content is concise and aimed at engineers who need reliable terminal-based SSO workflows.

How this skill works

The skill outlines discovery steps to locate the SSO instance ARN, identity store ID, and portal URL using management-account AWS CLI calls. It shows how to structure ~/.aws/config with sso-session blocks for token reuse and automatic refresh, and how to authenticate using PKCE or device-code flows. It also summarizes key endpoints, auth flow steps, token cache location, and troubleshooting commands.

When to use it

Setting up or auditing AWS SSO access from developer workstations or CI runners.
Creating multiple profiles that share an SSO session and token refresh behavior.
Logging into AWS from headless or remote environments using device code auth.
Troubleshooting login failures, expired tokens, or proxy SSL issues.
Verifying account and permission-set assignments from the management account.

Best practices

Use sso-session blocks in ~/.aws/config to share and reuse tokens across profiles.
Prefer CLI v2.22.0+ for PKCE-based, same-device browser login and automatic refresh.
Use device-code (--use-device-code) only for headless or unsupported browser environments.
Keep the sso cache (~/.aws/sso/cache/) secure and back up nothing sensitive from it.
Validate permission-set assignments from the management account before troubleshooting access denied errors.

Example use cases

Discover your SSO portal URL from the management account with aws sso-admin list-instances.
Create a profile that reuses an sso-session to manage tokens across multiple AWS accounts.
Log in on a remote server using aws sso login --use-device-code, then confirm with aws sts get-caller-identity.
Diagnose an expired token by re-running aws sso login for the affected profile.
Resolve proxy SSL issues by exporting AWS_CA_BUNDLE pointing to your proxy CA certificate.

FAQ

How do I find the portal start URL?

Run aws sso-admin list-instances from the management account and use the IdentityStoreId to form https://d-xxxxxxxxxx.awsapps.com/start.

Which CLI version should I use?

Use AWS CLI v2.22.0 or newer for PKCE auth and automatic token refresh; older releases use device-code flows.