Install & Compatibility
Where this runs
tested against v1.14.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.763s · 51.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.9s · import 0.695s · 52MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_boto3_session
✓ from aws_sso_lib import get_boto3_session
Main function to get a configured boto3 session for an SSO account and role.
login
✓ from aws_sso_lib import login
Function to initiate an interactive SSO login process.
list_available_accounts
✓ from aws_sso_lib import list_available_accounts
Utility to list accounts accessible via the current SSO session.
list_available_roles
✓ from aws_sso_lib import list_available_roles
Utility to list roles available within a given account via the current SSO session.
This quickstart demonstrates how to perform an interactive SSO login and then obtain a `boto3` session for a specific AWS account and role using `aws-sso-lib`. It then uses this session to call `sts.get_caller_identity()` and `s3.list_buckets()` as an example of AWS service interaction. Ensure `AWS_SSO_START_URL`, `AWS_SSO_REGION`, `AWS_ACCOUNT_ID`, `AWS_ROLE_NAME`, and `AWS_REGION` environment variables are set or replaced with your actual values.
import os
from aws_sso_lib import login, get_boto3_session
# Ensure these environment variables are set or replace with actual values
SSO_START_URL = os.environ.get('AWS_SSO_START_URL', 'https://d-xxxxxxxxxx.awsapps.com/start')
SSO_REGION = os.environ.get('AWS_SSO_REGION', 'us-east-1') # The region where your SSO instance is configured
# You might need to know the account ID and role name for your target AWS account
TARGET_ACCOUNT_ID = os.environ.get('AWS_ACCOUNT_ID', '123456789012')
TARGET_ROLE_NAME = os.environ.get('AWS_ROLE_NAME', 'AWSAdministratorAccess')
AWS_SESSION_REGION = os.environ.get('AWS_REGION', 'us-east-1') # The region for the Boto3 session
print("Attempting SSO login...")
# The 'login' function opens a browser for authentication if credentials are expired
# or not found. It returns a token dict which is cached.
token = login(SSO_START_URL, SSO_REGION, force_refresh=False)
print("SSO login successful (or token was already valid).")
print(f"Getting boto3 session for account {TARGET_ACCOUNT_ID} with role {TARGET_ROLE_NAME} in region {AWS_SESSION_REGION}...")
# Get a boto3 session using the SSO credentials
session = get_boto3_session(
SSO_START_URL,
SSO_REGION,
TARGET_ACCOUNT_ID,
TARGET_ROLE_NAME,
region=AWS_SESSION_REGION,
login=True # Automatically logs in if session is expired
)
# Use the session to interact with AWS services
sts_client = session.client('sts')
caller_identity = sts_client.get_caller_identity()
print(f"Successfully obtained credentials for: {caller_identity['Arn']}")
# Example: List S3 buckets
s3_client = session.client('s3')
buckets = s3_client.list_buckets()
print("S3 Buckets:")
for bucket in buckets['Buckets']:
print(f"- {bucket['Name']}")
aws-sso-util --version
Errors
Common errors & fixes
Login failed: 'expiresAt'
The cached SSO token is either corrupted, missing the 'expiresAt' field, or otherwise invalid.
fixRun `aws-sso-lib.login(start_url, sso_region, force_refresh=True)` in your code, or manually delete the relevant JSON file from `~/.aws/sso/cache/` and re-attempt login.
NoCredentialProviders: no valid providers in chain.
The AWS SDK or application is unable to find valid AWS credentials, often when relying on `credential_process` configured via `aws-sso-util` but the SDK isn't configured to load it.
fixEnsure `export AWS_SDK_LOAD_CONFIG=1` is set in your environment. Also, verify your `~/.aws/config` file is correctly configured for SSO profiles.
cannot import name 'SSOTokenFetcher' from 'botocore.utils'
This usually indicates an incompatibility or conflict between the installed versions of `botocore` (often brought in by `boto3` or `awscli`) and `aws-sso-lib`, where `SSOTokenFetcher`'s location or existence in `botocore.utils` has changed.
fixEnsure `boto3` and `botocore` are at compatible versions, ideally by letting `pip` manage them through `pip install --upgrade boto3 aws-sso-lib`. Avoid manually installing conflicting versions of `botocore` if `awscli` is also installed.
failed to refresh cached credentials, the SSO session has expired or is invalid: failed to read cached SSO token file, open /home/user/.aws/sso/cache/[token_file].json: input/output error
The cached SSO token file is inaccessible due to incorrect file permissions, or the file itself is corrupted.
fixCheck file permissions for `~/.aws/sso/cache/` and its contents (`chmod 600 ~/.aws/sso/cache/*`). If permissions are correct, the file might be corrupted, in which case you should delete it and re-authenticate.
Upgrade
Version history
1.14.0latest on PyPI · released Jan 27, 2023
Audit
Dependencies
boto3requiredCore dependency for interacting with AWS services and fetching credentials.
botocorerequiredUnderlying AWS SDK for Python, a core dependency of boto3 and aws-sso-lib.