Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 70 ยท Getting started with AWS

Console, CLI and SDKs

Learn the three ways to use AWS: the console, the aws CLI and SDKs such as boto3. Configure profiles and SSO, understand credentials, and see how every call is a signed HTTPS request.

Everything you can do in AWS is an API call. The web console, the command line tool and the language SDKs are three different front ends to the same set of HTTPS APIs. Once you see that, the tools stop feeling like three separate things to learn: they share the same names for actions, the same permissions and the same credentials.

This lesson shows when to use each tool, how credentials and profiles are configured, how a small boto3 program looks, and what actually travels over the wire. The commands and SDK code below are real and read-only on this site, since there is no AWS account behind the page. The runnable examples are stand-ins: a toy request signer that follows the same idea as AWS Signature Version 4, and a client that logs every call it would send.

Three front ends, one API

flowchart LR
    C["Console<br/>point and click"] --> API["AWS service API<br/>HTTPS endpoint per Region"]
    L["AWS CLI<br/>aws s3 ls"] --> API
    S["SDK<br/>boto3, Java, JS, Go"] --> API
    API --> R["Resources in your account"]

Console, CLI and SDKs all end in the same signed HTTPS requests.

  • The console is best for exploring, learning a new service, and looking at graphs. It is not repeatable: nobody can review a series of clicks, and nobody can run it twice with the same result.
  • The AWS CLI is best for quick one-off tasks, scripts and automation in a shell. A command is text, so you can put it in a README, a pipeline or a runbook.
  • SDKs exist for most languages (Python's is called boto3, JavaScript, Java, Go, .NET, PHP, Ruby, Rust and more). They are for application code that creates or uses AWS resources while it runs.
  • Infrastructure as code tools such as CloudFormation sit above these and are covered later, starting with CloudFormation.

The practical rule: explore in the console, repeat in the CLI, and put anything that runs more than a couple of times into code or templates. AWS CloudShell, a browser shell inside the console, comes with the CLI already installed and uses the credentials you signed in with, which makes it handy for first experiments.

Credentials: who is calling?

Every request carries an identity. The identity might be an IAM user's access key (an access key ID plus a secret access key), or temporary credentials that also contain a session token. Long-lived access keys are a last resort; the better options are single sign-on and roles, which the IAM lessons explain.

The CLI and SDKs look for credentials in a fixed order, called the credential provider chain. The details differ slightly by tool, but the usual order is:

  1. Explicit values passed in code or on the command line.
  2. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN).
  3. A named profile that uses role assumption, web identity or SSO.
  4. The shared credentials and config files in ~/.aws/.
  5. Container or instance credentials, which is how code running on ECS or EC2 gets a role without any stored keys.

That last item is why code running on AWS should never contain keys at all.

Installing the AWS CLI

Install AWS CLI version 2, which is a self-contained program that works the same way on every platform. Read-only commands, since installers change your machine:

Terminal
# Linux (x86_64 or aarch64): download the official zip, unpack, install
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip && sudo ./aws/install

# macOS: the official .pkg installer, or Homebrew
brew install awscli

# Windows: the official MSI installer, or the package manager
msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi
winget install Amazon.AWSCLI

# Verify the installation on any platform
aws --version

Distribution packages such as apt install awscli may install an old version 1 or an outdated build, so prefer the official installer or your platform's maintained package. The CLI behaves the same on every operating system, which means a command you test on your laptop works unchanged in a Linux CI job.

aws configure and profiles

The quickest way to set up the CLI with an access key is:

Terminal
aws configure
# AWS Access Key ID [None]: <your key id>
# AWS Secret Access Key [None]: <your secret>
# Default region name [None]: eu-west-1
# Default output format [None]: json

This writes two small text files. Keep the secret out of version control.

INI
# ~/.aws/credentials
[default]
aws_access_key_id = <key id>
aws_secret_access_key = <secret>

# ~/.aws/config
[default]
region = eu-west-1
output = json

[profile staging]
region = us-east-1

A profile is a named group of settings. Use one with a flag or with an environment variable:

Terminal
aws s3 ls --profile staging
export AWS_PROFILE=staging
aws sts get-caller-identity

aws sts get-caller-identity is the most useful first command of any session: it prints the account number and the ARN of the identity the CLI is using, so you know which account and which role you are about to change.

SSO login

