Hands-on lab — Day 25: API Authentication: Keys, Tokens, and OAuth

#!/usr/bin/env bash
# Day 025 lab — completed reference implementation.
# Authenticate to a public test API (httpbin.org) with each common scheme:
#   1. Basic auth, correct credentials      -> 200
#   2. Basic auth, wrong credentials        -> 401
#   3. Bearer token in the Authorization header
#   4. An API key in a custom header, echoed back
#   5. A bearer token read from an environment variable (the safe pattern)
#
# httpbin's auth endpoints accept ANY credentials, so no real key is needed.
# Every credential in this script is an obviously fake placeholder.
# If the network is unavailable, the script says so and exits 0 (nothing to prove offline).
set -uo pipefail

API="https://httpbin.org"
# curl options: fail quietly on server errors, cap the wait, ride past transient 5xx.
CURL=(curl -s --max-time 25 --retry 5 --retry-delay 2)

echo "=== API Authentication Demo ==="
echo "Target: ${API} (public test server; accepts any credentials)"
echo

# Bail out gracefully when offline so the demo never hangs or errors.
if ! curl -s -o /dev/null --max-time 12 "${API}/status/200" 2>/dev/null; then
  echo "No network access — skipping the live requests."
  echo "Online, this script sends Basic auth, a bearer token, and a key header to ${API}."
  echo "=== End of demo ==="
  exit 0
fi

echo "--- 1. Basic auth with CORRECT credentials (expect 200) ---"
echo "\$ curl -u user:pass ${API}/basic-auth/user/pass"
code="$("${CURL[@]}" -o /dev/null -w '%{http_code}' -u user:pass "${API}/basic-auth/user/pass")"
echo "HTTP status: ${code}"
echo

echo "--- 2. Basic auth with WRONG credentials (expect 401) ---"
echo "\$ curl -u user:wrongpass ${API}/basic-auth/user/pass"
code="$("${CURL[@]}" -o /dev/null -w '%{http_code}' -u user:wrongpass "${API}/basic-auth/user/pass")"
echo "HTTP status: ${code}"
echo

echo "--- 3. Bearer token in the Authorization header ---"
echo "\$ curl -H 'Authorization: Bearer token-example-123' ${API}/bearer"
"${CURL[@]}" -H "Authorization: Bearer token-example-123" "${API}/bearer"
echo

echo "--- 4. API key in a custom header, echoed back by the server ---"
echo "\$ curl -H 'X-API-Key: demo-key' ${API}/headers"
"${CURL[@]}" -H "X-API-Key: demo-key" "${API}/headers"
echo

echo "--- 5. Bearer token READ FROM AN ENVIRONMENT VARIABLE (the safe pattern) ---"
# The secret lives in a variable, not inline in the command. Here it is a fake value;
# for a real API you would 'export' the key from a gitignored .env, never hard-code it.
export DEMO_TOKEN="token-from-env-example"
echo "\$ export DEMO_TOKEN=...   (kept out of code and git)"
echo "\$ curl -H \"Authorization: Bearer \$DEMO_TOKEN\" ${API}/bearer"
"${CURL[@]}" -H "Authorization: Bearer ${DEMO_TOKEN}" "${API}/bearer"
echo

echo "=== End of demo ==="

lesson_id: D025
day: 25
kind: api-example
languages: [bash]
setup_commands:
  - cd labs/sections/computing-foundations/day-025-api-authentication-keys-tokens-and-oauth
run_commands:
  - bash examples/auth_demo.sh
  - bash starter/auth_demo.sh
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/auth_demo.sh  # optional: reset your work'
requires_network: true
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS (curl 8.7.1), online, bash tests/run_tests.sh → 16 checks, 0 failure(s), 0 skip(s); example run gave Basic 200 / Basic 401 / bearer authenticated:true. When httpbin returns a transient 503 the network checks SKIP and the script still exits 0.'

# Dependencies — Day 025 lab

**Only `curl`.** This lab has no installable dependencies beyond a POSIX
shell and the `curl` command:

- `bash` ≥ 3.2 (preinstalled on macOS and every mainstream Linux distribution)
- `curl` (preinstalled on macOS and most Linux; on Debian/Ubuntu install with
  `sudo apt install curl`, on Fedora with `sudo dnf install curl`)

Check that curl is present:

```bash
curl --version
```

There is deliberately no `requirements.txt` or `package.json` here. The lab
talks to a public test server (`httpbin.org`) whose authentication endpoints
accept **any** credentials, so **no API key and no account are required**.
The lab needs network access to reach that server; with no network, the
scripts and tests degrade gracefully (they announce the skip and exit 0).

