query-orchestration/docs/ai.generated/13-two-pool-service-accounts.md

# Two-Pool Service Accounts (Cognito)

Reference for the multi-issuer authentication path introduced by the
`api.key.support.cognito.two-pool.plan.3.claude.md` plan. Human users
keep authenticating through the existing Cognito user pool ("pool A");
machine callers authenticate through a second user pool ("pool B")
that has MFA disabled. queryAPI accepts JWTs from either pool with no
other code changes for the consuming caller.

This page covers what changed in queryAPI, the operator-side setup,
the lifecycle CLI, and what to verify when something breaks.

## What the feature changes

| Surface | Pool A (humans) | Pool B (service accounts) |
| --- | --- | --- |
| Cognito user pool | unchanged (`COGNITO_USER_POOL_ID`) | new (`COGNITO_SVC_USER_POOL_ID`) |
| JWKS | `COGNITO_JWKS_URL` (derived) | `COGNITO_SVC_JWKS_URL` (derived) |
| Caller flow | OAuth + PKCE + MFA via hosted UI | `InitiateAuth` USER_PASSWORD_AUTH |
| `iss` claim | `https://cognito-idp.<region>.amazonaws.com/<pool-A-id>` | `.../<pool-B-id>` |
| `auth_source` (echo ctx) | `"user"` | `"service"` |
| Env check (`CheckUserEnvironmentAccess`) | looks up `sub` in pool A | looks up `sub` in pool B |
| EULA agreement | required on first login | not applicable (service accounts cannot interactively agree) |
| Permit.io user | keyed on pool A `sub`, attribute `is_service_account` absent | keyed on pool B `sub`, attribute `is_service_account=true` |
| Lifecycle | `cmd/auth_related/user.creation.tool` | `cmd/auth_related/service.account.tool` |

The feature is **off by default**. With `COGNITO_SVC_USER_POOL_ID`
empty, queryAPI rebuilds the keyset map with only pool A and the
runtime behavior is bit-identical to pre-change.

## Configuration

Set these in `.env` (or the equivalent secret store) when enabling
pool B for an environment:

```dotenv
# Required to turn the feature on. queryAPI derives the JWKS URL from
# this id at startup. The CLI tool refuses to run when this is empty.
COGNITO_SVC_USER_POOL_ID=us-east-2_Qom1i9qIG

# Optional. Defaults to the cognito-idp.<region>.amazonaws.com URL
# computed from COGNITO_SVC_USER_POOL_ID + COGNITO_REGION. Override
# only for tests that point at a fake JWKS endpoint.
COGNITO_SVC_JWKS_URL=

# Only the CLI tool and consuming callers need this. queryAPI itself
# does not call InitiateAuth — it only validates tokens — so it is
# safe to omit on queryAPI hosts.
COGNITO_SVC_APP_CLIENT_ID=6r7chkvjotgs2bsfbd5ibaaft7
```

The full template is in `.env.example`. The provisioning scripts in
`cmd/auth_related/service.accounts/creation.scripts/` print the
correct values for the dev environment.

## Caller flow

A consuming process needs `(username, password, app-client-id)` plus
the pool id. It does not need AWS IAM credentials — `InitiateAuth` is
an unauthenticated Cognito endpoint.

```bash
# 1. Get an access token. Refresh ~10 min before exp.
aws cognito-idp initiate-auth \
  --region "$COGNITO_REGION" \
  --client-id "$COGNITO_SVC_APP_CLIENT_ID" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME="$SVC_USERNAME",PASSWORD="$SVC_PASSWORD"

# 2. Call queryAPI with the access token. The token shape is
#    identical to a human token: sub, iss, username, exp, ...
curl https://queryapi.example.com/clients \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. When near expiry, refresh.
aws cognito-idp initiate-auth \
  --region "$COGNITO_REGION" \
  --client-id "$COGNITO_SVC_APP_CLIENT_ID" \
  --auth-flow REFRESH_TOKEN_AUTH \
  --auth-parameters REFRESH_TOKEN="$REFRESH_TOKEN"
```

For a zero-dependency reference implementation in Python, see
`cmd/auth_related/service.accounts/test.scripts/test.service.account.auth.py`.

## How queryAPI authenticates two issuers safely

`internal/cognitoauth/token.go` builds an `IssuerKeysets` map at the
start of each verifier call: pool A always present, pool B added when
`COGNITO_SVC_USER_POOL_ID` is set. Verification is a two-pass:

1. Peek at the token's `iss` claim **without** trusting it (no
   signature check). The peek's only job is to pick a keyset.
2. Re-parse the token with `jwt.WithKeySet(keySet)` and
   `jwt.WithIssuer(iss)`. A forged `iss` therefore fails because the
   chosen pool's JWKS does not contain the signer's key.

Anything whose `iss` is not in the map is rejected with
`"untrusted issuer: ..."`. The JWKS cache (`internal/cognitoauth/jwks.go`)
is keyed by URL, so the two pools never clobber each other's
cached keys.

## Service-account lifecycle CLI

`cmd/auth_related/service.account.tool` wraps the Cognito + Permit
calls needed to manage pool B users from an operator workstation.
Source layout mirrors `user.creation.tool`.

