AWS native identity implementation¶
This contract records how the AWS backend binds the shared identity model (#2313). The design records the owner decisions and the threat model. ADR-066 is the binding model.
Service principal proof¶
config.service_identity selects the verifier from CLOUD_PROVIDER. On AWS it
calls shared.aws_web_identity.verify_aws_web_identity_token. The verifier
fetches signing keys from the configured issuer's /.well-known/jwks.json and
requires:
- an ES384 or RS256 signature;
issequal toAWS_SERVICE_TOKEN_ISSUER;audequal toAWS_SERVICE_TOKEN_AUDIENCE, as one value;subthat is an IAM role ARN inAWS_ACCOUNT_ID;- the namespaced
aws_accountclaim equal toAWS_ACCOUNT_ID; exp,iatandjti, with a lifetime of 3600 seconds or less.
Any failure is one bounded denial. The composition root binds a
shared.service_proof profile, so management.service_credentials validates
admission subjects without provider literals. The binding is (issuer, role ARN).
ProviderBinding.subject holds up to 2048 characters, the IAM ARN maximum.
shifter_client.ServiceClient.from_aws obtains tokens with STS
GetWebIdentityToken (ES384, 900 seconds) and renews them 60 seconds before
expiry. The botocore credential chain renews the source role credentials.
Human sessions¶
ShifterOIDCBackend requires auth_time. A Cognito login stores issuer, subject
and auth_time in the session through the login signal. session_credentials
applies the idle and absolute limits to Cognito sessions. At the recheck
interval, config.cognito_directory calls AdminGetUser on the pool that the
issuer names. A disabled, deleted, unconfirmed or unverified user, or a subject
mismatch, ends the session. A provider failure ends it too.
Datastores¶
| Process | Login | Authentication |
|---|---|---|
| Portal, workers, scheduler, launcher | portal_web, portal_workers, ctf_scheduler, provisioner_launcher |
RDS IAM from start (DB_AUTH_MODE=rds-iam) |
| Migration Job | RDS master | Password, owner duties only |
| Provisioner | provisioner_lambda |
RDS IAM |
| Guacamole | guacamole_admin |
Password |
| OpenFGA runtime, admin, migration | openfga_runtime, openfga_admin, openfga_migrator |
Rotated password |
Every connection uses sslmode=verify-full with the region's RDS CA bundle.
The renderer publishes it as DB_SSL_ROOT_CERT_PEM_B64. The entrypoint and the
provisioner write it to a read-only file.
The provisioning Job creates the IAM logins before the identity probe and the
OpenFGA database and base logins. The migration Job runs
reconcile_aws_database_duties, which reuses the GCP application and policy
owner reconcilers. Each runtime login joins the portal_runtime duty. Passwords
reach the server only as SCRAM-SHA-256 verifiers, because the RDS parameter
group logs every statement.
Rotation and refresh¶
modules/portal/eks/openfga.tf creates the three datastore secrets and the
in-repo rotation function lambda/openfga_rotation.py. Runtime and admin use
the alternating-users strategy; the migrator uses single-user. The schedule is
30 days. The function runs in the EKS private subnets under a bounded role.
Its configuration binds each secret ARN to one base login and names the master
secret. The function refuses a secret that holds any other login, so secret
content cannot direct the master credential at another duty.
Secrets Manager runs testSecret when it creates a schedule, so the schedules
exist only when openfga_rotation_schedule is true. The deploy sets it after the
provisioning Job has created the logins, and keeps it on later.
The deploy builds the package. Terraform uploads it to the root's artifact
bucket, AWS Signer signs it, and the functions deploy the signed copy from S3.
The code signing configuration refuses any other code, so teardown needs no
package. The shared lambda-code-signing and lambda-signed-package modules
also sign the portal's Cognito and Redis functions.
shared.cloud.policy_credential_refresh runs weekly. Its IAM role reads only
the three secrets. Its Kubernetes Role allows only patch on the three
openfga-<duty>-datastore Secrets and the two policy Deployments. The
restrict-openfga-credential-refresh admission policy denies any Deployment
change from this identity except the restart annotation.
Gateway renewal¶
The Guacamole extension selects its identity with GUACAMOLE_CONTROL_IDENTITY.
AwsGatewayIdentity uses the AWS SDK for Java STS client and the IRSA
credential chain. The guacamoleClient role may mint tokens only for the
gateway audience, with ES384 and at most 900 seconds. The portal accepts the
token only when the role ARN equals GUACAMOLE_CONTROLLER_ROLE_ARN.
IAM and operator access¶
| Grant | Scope |
|---|---|
Portal, workers, CTF scheduler, provisioner launcher cognito-idp:AdminGetUser |
The installation user pool only |
guacamoleClient sts:GetWebIdentityToken |
One audience, ES384, at most 900 seconds |
policyCredentialRefresh, provisioning Job |
Read the three datastore secrets |
| Runtime roles | Their own rds-db:connect user; no master or Guacamole secret |
| Deploy role trust | Exact deploy Environments, exact protected refs, named operators |
| Deploy role tunnel | AWS-StartPortForwardingSessionToRemoteHost on the tagged access node |
The operator access node has no public address, no inbound rule and only the Session Manager core policy. IAM users that assume the deploy role need MFA and a source identity equal to their user name.
Verification¶
Unit tests cover the verifier, admission, the client, session assurance, the gateway (Python and Java), database settings, the entrypoint, the provisioning and reconciliation commands, the rotation function and the refresh Job. Terraform tests cover the IAM grants, secret readers, rotation settings and the access node. A released-server PostgreSQL test covers the IAM logins and duties. These tests do not prove live IAM, token renewal, rotation or tunnel behavior.