#!/usr/bin/env bash
# Day 025 lab — YOUR working file.
# Complete the 4 numbered exercises below. Each names the exact curl command
# to run. httpbin.org accepts ANY credentials, so no real key is needed —
# every value here is an obviously fake placeholder.
#
# Run it with:   bash starter/auth_demo.sh
# When you are done, none of the "NOT DONE YET" placeholder lines should remain.
set -uo pipefail

API="https://httpbin.org"
CURL=(curl -s --max-time 25 --retry 5 --retry-delay 2)

echo "=== API Authentication Demo (starter) ==="

# Skip the live requests when offline so the script never hangs.
if ! curl -s -o /dev/null --max-time 12 "${API}/status/200" 2>/dev/null; then
  echo "No network access — connect to the internet and re-run to complete the exercises."
  exit 0
fi

# ---------------------------------------------------------------------------
# Exercise 1: Basic auth with CORRECT credentials — expect HTTP 200.
#   Replace the placeholder echo below with a command that prints just the code:
#     "${CURL[@]}" -o /dev/null -w '%{http_code}\n' -u user:pass \
#       "${API}/basic-auth/user/pass"
echo "--- Exercise 1: Basic auth, correct credentials (expect 200) ---"
echo "NOT DONE YET — run the curl -u user:pass command described above"

# ---------------------------------------------------------------------------
# Exercise 2: Basic auth with WRONG credentials — expect HTTP 401.
#   Replace the placeholder echo below with the same command but a wrong password:
#     "${CURL[@]}" -o /dev/null -w '%{http_code}\n' -u user:wrongpass \
#       "${API}/basic-auth/user/pass"
echo "--- Exercise 2: Basic auth, wrong credentials (expect 401) ---"
echo "NOT DONE YET — run the curl -u user:wrongpass command described above"

# ---------------------------------------------------------------------------
# Exercise 3: Send a BEARER TOKEN in the Authorization header.
#   Replace the placeholder echo below with:
#     "${CURL[@]}" -H "Authorization: Bearer token-example-123" "${API}/bearer"
#   The endpoint should return JSON with "authenticated": true and your token.
echo "--- Exercise 3: Bearer token in the Authorization header ---"
echo "NOT DONE YET — run the curl -H 'Authorization: Bearer ...' command described above"

# ---------------------------------------------------------------------------
# Exercise 4: Read a bearer token from an ENVIRONMENT VARIABLE (the safe pattern).
#   Set a fake token in a variable, then reference the variable so the secret
#   never appears inline. Replace the placeholder echo below with these two lines:
#     export DEMO_TOKEN="token-example-123"
#     "${CURL[@]}" -H "Authorization: Bearer ${DEMO_TOKEN}" "${API}/bearer"
echo "--- Exercise 4: Bearer token from an environment variable ---"
echo "NOT DONE YET — export DEMO_TOKEN and run curl with \$DEMO_TOKEN as described above"

echo "=== End of demo ==="

# Authentication worksheet — Day 025

Fill this in from a real run of the commands (via `bash examples/auth_demo.sh`
or by running each `curl` yourself). Every credential here is fake and
httpbin.org accepts any of them, so you need no account and no real key.

## 1. Basic auth status codes

Run both and record the exact HTTP status code:

```bash
curl -s -o /dev/null -w '%{http_code}\n' -u user:pass       https://httpbin.org/basic-auth/user/pass
curl -s -o /dev/null -w '%{http_code}\n' -u user:wrongpass  https://httpbin.org/basic-auth/user/pass
```

- Status code for CORRECT credentials (`user:pass`): __________
- Status code for WRONG credentials (`user:wrongpass`): __________
- What does each code mean, in one sentence?
  - 200: ______________________________________________________
  - 401: ______________________________________________________

## 2. Bearer token

```bash
curl -s -H "Authorization: Bearer token-example-123" https://httpbin.org/bearer
```

- Did the endpoint accept your token (did the JSON say `"authenticated": true`)?  __________
- What token did it echo back? __________
- Which HTTP header carried the token, and in what exact format? __________

## 3. Key in a header

```bash
curl -s -H "X-API-Key: demo-key" https://httpbin.org/headers
```

- Did your `X-API-Key` header appear in the server's echo of the headers it saw?  __________
- Why is sending a key in a header safer than sending it in the URL query string?
  Name two places a query-string key can leak:
  1. ______________________________________________________
  2. ______________________________________________________

## 4. Storing a real key safely (the important part)

Imagine you will call a paid API tomorrow. Write 4–6 sentences answering:

- What environment variable name would you read the key from?
- Where would the `.env` file live, and why must it be in `.gitignore`?
- Why should you never hard-code the key in your source?
- What would you do the *instant* you discovered the key had been committed to a
  public repository — and why is deleting the commit not enough?

Your answer:

_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________