Subcommands:

```text
service.account.tool create <username>          [--description text] [--env-id id] [--roles r1,r2]
service.account.tool show <username>
service.account.tool list
service.account.tool disable <username>          # AdminDisableUser + AdminUserGlobalSignOut
service.account.tool enable <username>           # AdminEnableUser
service.account.tool rotate-password <username>  # AdminSetUserPassword (permanent)
service.account.tool delete <username>           # AdminDeleteUser + DeletePermitUser
service.account.tool register-permit <username> [--roles r1,r2]
        # Registers an already-existing Cognito service-account in
        # Permit and assigns roles. Use this when the Cognito user was
        # created outside the tool (e.g. by the bring-up shell scripts
        # in cmd/auth_related/service.accounts/creation.scripts/).
```

Env vars (the wrapper `run.tool.sh` sets the dev defaults):

```dotenv
COGNITO_REGION=us-east-2
COGNITO_SVC_USER_POOL_ID=us-east-2_Qom1i9qIG
COGNITO_SVC_APP_CLIENT_ID=6r7chkvjotgs2bsfbd5ibaaft7
PERMIT_IO_API_KEY=...
PERMIT_IO_BASE_URL=https://api.permit.io
AWS_PROFILE=...
```

The `create` command:

- prints the password **once**;
- stores nothing local (you must copy it into your secret store);
- registers the user in Permit with `is_service_account=true`;
- assigns any roles passed via `--roles`.

If `PERMIT_IO_API_KEY` is unset, the create flow logs a warning and
skips the Permit step — useful for offline dry-runs but not what you
want in production.

## EULA

queryAPI does not currently enforce EULA acceptance with a middleware
gate — the EULA endpoints (`/eula/agree`, `/eula/status`) are
self-service and surface status. Service accounts simply do not call
them. If a future change introduces an EULA-enforcement middleware,
the right hook is `auth_source == "service"` → skip; the value is
already on the echo context by then.

## Revocation

Cognito does not provide instant revocation for outstanding access
tokens. The mitigation is two layers:

1. Bound the lag with the pool B `AccessTokenValidity` setting
   (60 minutes by default; can drop to 5 minutes per the plan).
2. Operator runs `service.account.tool disable <username>`:
   - `AdminDisableUser` blocks new auth + refresh attempts.
   - `AdminUserGlobalSignOut` revokes all refresh tokens.
   - Outstanding access tokens remain valid until `exp`.

If sub-minute revocation is ever required, the follow-up is an
in-service deny list keyed on `sub` for `auth_source == "service"`.
It is deliberately not in scope for v1.

## Testing locally

Unit tests covering the multi-issuer paths live in:

- `internal/cognitoauth/multi_issuer_test.go`
  (verifier accepts pool A + pool B tokens, rejects forged `iss`, rejects unknown issuers)
- `internal/cognitoauth/envcheck_test.go`
  (`CheckUserEnvironmentAccess` dispatches on `auth_source`; rejects
  when `auth_source=service` but pool B is unconfigured)
- `cmd/auth_related/service.account.tool/main_test.go`
  (password class invariants, CSV splitter)

Run the targeted set with:

```bash
go test ./internal/cognitoauth/ -run TwoPool
go test ./cmd/auth_related/service.account.tool/
```

For an end-to-end smoke test against the dev pool B, see
`cmd/auth_related/service.accounts/test.scripts/test.service.account.auth.py`.

Lifecycle coverage (disable / enable / rotate-password / delete) lives
in `scripts/manual_tests/test_two_pool_lifecycle.py`. It uses a
throwaway user (`SVC_LIFECYCLE_USERNAME`, default
`svc-lifecycle-test-1`) so it never collides with the long-lived
super-admin test account.

Both manual scripts read credentials from the env vars documented in
`.env.example` under "Pool B (service-accounts) test credentials"
(`SVC_TEST_USERNAME`, `SVC_TEST_PASSWORD`, `SVC_TEST_SUB`,
`SVC_TEST_USER_POOL_ID`, `SVC_TEST_APP_CLIENT_ID`). A repo-root
`.env` is auto-loaded; no third-party `dotenv` library is required.

## When something breaks

| Symptom | Likely cause | Where to look |
| --- | --- | --- |
| All requests return 401 right after enabling pool B | Wrong `COGNITO_SVC_JWKS_URL` or pool B JWKS endpoint unreachable | `loadIssuerKeysets` in `middleware.go`; check server startup logs for `"loading service pool JWKS"` |
| Service token returns 403 from env check | Pool B `sub` not registered in Permit.io with the right `environment_id` and roles | `service.account.tool register-permit <username>` |
| `"untrusted issuer"` warnings | Token issued by a Cognito pool that is not configured | Verify the token's `iss` matches one of the two configured pools |
| `"untrusted issuer"` for a known pool right after rollout | Pool B JWKS not loaded because `COGNITO_SVC_USER_POOL_ID` is empty | Confirm env var presence with a `printenv \| grep COGNITO_SVC` |
| EULA endpoint returns "Insufficient permissions" for service token | Service account does not have a role with `eula` action permission | Either grant the role in Permit, or do not call EULA endpoints from service code |