For a person at a keyboard, the better way is IAM Identity Center (formerly AWS SSO). You log in through your company's identity provider in a browser, and the CLI receives short-lived credentials that expire on their own:

Terminal
aws configure sso          # asks for the start URL, Region, account and role
aws sso login --profile staging
aws s3 ls --profile staging

When the session expires you simply run aws sso login again. Nothing long-lived sits on your disk.

A first boto3 program

boto3 finds credentials with the same chain, so the code contains no keys:

Python
import boto3
from botocore.exceptions import ClientError

s3 = boto3.client("s3", region_name="eu-west-1")

try:
    response = s3.list_buckets()
    for bucket in response["Buckets"]:
        print(bucket["Name"])
except ClientError as error:
    code = error.response["Error"]["Code"]
    print("AWS refused the call:", code)

boto3.client("s3") is a thin wrapper that maps Python methods to API actions: list_buckets is the S3 ListBuckets action, and the dictionary you get back is the parsed response. A call that AWS rejects raises ClientError, whose response["Error"]["Code"] has the machine-readable reason, for example AccessDenied or NoSuchBucket. Many list calls return results in pages, so for large results use a paginator (s3.get_paginator("list_objects_v2")) instead of reading only the first page.

Every call is a signed request

When you run aws ec2 describe-instances, the CLI builds an HTTPS request to the EC2 endpoint of your Region, signs it with your secret key using Signature Version 4, and sends it. The service recomputes the signature from its own copy of your secret. If the two match, the request is authentic and was not changed on the way. The secret itself is never sent.

The signature is computed in a few steps:

  1. Build a canonical request: method, path, query string, selected headers and a hash of the body.
  2. Build a string to sign from the algorithm name, the timestamp, a credential scope (date, Region, service and the word aws4_request) and the hash of the canonical request.
  3. Derive a signing key by chaining HMAC-SHA256 over the secret, the date, the Region, the service name and the fixed text aws4_request.
  4. Compute HMAC-SHA256 of the string to sign with that signing key. The hex result is the signature, which goes into the Authorization header.

Because the key is derived for one date, Region and service, a leaked signing key is useful only for a narrow slice. The stand-in below follows these same steps with a made-up secret. It is a simplified teaching version (a real request signs more headers and canonicalization has more rules), so never use it against AWS, but it shows the properties that matter.

Python A toy request signer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You will see True for the repeated request and False for every change. That is the whole security idea: a modified request, a stale timestamp or a wrong secret produces a different signature, and the service rejects it. This also explains why aws commands fail when your computer's clock is far off: the timestamp is part of what is signed, and AWS only accepts requests whose time is close to its own.

Seeing the calls: a logging client

One more habit helps when you learn: look at the API calls behind a tool. The CLI's --debug flag prints the request details, and AWS CloudTrail records every call made in your account (covered in CloudTrail, Config and X-Ray). The stand-in below imitates a small client that logs each call with the profile, Region and action used, and returns canned data. Real clients return real data from AWS; the log format here is invented.

Python A client that logs every call

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the same Python code, pointed at two profiles, talks to two accounts and two Regions. That is exactly why checking the caller identity before any change is a good habit.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do the console, the CLI and the SDKs have in common?

    All three are front ends to the same HTTPS APIs, so the same IAM permissions and action names apply to each.
  2. 2. Which command prints the account and identity the CLI is currently using?

    aws sts get-caller-identity returns the account ID, user ID and ARN of the caller, and it needs no special permissions.
  3. 3. In Signature Version 4, what is sent over the network?

    The request carries the access key ID and a signature computed from the secret. The service recomputes it using its own copy of the secret, so the secret never travels.
  4. 4. Code on an EC2 instance needs to read an S3 bucket. What is the recommended way to give it credentials?

    The SDK credential chain picks up role credentials automatically on EC2, ECS and Lambda, so no keys are stored.

Summary

  • The console, the CLI and SDKs such as boto3 are three front ends to the same HTTPS APIs.
  • Explore in the console, repeat in the CLI, automate in code or infrastructure as code.
  • The CLI and SDKs follow a credential provider chain; prefer SSO and roles over stored access keys.
  • aws configure writes profiles to ~/.aws/; aws sts get-caller-identity tells you who you are.
  • Requests are signed with Signature Version 4: the secret never leaves your machine and any change to the request breaks the signature.

Next: The Shared Responsibility Model.