Skip to content

AWS SSO Authentication

StormTunnel can authenticate AWS Session Manager tunnels using IAM Identity Center (SSO) tokens. It monitors token expiry and refreshes them automatically.

Prerequisites

  • AWS CLI v2 installed
  • An SSO profile configured in ~/.aws/config (via aws configure sso or manually)
  • Your SSO permission set includes ssm:StartSession, ssm:TerminateSession, and ec2:DescribeInstances

Setup

1. Add an SSO profile

If you don't already have one in ~/.aws/config:

[profile my-sso-profile]
sso_start_url = https://my-org.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = PowerUserAccess
region = us-east-1

2. Log in

Run aws sso login --profile my-sso-profile in Terminal, or let StormTunnel open the browser when you first connect a tunnel that uses this profile.

3. Create a tunnel

  1. Click + and select AWS Session Manager.
  2. Enter the SSO profile name in the AWS Profile field.
  3. Fill in region, instance ID, and ports.
  4. Click Save.

Token lifecycle

StormTunnel checks token validity every 60 seconds and refreshes silently 5 minutes before expiry. If a silent refresh fails, a notification badge appears on the tunnel. Click Authenticate to re-open the SSO portal in your browser; the tunnel reconnects once you complete login.

Tokens are stored in macOS Keychain and shared with AWS CLI -- authenticating in either tool covers both.

IdP session expiry

When your identity provider session expires (duration set by your org), no silent refresh is possible. You must re-authenticate through the browser.

Multiple profiles

Each profile gets its own Keychain entry and independent refresh cycle:

[profile dev-sso]
sso_start_url = https://my-org.awsapps.com/start
sso_account_id = 111111111111
sso_role_name = DeveloperAccess
region = us-east-1

[profile prod-sso]
sso_start_url = https://my-org.awsapps.com/start
sso_account_id = 222222222222
sso_role_name = ReadOnlyAccess
region = us-west-2

Settings

Under Settings > AWS:

  • Auto-refresh tokens -- toggle automatic refresh (on by default)
  • Early refresh threshold -- how far ahead of expiry to refresh (default: 5 min)
  • Refresh check interval -- polling frequency (default: 60 s)

Troubleshooting

Token expired or "SSO Authentication Required" loop

  1. Run aws sso logout then aws sso login --profile <profile>.
  2. Verify the sso_start_url in ~/.aws/config is reachable.
  3. Confirm your IdP session is still active.

Browser does not open

  1. Check that a default browser is set in System Settings > Desktop & Dock.
  2. Verify StormTunnel is allowed to open URLs (no MDM restriction blocking it).

Permission denied after login

Your SSO permission set is missing required SSM actions. Ask your AWS admin to add ssm:StartSession and related permissions.