Token Exchange (RFC 8693)

# Check whether token-exchange is active on the running server.
docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh get \
  serverinfo -r master | jq '.features[] | select(.name | test("token.exchange"))'

# If it is not enabled, add the feature to both nodes' start command and
# rebuild, using the same rolling restart pattern as Lab 08. For a Docker
# Compose start, this means adding to the command:
#   start --features=token-exchange,admin-fine-grained-authz
# then, per node:
#   docker exec -it ib-keycloak-1 /opt/keycloak/bin/kc.sh build
#   docker restart ib-keycloak-1
#   (wait for health) then repeat for ib-keycloak-2

for svc in payroll-api document-api; do
  docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh create clients \
    -r northgate \
    -s clientId=$svc \
    -s enabled=true \
    -s protocol=openid-connect \
    -s bearerOnly=true
done

# Create the two optional client scopes.
docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh create client-scopes \
  -r northgate -s name=payroll:read -s protocol=openid-connect \
  -s 'attributes."include.in.token.scope"=true'

docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh create client-scopes \
  -r northgate -s name=document:render -s protocol=openid-connect \
  -s 'attributes."include.in.token.scope"=true'

# The audience mapper ensures a token carrying payroll:read is addressed to
# payroll-api, and likewise for document:render. Substitute the scope id
# returned when you list client-scopes.
SCOPE_ID=$(docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh get \
  client-scopes -r northgate --fields id,name | jq -r '.[] | select(.name=="payroll:read") | .id')

docker exec -it ib-keycloak-1 /opt/keycloak/bin/kcadm.sh create \
  client-scopes/$SCOPE_ID/protocol-mappers/models -r northgate \
  -s name=payroll-aud \
  -s protocol=openid-connect \
  -s protocolMapper=oidc-audience-mapper \
  -s 'config."included.client.audience"=payroll-api' \
  -s 'config."access.token.claim"=true'

# Fine-grained exchange permissions are most reliably configured in the
# Admin Console for the target (audience) client:
#   Clients, payroll-api, Permissions tab, toggle "Permissions enabled".
#   This creates a "token-exchange" scoped permission. Edit that permission
#   and attach a client policy whose clients list contains hr-portal.
# Repeat for document-api, attaching a policy whose clients list contains
# payroll-api.
#
# The exact resource and policy names differ across Keycloak versions, which
# is why the Console, which surfaces the current names, is used here rather
# than a version-fragile kcadm script.
echo "Configure exchange permissions in the Admin Console as described above."

# Direct grant is used only to obtain a subject token without a browser step.
USER_TOKEN=$(curl -sk -X POST \
  "https://localhost:8443/realms/northgate/protocol/openid-connect/token" \
  -d "client_id=hr-portal" \
  -d "client_secret=REPLACE_WITH_HR_PORTAL_SECRET" \
  -d "grant_type=password" \
  -d "username=asmith" \
  -d "password=REPLACE_WITH_ASMITH_PASSWORD" \
  -d "scope=openid profile" | jq -r '.access_token')

echo "$USER_TOKEN" | cut -c1-40; echo "..."

PAYROLL_TOKEN=$(curl -sk -X POST \
  "https://localhost:8443/realms/northgate/protocol/openid-connect/token" \
  -d "client_id=hr-portal" \
  -d "client_secret=REPLACE_WITH_HR_PORTAL_SECRET" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=$USER_TOKEN" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "audience=payroll-api" \
  -d "scope=payroll:read" | jq -r '.access_token')

# Decode and inspect the exchanged token's key claims.
python3.11 - <<PYEOF
import base64, json, os
t = "$PAYROLL_TOKEN".split('.')[1]
t += '=' * (-len(t) % 4)
claims = json.loads(base64.urlsafe_b64decode(t))
print("sub:  ", claims.get("sub"))
print("aud:  ", claims.get("aud"))
print("scope:", claims.get("scope"))
print("act:  ", json.dumps(claims.get("act")))
PYEOF

# service.py
# A minimal audience-validating service. SERVICE_AUD and SERVICE_SCOPE set
# what this instance accepts. The payroll instance additionally knows how to
# exchange onward to the document service.

import os
import json
import base64
from flask import Flask, request, jsonify
import requests
from jwcrypto import jwt, jwk

app = Flask(__name__)
ISSUER = "https://ib-lb:8443/realms/northgate"
JWKS_URL = f"{ISSUER}/protocol/openid-connect/certs"
SERVICE_AUD = os.environ["SERVICE_AUD"]
SERVICE_SCOPE = os.environ["SERVICE_SCOPE"]
requests.packages.urllib3.disable_warnings()
_jwks = jwk.JWKSet.from_json(requests.get(JWKS_URL, verify=False).text)


def _validate(token):
    claims = json.loads(jwt.JWT(jwt=token, key=_jwks, algs=["RS256"]).claims)
    aud = claims.get("aud")
    aud_list = aud if isinstance(aud, list) else [aud]
    if SERVICE_AUD not in aud_list:
        raise ValueError(f"token audience {aud} does not include {SERVICE_AUD}")
    if SERVICE_SCOPE not in (claims.get("scope") or "").split():
        raise ValueError(f"token scope missing {SERVICE_SCOPE}")
    return claims


@app.get("/whoami")
def whoami():
    auth = request.headers.get("Authorization", "")
    _, _, token = auth.partition(" ")
    try:
        claims = _validate(token)
    except Exception as e:
        return jsonify({"error": str(e)}), 401
    return jsonify({
        "service_audience": SERVICE_AUD,
        "resource_owner_sub": claims.get("sub"),
        "act_chain": claims.get("act"),
        "scope": claims.get("scope"),
    })


if __name__ == "__main__":
    port = int(os.environ.get("PORT", "8096"))
    app.run(host="0.0.0.0", port=port, ssl_context="adhoc")

# Terminal A, payroll service
export SERVICE_AUD=payroll-api SERVICE_SCOPE=payroll:read PORT=8096
python3.11 service.py

# Terminal B, document service
export SERVICE_AUD=document-api SERVICE_SCOPE=document:render PORT=8097
python3.11 service.py

# The payroll service presents ITS token as the subject of a new exchange.
# In a real service this call is made from within the payroll service using
# its own client credentials; shown here as a script for clarity.
DOC_TOKEN=$(curl -sk -X POST \
  "https://localhost:8443/realms/northgate/protocol/openid-connect/token" \
  -d "client_id=payroll-api" \
  -d "client_secret=REPLACE_WITH_PAYROLL_API_SECRET" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=$PAYROLL_TOKEN" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "audience=document-api" \
  -d "scope=document:render" | jq -r '.access_token')

curl -sk -H "Authorization: Bearer $DOC_TOKEN" \
  https://localhost:8097/whoami | jq

# The document-addressed token presented to the payroll service must fail.
curl -sk -o /dev/null -w "Document token to payroll service: HTTP %{http_code}\n" \
  -H "Authorization: Bearer $DOC_TOKEN" \
  https://localhost:8096/whoami

# And the payroll-addressed token to the document service must also fail.
curl -sk -o /dev/null -w "Payroll token to document service: HTTP %{http_code}\n" \
  -H "Authorization: Bearer $PAYROLL_TOKEN" \
  https://localhost:8097/whoami