aws-sso-util

4.33.0 · active · verified Fri Apr 17

aws-sso-util is a Python library and CLI tool that simplifies managing AWS Single Sign-On (SSO) credentials and profiles, abstracting away much of the complexity of the AWS CLI's SSO integration. It provides utilities for logging in, fetching temporary credentials, and configuring profiles. The library is actively maintained with frequent, independent releases for its CLI and programmatic components, with the current version being 4.33.0.

Common errors

```
ModuleNotFoundError: No module named 'aws_sso_util'
```
cause The `aws-sso-util` library has not been installed or is not in your Python environment's path.

fix Run `pip install aws-sso-util` to install the library.
```
Error: No SSO start_url configured for profile 'my-profile'
```
cause Your AWS configuration file (~/.aws/config) is missing the `sso_start_url` for the specified profile, or the profile name is incorrect.

fix Run `aws-sso-util configure populate` to interactively set up your SSO configuration, or manually add `sso_start_url` and `sso_region` to your profile in `~/.aws/config`.
```
The SSO session token has expired or is invalid.
```
cause Your cached SSO token, which grants access to AWS SSO, has expired. This typically happens after 8-12 hours.

fix Run `aws-sso-util login --force-refresh` to re-authenticate and acquire a new SSO session token.
```
Failed to get credentials: 'expiration' is missing from token cache.
```
cause The cached SSO token file is malformed or an older version of `aws-sso-util` created a token without a required `expiration` field.

fix Run `aws-sso-util login --force-refresh` to force the generation of a new, properly structured token. If the issue persists, consider manually clearing the SSO token cache (e.g., `rm -f ~/.aws/sso/cache/*.json`).
```
aws-sso-credential-process failed with error: An error occurred (ExpiredTokenException) when calling the GetRoleCredentials operation: The token has expired.
```
cause When using `aws-sso-util` as a credential process for `botocore`/`boto3`, the underlying SSO session token used by `aws-sso-util` has expired, causing credential fetching to fail.

fix Run `aws-sso-util login --force-refresh` to renew your AWS SSO session token. The credential process will then be able to fetch valid temporary credentials.

Warnings

breaking Python 3.6 is no longer supported. Upgrading to Python 3.7+ is required.
Fix: Upgrade your Python environment to 3.7 or newer. This aligns with `boto3`'s Python support.
breaking Changes in `botocore` required updates to `get_credentials()` and `aws-sso-credential-process`.
Fix: Ensure you are on the latest `aws-sso-util` version (4.29+ or lib 1.12+) to maintain compatibility with recent `botocore` releases.
breaking The `jsonschema` dependency was updated to a major version (v4). This might cause compatibility issues if other installed packages rely on an older `jsonschema` version.
Fix: Upgrade `aws-sso-util` to 4.33 or newer. If conflicts arise, consider using a virtual environment or upgrading conflicting packages.
breaking The `PyYAML` dependency was updated to v6.0.1. This addresses a Cython issue but could potentially introduce compatibility issues with older `PyYAML` consumers.
Fix: Upgrade `aws-sso-util` to 4.32 or newer. If issues persist, ensure `PyYAML` itself is up-to-date and compatible with other project dependencies.
breaking The `click` dependency was upgraded to version 8. This may impact custom CLI extensions or scripts that rely on specific `click` v7 behaviors.
Fix: Upgrade `aws-sso-util` to 4.31 or newer. Review your CLI scripts for any `click` specific syntax that might have changed.
deprecated The `--force` option for `aws-sso-util login` and other commands has been deprecated in favor of `--force-refresh` for consistency.
Fix: Update your scripts and usage patterns to use `--force-refresh` instead of `--force`.
gotcha Cached SSO tokens have a limited lifespan (usually 8-12 hours). Operations will fail once the token expires.
Fix: Run `aws-sso-util login --force-refresh` to re-authenticate and refresh your SSO session token when you encounter token expiration errors.

Install

pip install aws-sso-util Install latest version

Imports

get_credentials
```
from aws_sso_util import get_credentials
```
Main function for programmatically fetching AWS SSO credentials.
SSOTokenFetcher
```
from aws_sso_util import SSOTokenFetcher
```
Used for lower-level SSO token management and refreshing.

Quickstart

This quickstart demonstrates how to programmatically fetch temporary AWS credentials using `get_credentials`. It's crucial to have your AWS SSO profile configured (e.g., via `aws-sso-util configure populate`) and an active SSO session (via `aws-sso-util login`) before running this code.

import os
from aws_sso_util import get_credentials

# Configure your AWS SSO profile name, e.g., 'my-sso-profile'
# Ensure your AWS config file (~/.aws/config) has the sso_start_url, sso_region, and sso_account_id configured
profile_name = os.environ.get('AWS_SSO_PROFILE', 'default')

try:
    credentials = get_credentials(profile=profile_name)
    print(f"Successfully fetched temporary credentials for profile '{profile_name}':")
    print(f"  Access Key ID: {credentials['AccessKeyId']}")
    print(f"  Secret Access Key: {credentials['SecretAccessKey']}")
    print(f"  Session Token: {credentials['SessionToken'][:8]}...")
    print(f"  Expiration: {credentials['Expiration']}")
except Exception as e:
    print(f"Error fetching credentials: {e}")
    print("Please ensure you've run 'aws-sso-util login' and configured your profile.")

view raw JSON →