{"id":8866,"library":"aws-sso-lib","title":"AWS SSO Library","description":"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.","status":"active","version":"1.14.0","language":"en","source_language":"en","source_url":"https://github.com/benkehoe/aws-sso-util","tags":["AWS","SSO","IAM Identity Center","Authentication","Boto3","Credentials"],"install":[{"cmd":"pip install aws-sso-lib","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for interacting with AWS services and fetching credentials.","package":"boto3","optional":false},{"reason":"Underlying AWS SDK for Python, a core dependency of boto3 and aws-sso-lib.","package":"botocore","optional":false}],"imports":[{"note":"Main function to get a configured boto3 session for an SSO account and role.","symbol":"get_boto3_session","correct":"from aws_sso_lib import get_boto3_session"},{"note":"Function to initiate an interactive SSO login process.","symbol":"login","correct":"from aws_sso_lib import login"},{"note":"Utility to list accounts accessible via the current SSO session.","symbol":"list_available_accounts","correct":"from aws_sso_lib import list_available_accounts"},{"note":"Utility to list roles available within a given account via the current SSO session.","symbol":"list_available_roles","correct":"from aws_sso_lib import list_available_roles"}],"quickstart":{"code":"import os\nfrom aws_sso_lib import login, get_boto3_session\n\n# Ensure these environment variables are set or replace with actual values\nSSO_START_URL = os.environ.get('AWS_SSO_START_URL', 'https://d-xxxxxxxxxx.awsapps.com/start')\nSSO_REGION = os.environ.get('AWS_SSO_REGION', 'us-east-1') # The region where your SSO instance is configured\n\n# You might need to know the account ID and role name for your target AWS account\nTARGET_ACCOUNT_ID = os.environ.get('AWS_ACCOUNT_ID', '123456789012')\nTARGET_ROLE_NAME = os.environ.get('AWS_ROLE_NAME', 'AWSAdministratorAccess')\nAWS_SESSION_REGION = os.environ.get('AWS_REGION', 'us-east-1') # The region for the Boto3 session\n\nprint(\"Attempting SSO login...\")\n# The 'login' function opens a browser for authentication if credentials are expired\n# or not found. It returns a token dict which is cached.\ntoken = login(SSO_START_URL, SSO_REGION, force_refresh=False)\nprint(\"SSO login successful (or token was already valid).\")\n\nprint(f\"Getting boto3 session for account {TARGET_ACCOUNT_ID} with role {TARGET_ROLE_NAME} in region {AWS_SESSION_REGION}...\")\n# Get a boto3 session using the SSO credentials\nsession = get_boto3_session(\n    SSO_START_URL,\n    SSO_REGION,\n    TARGET_ACCOUNT_ID,\n    TARGET_ROLE_NAME,\n    region=AWS_SESSION_REGION,\n    login=True # Automatically logs in if session is expired\n)\n\n# Use the session to interact with AWS services\nsts_client = session.client('sts')\ncaller_identity = sts_client.get_caller_identity()\nprint(f\"Successfully obtained credentials for: {caller_identity['Arn']}\")\n\n# Example: List S3 buckets\ns3_client = session.client('s3')\nbuckets = s3_client.list_buckets()\nprint(\"S3 Buckets:\")\nfor bucket in buckets['Buckets']:\n    print(f\"- {bucket['Name']}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.7 or higher.","message":"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.","severity":"breaking","affected_versions":">=1.12.0"},{"fix":"Upgrade `aws-sso-lib` to the latest version to ensure compatibility with recent `botocore` changes.","message":"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.","severity":"breaking","affected_versions":"<1.12.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Set `export AWS_SDK_LOAD_CONFIG=1` in your shell environment before running applications that rely on `credential_process` for SSO authentication.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The cached SSO token is either corrupted, missing the 'expiresAt' field, or otherwise invalid.","error":"Login failed: 'expiresAt'"},{"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.","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.","error":"NoCredentialProviders: no valid providers in chain."},{"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.","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.","error":"cannot import name 'SSOTokenFetcher' from 'botocore.utils'"},{"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.","cause":"The cached SSO token file is inaccessible due to incorrect file permissions, or the file itself is corrupted.","error":"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"}]}