Usage Guide

Basic Usage

The AWS SSO Manager provides a simple interface for managing AWS SSO credentials. Here’s how to use it:

1. Import the package:

   from aws_sso import AWSsso
   from pathlib import Path
   

2. Create an instance:

   sso = AWSsso(
       aws_exec_file_path=r'C:\Program Files\Amazon\AWSCLIV2\aws.exe',  # Adjust path for your system
       db_path=Path('./data/credentials.db'),
       refresh_window_hours=6
   )
   

3. Use the manager:

   # Ensure credentials are valid
   sso.ensure_valid_credentials()
   
   # Get expiration time
   expiration = sso.get_expiration_time()
   print(f"Credentials will expire at: {expiration}")
   

Advanced Usage

Custom Configuration

You can customize the behavior with additional parameters:

sso = AWSsso(
    aws_exec_file_path=r'C:\Program Files\Amazon\AWSCLIV2\aws.exe',
    db_path=Path('./data/custom_credentials.db'),
    refresh_window_hours=12,  # Longer refresh window
    max_retries=5,           # More retries
    retry_delay=10           # Longer delay between retries
)

Error Handling

Handle potential errors during authentication:

from aws_sso import AWSsso, AuthenticationError, CredentialError

try:
    sso = AWSsso()
    sso.ensure_valid_credentials()
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except CredentialError as e:
    print(f"Credential error: {e}")

Context Manager

Use the context manager interface for automatic cleanup:

with AWSsso() as sso:
    sso.ensure_valid_credentials()
    # Work with AWS services...

Monitoring Credentials

Track credential status:

# Get last refresh time
last_refresh = sso.get_last_refresh_time()
if last_refresh:
    print(f"Last credential refresh: {last_refresh}")

# Check if credentials need refresh
if sso.should_refresh_credentials:
    print("Credentials need to be refreshed")
    sso.refresh_credentials()

Best Practices

1. Path Management: Use Path objects for file paths to ensure cross-platform compatibility

2. Error Handling: Always wrap credential operations in try-except blocks

3. Logging: Enable logging to track credential management:

   import logging
   logging.basicConfig(level=logging.INFO)
   

4. Database Location: Store the credentials database in a secure location

5. Regular Checks: Periodically check credential status in long-running applications

Common Issues

AWS CLI Not Found

If you get a FileNotFoundError, ensure: - AWS CLI is installed - Correct path is provided to aws_exec_file_path - AWS CLI is accessible from your environment

Authentication Failures

If authentication fails: - Check your AWS SSO configuration - Verify your internet connection - Ensure your AWS SSO session is active - Check the AWS CLI configuration

Database Errors

If you encounter database errors: - Ensure the database directory exists - Check write permissions - Verify the database path is valid