How to use the command 'aws sso' (with examples)

AWS Single Sign-On (SSO) provides centralized access management to AWS resources. By using AWS SSO, organizations can integrate with identity providers to ensure each user’s access to AWS accounts is managed seamlessly and securely. The aws sso command-line interface (CLI) commands help start and stop sessions, manage roles and accounts, and generate short-term credentials. This article provides detailed insights into how to use these commands effectively with practical examples, explaining the motivation behind each use case and the parameters involved.

Use case 1: Start SSO session and refresh access tokens

Code:

aws sso login

Motivation:

Initiating an SSO session is crucial for obtaining the necessary credentials to access AWS resources. This command is typically the first step when you want to work with AWS services using command-line tools or scripts. Once logged in, users acquire valid and updated tokens required to authorize further AWS CLI operations.

Explanation:

• aws sso: Invokes the AWS SSO service through the AWS CLI.
• login: Triggers the login process. This action utilizes pre-configured SSO settings, which direct the CLI to initiate the authentication flow with the identity provider linked with AWS SSO. Before running this, users must configure SSO settings via aws configure sso.

Example output:

SSO session successfully started. You can access your assigned roles and accounts.

Use case 2: End SSO session and clear cached access tokens

Code:

aws sso logout

Motivation:

Logging out and clearing cached tokens are essential for security, especially when working on shared or public systems. This ensures that temporary credentials aren’t inadvertently used by others, thereby maintaining safeguard over sensitive AWS resources.

Explanation:

• aws sso: Again, this signifies the use of the AWS SSO component within AWS CLI.
• logout: This command deactivates the current SSO session and erases tokens that were cached during the session’s duration, ensuring previous SSO credentials aren’t misused.

Example output:

SSO session ended, and cached credentials cleared.

Use case 3: List all AWS accounts accessible to the user

Code:

aws sso list-accounts

Motivation:

A user may have access to multiple AWS accounts through SSO, and listing these accounts helps identify the AWS environments they have permission to interact with. This is especially beneficial to users who need clarity on their allocated resources across different AWS accounts and projects.

Explanation:

• aws sso: Confirms that this is within the context of AWS SSO operations.
• list-accounts: Requests a comprehensive enumeration of all AWS accounts the user can access, simplifying navigation and management tasks for the user.

Example output:

{
  "accountList": [
    {
      "accountId": "123456789012",
      "accountName": "Development Account",
      "emailAddress": "dev@example.com"
    },
    {
      "accountId": "987654321098",
      "accountName": "Production Account",
      "emailAddress": "prod@example.com"
    }
  ]
}

Use case 4: List all roles accessible to the user for a given AWS account

Code:

aws sso list-account-roles --account-id 123456789012 --access-token A1B2C3D4E5F6G7H8I9J0

Motivation:

Users often have different roles assigned within a single AWS account. Listing these roles is vital for understanding what actions a user can perform within that account, thus facilitating informed decision-making regarding permissions and role-based access within the AWS environment.

Explanation:

• aws sso: Reiterates the use of AWS SSO functionality.
• list-account-roles: The command option used to enumerate all roles tied to a specific AWS account to which the user has access.
• --account-id: Specifies the exact AWS account ID whose roles you’re interested in listing.
• --access-token: The token required to authenticate and authorize this request, obtained during a previous aws sso login.

Example output:

{
  "roleList": [
    {
      "roleName": "Administrator",
      "accountId": "123456789012"
    },
    {
      "roleName": "ReadOnlyUser",
      "accountId": "123456789012"
    }
  ]
}

Use case 5: Retrieve short-term credentials for a specific account

Code:

aws sso get-role-credentials --account-id 123456789012 --role-name Administrator --access-token A1B2C3D4E5F6G7H8I9J0

Motivation:

Short-term credentials are essential for securely accessing AWS resources using roles assigned through SSO. This is particularly useful for programmatic access, where these temporary credentials are used to perform AWS operations without requiring persistent credentials, thus enhancing security by minimizing exposure risk.

Explanation:

• aws sso: Utilizes AWS SSO for the operation.
• get-role-credentials: Command to acquire temporary credentials for a specified role in a given AWS account.
• --account-id: Identifies the account where the role resides.
• --role-name: Specifies the name of the role for which short-term credentials are being requested.
• --access-token: The access token, ensuring the requestor has the right to perform this operation, obtained from a prior aws sso login.

Example output:

{
  "roleCredentials": {
    "accessKeyId": "ASIAEXAMPLE123456",
    "secretAccessKey": "wJalrXUtnFEXAMPLEKEY",
    "sessionToken": "FQoGZXIvYXdzEFsaDP...",
    "expiration": 1615554199
  }
}

Conclusion:

AWS SSO CLI commands offer an efficient way to manage access to AWS resources through a centralized authentication process. By using aws sso commands, users can manage starting and stopping sessions, listing accessible AWS accounts and roles, and obtaining short-term credentials, all of which contribute to optimizing and securing user interactions with AWS environments. Each command serves a vital role in ensuring streamlined and secure access management, which is essential in cloud-based operations.