#!/usr/bin/env bash
# Tests for the Day 025 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Two kinds of checks:
#   * Structure checks always run and must pass (files present, the example
#     script exercises each scheme, the starter names its exercises, both
#     scripts parse, and no realistic long key-shaped string is present).
#   * Network checks run only when the internet is reachable. Offline, they
#     are SKIPPED with a message. When online but the public test server
#     (httpbin.org) is transiently returning 5xx, the affected check is also
#     SKIPPED rather than failed — an external outage is not the learner's bug.
#
# The script exits 0 when no structure check failed, whether online or offline.
set -u

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
API="https://httpbin.org"
failures=0
checks=0
skips=0

pass() { checks=$((checks + 1)); echo "  ok:   $1"; }
fail() { checks=$((checks + 1)); failures=$((failures + 1)); echo "  FAIL: $1"; }
skip() { skips=$((skips + 1)); echo "  skip: $1"; }

echo "== Structure checks =="
example="${lab_dir}/examples/auth_demo.sh"
starter="${lab_dir}/starter/auth_demo.sh"

[ -f "${example}" ] && pass "example script exists" || fail "example script missing"
[ -f "${starter}" ] && pass "starter script exists" || fail "starter script missing"
[ -f "${lab_dir}/starter/auth-worksheet.md" ] && pass "worksheet exists" || fail "worksheet missing"

# The example must exercise each scheme.
for needle in "user:pass" "user:wrongpass" "Authorization: Bearer" "X-API-Key" "DEMO_TOKEN"; do
  if grep -q -- "${needle}" "${example}"; then pass "example uses '${needle}'"; else fail "example missing '${needle}'"; fi
done

# The starter must name its four numbered exercises.
ex_count="$(grep -cE 'Exercise [1-4]:' "${starter}" 2>/dev/null || true)"
if [ "${ex_count:-0}" -ge 4 ]; then pass "starter has 4 numbered exercises"; else fail "starter has 4 numbered exercises (found ${ex_count:-0})"; fi

# Both scripts must be valid bash.
if bash -n "${example}" 2>/dev/null; then pass "example has valid bash syntax"; else fail "example has a syntax error"; fi
if bash -n "${starter}" 2>/dev/null; then pass "starter has valid bash syntax"; else fail "starter has a syntax error"; fi

# Safety: no realistic long key-shaped string should appear anywhere in the lab.
# (Fake placeholders like token-example-123 are short and hyphenated; a real
# key is a long unbroken run of letters/digits. Flag any 32+ char run.)
if grep -rInE '[A-Za-z0-9]{32,}' "${lab_dir}" >/dev/null 2>&1; then
  fail "a long key-shaped string is present — use only short fake placeholders"
else
  pass "no realistic long key-shaped strings present"
fi

echo
echo "== Network checks =="
if ! curl -s -o /dev/null --max-time 12 "${API}/status/200" 2>/dev/null; then
  skip "no network access — skipping all live-request checks (expected offline)"
else
  pass "network reachable (${API} responded)"

  # Check 1: correct Basic auth returns 200.
  ok="$(curl -o /dev/null -s --max-time 25 --retry 5 --retry-delay 2 \
    -w '%{http_code}' -u user:pass "${API}/basic-auth/user/pass" 2>/dev/null)" || ok="000"
  case "${ok}" in
    200) pass "correct Basic auth returned HTTP 200" ;;
    5* | 000) skip "Basic-auth-correct check — httpbin transiently unavailable (got '${ok}'); retry later" ;;
    *) fail "correct Basic auth should return 200 (got '${ok}')" ;;
  esac

  # Check 2: wrong Basic auth returns 401. A 401 is not a transient error, so
  # --retry returns it without retrying; a 5xx means the server is overloaded.
  bad="$(curl -o /dev/null -s --max-time 25 --retry 5 --retry-delay 2 \
    -w '%{http_code}' -u user:wrongpass "${API}/basic-auth/user/pass" 2>/dev/null)" || bad="000"
  case "${bad}" in
    401) pass "wrong Basic auth returned HTTP 401" ;;
    5* | 000) skip "Basic-auth-wrong check — httpbin transiently unavailable (got '${bad}'); retry later" ;;
    *) fail "wrong Basic auth should return 401 (got '${bad}')" ;;
  esac

  # Check 3: the bearer endpoint accepts a token and returns 200.
  br="$(curl -o /dev/null -s --max-time 25 --retry 5 --retry-delay 2 \
    -w '%{http_code}' -H "Authorization: Bearer token-example-123" "${API}/bearer" 2>/dev/null)" || br="000"
  case "${br}" in
    200) pass "bearer endpoint accepted the token (HTTP 200)" ;;
    5* | 000) skip "bearer check — httpbin transiently unavailable (got '${br}'); retry later" ;;
    *) fail "bearer endpoint should return 200 (got '${br}')" ;;
  esac
fi

echo
echo "${checks} checks, ${failures} failure(s), ${skips} skip(s)."
[ "${failures}" -eq 0 ]