AWS SSO Library

1.14.0 · active · verified Thu Apr 16

aws-sso-lib is a Python library designed to programmatically interact with AWS IAM Identity Center (formerly AWS SSO). It simplifies tasks like interactive login, obtaining `boto3` sessions for specific accounts and roles, and discovering available accounts and roles. It is the underlying library for the `aws-sso-util` CLI tool. The library's release cadence is tied to its dependent CLI, with irregular updates addressing new features, bug fixes, and compatibility with AWS SDKs.

Common errors

```
Login failed: 'expiresAt'
```
cause The cached SSO token is either corrupted, missing the 'expiresAt' field, or otherwise invalid.

fix Run `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.
```
cause 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.

fix Ensure `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'
```
cause 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.

fix Ensure `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
```
cause The cached SSO token file is inaccessible due to incorrect file permissions, or the file itself is corrupted.

fix Check 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.

Warnings

breaking Support for Python 3.6 was removed in `aws-sso-lib` v1.12, aligning with `boto3`'s deprecation of Python 3.6. Ensure you are using Python 3.7 or newer.
Fix: Upgrade your Python environment to version 3.7 or higher.
breaking Changes in `botocore` (the underlying AWS SDK for Python) required updates to `aws-sso-lib`'s `get_credentials()` function and the `aws-sso-credential-process` utility in `v1.12` and `v4.29` respectively. Older versions of `aws-sso-lib` might fail to retrieve credentials or process them correctly with newer `botocore` versions.
Fix: Upgrade `aws-sso-lib` to the latest version to ensure compatibility with recent `botocore` changes.
gotcha AWS SSO tokens are short-lived and cached locally (typically in `~/.aws/sso/cache/`). If a token expires or becomes invalid, programmatic access will fail until the user re-authenticates. Errors like 'Login failed: 'expiresAt'' or 'Error loading SSO Token: The SSO access token has either expired or is otherwise invalid' are common indicators.
Fix: Re-run the `login()` function or the `aws sso login` CLI command to refresh your SSO session. Consider handling token expiration in your application logic to prompt for re-authentication.
gotcha When using `aws-sso-util credential-process` (which leverages `aws-sso-lib`) with AWS SDKs that don't have native IAM Identity Center support, you might need to explicitly set the environment variable `AWS_SDK_LOAD_CONFIG=1` for the SDK to correctly discover and use the `credential_process` configured in your `~/.aws/config` file.
Fix: Set `export AWS_SDK_LOAD_CONFIG=1` in your shell environment before running applications that rely on `credential_process` for SSO authentication.

Install

pip install aws-sso-lib Install latest version

Imports

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.

Quickstart

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']}")

view raw JSON →