Registry / type-stubs / aws-sso-lib

aws-sso-lib

JSON →
library1.14.0pypypi✓ verified 84d ago

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.

pip install aws-sso-lib
INSTALL
IMPORT
SIG · AWS-SSO-LIB
A
aws-sso-lib
type-stubspythonv1.14.0
Install
3.9s avg
Import
729ms
Disk
50MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.763s · 51.1MB
glibc
py 3.103.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
Debug
Known issues
breakingSupport 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.
affects: >=1.12.0
breakingChanges 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.
affects: <1.12.0
gotchaAWS 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.
affects: All
gotchaWhen 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.
affects: All
Errors
Common errors & fixes
Login failed: 'expiresAt'
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.
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'
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
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.
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.
Agent activity
42 hits · last 30 days
node
36
OpenAI (training)
1
Resources
aws-sso-lib — pip install aws-sso-lib · libregistry