Skip to content

AWS SSO Authentication

AWS Single Sign-On (SSO) authentication provides secure, federated access to your AWS accounts through your organization's identity provider. StormTunnel supports SSO authentication with automatic token management and error recovery.

Overview

SSO authentication offers several advantages over traditional AWS credentials:

  • Federated Identity: Use your corporate credentials (Azure AD, Okta, etc.)
  • Time-Limited Access: Tokens automatically expire for security
  • Automatic Refresh: StormTunnel monitors and refreshes tokens before expiration
  • Error Recovery: Automatic retry with exponential backoff for transient failures

Prerequisites

AWS IAM Identity Center Setup

  1. Enable IAM Identity Center in your AWS Organization
  2. Connect your Identity Provider (IdP):
    • Azure AD
    • Okta
    • Google Workspace
    • SAML 2.0 provider
  3. Configure Permission Sets for users who need tunnel access

Required IAM Permissions

Your SSO permission set should include:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:StartSession",
                "ssm:TerminateSession",
                "ssm:DescribeSessions",
                "ssm:GetConnectionStatus",
                "ssm:DescribeInstanceInformation"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": ["ec2:DescribeInstances"],
            "Resource": "*"
        }
    ]
}

Setting Up SSO in StormTunnel

Step 1: Configure AWS Profile

Create or update your AWS config file (~/.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
output = json

Step 2: Initial SSO Authentication

When you first use an SSO profile, StormTunnel will:

  1. Detect the SSO configuration
  2. Open your default browser to the SSO portal
  3. Wait for you to complete authentication
  4. Store the access token securely in macOS Keychain

Step 3: Create SSO-Based Tunnel

  1. Click the + button to create a new tunnel
  2. Select AWS Session Manager as tunnel type
  3. Enter your SSO profile name in the AWS Profile field
  4. Configure the tunnel parameters (region, instance ID, ports)
  5. Click Save

Authentication Flow

First-Time Authentication

1. User creates tunnel with SSO profile
2. StormTunnel checks for valid token in Keychain
3. No token found → Browser opens to SSO portal
4. User authenticates with corporate credentials
5. AWS returns authorization code
6. StormTunnel exchanges code for access token
7. Token stored in Keychain
8. Tunnel connection established

Subsequent Connections

1. User activates tunnel
2. StormTunnel checks token in Keychain
3. Token valid → Use directly
4. Token expired → Automatic refresh
5. Refresh fails → Browser opens for re-authentication

Automatic Token Management

Token Monitoring

StormTunnel automatically monitors your SSO tokens:

  • Check Interval: Every 60 seconds
  • Early Refresh: Tokens are refreshed 5 minutes before expiration
  • Background Operation: Monitoring runs even when app is minimized

Token Refresh

When a token approaches expiration:

  1. StormTunnel attempts silent refresh using the refresh token
  2. If successful, the new token is stored automatically
  3. If refresh fails, you'll see a notification to re-authenticate

Re-Authentication Required

When re-authentication is needed:

  1. A notification badge appears on the tunnel
  2. Click the tunnel to see the re-authentication prompt
  3. Click Authenticate to open the SSO portal
  4. Complete authentication in your browser
  5. Return to StormTunnel - the tunnel will reconnect automatically

Error Recovery

StormTunnel includes intelligent error recovery for SSO authentication:

Automatic Retry

Transient failures (network issues, rate limiting) are automatically retried:

  • Exponential Backoff: Wait times increase between retries
  • Jitter: Random variation prevents thundering herd
  • Max Attempts: 5 retry attempts by default
  • Max Duration: 120 seconds total recovery time

Recovery Strategies

Error Type Recovery Strategy
Network timeout Retry with backoff
Rate limited Wait and retry (30s)
Token expired Re-authentication prompt
SSO config invalid Fail with guidance
Permission denied Contact admin prompt

Error Messages

Message Meaning Action
"SSO Authentication Required" Token expired or not found Complete SSO login
"Check Network Connection" Network issues detected Verify internet access
"Contact AWS Administrator" Permission issues Request IAM access
"Update Credentials Required" Credentials invalid Re-configure profile

Security Best Practices

Token Storage

  • Tokens are stored in macOS Keychain (encrypted)
  • Tokens are never written to disk in plaintext
  • Tokens are automatically cleared on logout

Session Security

  • Sessions use AWS-managed encryption
  • All traffic goes through AWS infrastructure
  • No SSH keys or ports exposed

Profile Isolation

  • Each AWS profile has its own token
  • Tokens are not shared between profiles
  • Switching profiles requires separate authentication

Troubleshooting

"SSO Authentication Required" Keeps Appearing

  1. Check your AWS config file is correctly formatted
  2. Verify the SSO start URL is accessible
  3. Check your IdP session hasn't expired
  4. Try aws sso logout followed by fresh authentication

Browser Doesn't Open

  1. Check your default browser is set correctly
  2. Verify StormTunnel has permission to open URLs
  3. Try manually navigating to the SSO start URL

"Token Refresh Failed"

  1. Your SSO session may have expired at the IdP
  2. Re-authenticate through the SSO portal
  3. Check for IdP maintenance or outages

Rate Limiting Issues

If you see rate limiting errors:

  1. Wait 30-60 seconds before retrying
  2. Reduce the number of concurrent tunnels
  3. Contact your AWS administrator for quota increases

Configuration Options

Token Refresh Settings

Access in Settings > AWS:

  • Auto-refresh tokens: Enable/disable automatic token refresh
  • Early refresh threshold: How early to refresh before expiration (default: 5 minutes)
  • Refresh check interval: How often to check token status (default: 60 seconds)

Recovery Settings

Configure in Settings > AWS > Advanced:

  • Max retry attempts: Number of automatic retries (default: 5)
  • Max recovery duration: Total time for recovery attempts (default: 120 seconds)
  • Enable jitter: Add randomization to retry delays (default: enabled)

Integration with AWS CLI

StormTunnel's SSO integration is compatible with AWS CLI v2:

Using AWS CLI:

  • Login to AWS: You can log in using AWS CLI in Terminal
  • StormTunnel shares the same token: Once you authenticate in either AWS CLI or StormTunnel, both can use the same SSO session
  • Logout: When you logout from AWS CLI, StormTunnel will prompt for re-authentication on next use

Benefits:

  • Single sign-on across tools
  • No need to authenticate separately
  • Token automatically shared between StormTunnel and AWS CLI

Multiple SSO Profiles

You can configure multiple SSO profiles for different accounts:

[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

Each profile:

  • Has its own token in Keychain
  • Can be authenticated independently
  • Has separate token refresh monitoring

Getting Help

If you encounter issues with SSO authentication:

  1. Check the Troubleshooting section above
  2. Review AWS IAM Identity Center documentation
  3. Contact your AWS administrator for permission issues
  4. Open StormTunnel Settings > Advanced > View Logs for detailed error information

Last Updated: 2025-12-16

Related Topics: