Unified credential boundary¶
Issue #2316 delivers ADR-066 S3 source for the coordinated S8 cutover. Do not deploy it alone into a mixed-authority production fleet. S4–S6 own the named domain enforcement conversions; S7 owns deployed IAM; S8 qualifies and activates the complete parent design. This change does not deploy cloud resources or grant cloud roles.
Admission and ownership¶
shared.credentials.CredentialContext carries an immutable principal, credential
kind, safe identifier and exact action ceiling. One bearer-first DRF authenticator
dispatches to public Knox or the provider's native service proof verifier: Google
ID tokens on GCP and AWS STS web identity tokens on AWS (#2313). Invalid bearer proof raises
401 even beside a valid session. Legacy human-only consumers reject services;
they never impersonate the service's creator. OpenFGA administration consumes the
neutral context directly.
Management owns principal/binding/admission lifecycle. Provider tuples are immutable and unique. Native service admissions have immutable audience/scopes and irreversible disable; a replacement row preserves the principal. SQL guards cover ORM bulk writes on both SQLite and PostgreSQL. Credential operations and strict audit records commit together. No network policy/provider call occurs under their database row locks.
User saves idempotently reconcile the profile and human principal in one transaction. If creation ran in autocommit and identity/audit persistence failed after the user insert, authentication remains denied until a later user save repairs the missing rows. Retry that save after restoring audit persistence; reconciliation emits one principal-creation audit record and grants no authority.
Authorized credential administration and service participation record the caller
in the canonical actor_principal_uuid audit field, including nested principal
and provider-binding creation. Workspace authorization request context and its
durable mutation journal carry the same UUID through confirmation/reconciliation.
Audit canonicalization v2 hashes that field; historical v1 records are preserved
unchanged. See audit architecture
for the append-profile migration and the prohibition on mixed-version writers.
Knox owns all personal-token generation, hashing and verification. Metadata retains
scope, exact issuance target, principal, expiry, ownership and audit identity. Native proof expiry cannot
extend metadata expiry. Historical rows receive deterministic public credential IDs
and exact owner-principal mappings but no new secret. requires_reissue identifies
unrevoked historical rows. Orphaned rows remain unusable; no email-based repair occurs.
Issuance requires a human session with CSRF, a live token-use grant and a live policy
check for every requested action under SQL-resolved target ancestry. Canonical new
scopes are authorization:<action-code>. Legacy HTTP scope aliases cannot be newly
issued through the management API. The exact target type/UUID is persisted and
SQL-immutable, reconstructed into the credential ceiling, and checked by every
AuthorizationRequest; even another resource the owner can access is denied.
At use time credential ceilings restrict actions and targets;
live application policy and domain lifecycle remain independently required.
Human and temporary sessions¶
The obsolete PLAT-101/CTF-608 magic-link flow was removed in CTF migration 0033 (#1206). The maintainer explicitly confirmed preserving current isolated-account login and recovery for #2316, not restoring that retired protocol.
Firebase Admin verifies signature, revocation, exact project audience/issuer and
configured tenant. Enrollment alone is not MFA assurance: the verified token must
show a totp or phone second-factor sign-in. Provider account lookup independently
requires verified email and enrollment. The management binding facade rejects
collisions and temporary accounts; it synchronizes the immutable principal binding.
Only non-secret identity/timing evidence enters Django sessions. HTTP and Channels share local-principal checks and bounded Firebase user-state revalidation. Provider outage fails closed when revalidation is due. WebSockets reload the stored Django session before admission and each received/sent message, so logout and password invalidation do not leave a cached authenticated socket. No raw ID token is retained.
Temporary email-free accounts keep their existing Django login, password-change and
event lifecycle gates. Their neutral credential context names one live event and
permits only event.read/event.participate, never administration, provider binding
or personal-token issuance. Existing CTF HTTP/socket boundaries remain in force.
The canonical ceiling binds the exact event target, and the context rejects any
disagreement between that target and its event UUID.
Participant principal UUIDs are scalar projections on the existing participation
record, not a second authority store. Ordinary QA services use the same participation
record and live policy plus event/status predicates.
An actor with live event.manage_participants authority can POST
/api/v1/ctf/events/{event_uuid}/principal-participants/ with an existing service's
principal_uuid and display name. This creates no Django user or credential and
grants no OpenFGA action. With separate event.participate authority and admission,
that service can GET /api/v1/ctf/me/events/{event_uuid}/participant/ using its native
ID token. The response is the existing participant-safe current-event projection;
canonical registration/status eligibility, exact event and live principal/policy
checks remain mandatory. This is the ordinary principal boundary, not a QA role or
service-name exception.
Configuration¶
| Setting | Default | Enforced policy |
|---|---|---|
GCP_SERVICE_TOKEN_AUDIENCE |
empty outside GCP renderer | Exact HTTPS portal audience; empty disables native bearer admission |
AWS_SERVICE_TOKEN_ISSUER |
empty outside AWS renderer | Exact account issuer for STS web identity tokens; any other value disables AWS bearer admission |
AWS_SERVICE_TOKEN_AUDIENCE |
empty outside AWS renderer | Exact HTTPS portal audience for AWS service tokens |
AWS_ACCOUNT_ID |
empty outside AWS renderer | The account that owns the issuer; service subjects must be role ARNs in it |
IDENTITY_PLATFORM_TENANT_ID |
empty | Exact configured tenant, including rejection of unexpected tenancy |
IDENTITY_SESSION_ABSOLUTE_SECONDS |
28800 | 60–86400; measured from provider authentication |
IDENTITY_SESSION_IDLE_SECONDS |
1800 | 60–3600 |
IDENTITY_SESSION_RECHECK_SECONDS |
300 | 1–300; maximum provider-state staleness |
API_TOKEN_MAX_TTL_DAYS |
365 | 1–365; finite and immutable at issue time |
The GCP runtime renderer derives audience from SITE_URL and forwards the tenant and
session bounds from its environment. The portal manifest and installer runtime
inventory/published contract declare these values. Invalid bounds fail startup.
Tenant configuration must match the provider, browser and server; changing the
provider project/tenant invalidates existing human-session evidence.
Supported renewable client¶
Install the repository-owned package (Python 3.12+):
The client composes Google's Credentials, IDTokenCredentials and
AuthorizedSession. The official library refreshes before requests as proof expires;
there is no renewal daemon, custom JWT issuer, password protocol or static-key flow.
Application ID tokens and cloud OAuth access tokens use separate transport instances.
Native APIs and refresh behavior are documented by
google-auth
and AuthorizedSession.
from bigrae_client import ServiceClient
client = ServiceClient.from_adc(
"https://portal.example.test",
target_principal="agent@synthetic-project.iam.gserviceaccount.com",
)
try:
response = client.request("GET", "/api/v1/bootstrap/")
response.raise_for_status()
# Cloud IAM remains independently authoritative. Never send the app token here.
cloud_response = client.cloud.get(
"https://storage.googleapis.com/storage/v1/b/synthetic-bucket", timeout=30
)
cloud_response.raise_for_status()
finally:
client.close()
Source credential options:
- Attached workload: run under an attached Google service account whose metadata
identity endpoint emits its Google ID token with email. Omit
target_principal. Direct federated Kubernetes principal subjects are not service-account numeric IDs; configure service-account impersonation when the metadata endpoint does not expose the registered identity. See attached ADC. - Local impersonation: use
gcloud auth application-default login, then provide the explicit target service-account email above. The source needs permission to generate ID/access tokens on that account (normally Service Account Token Creator), and IAM Credentials API must be enabled. Alternatively, Python supports ADC created bygcloud auth application-default login --impersonate-service-account=...; omit the target argument to use that configured impersonation. User ADC is renewable only while its refresh authorization remains valid. See local ADC. - External federation: use an administrator-generated, trusted external-account
ADC configuration through
GOOGLE_APPLICATION_CREDENTIALSand an explicit target service account. The external provider must keep supplying fresh subject proof, and IAM must permit the configured impersonation chain. A file containing a single expiring subject token is not indefinitely renewable; its producer must refresh it. Do not accept untrusted credential configuration or executable suppliers. See auth-library federation.
On AWS, use ServiceClient.from_aws(audience) from the aws extra
(python -m pip install "./shifter/shifter_client[aws]"). It obtains STS
GetWebIdentityToken tokens (ES384, 900 seconds) for exactly that audience and
renews them before expiry. The botocore credential chain renews the source role
credentials, for example from IRSA or an assumed role. The caller's role needs
sts:GetWebIdentityToken limited to the audience, and an admission for its role
ARN. IAM user credentials are not service identities. See the
AWS native identity guide.
Long-running success depends on a renewable source, valid IAM, available provider endpoints and live BigRAE admission/policy. A pasted bearer or revoked local refresh token cannot renew. The app transport rejects foreign-origin URLs and redirects and does not replay mutations on 401. Handle transient errors with the operation's documented idempotency contract, not indiscriminate retries. Do not log headers, credential objects, token responses or secrets.
Verification and enforcement¶
Focused tests cover real Knox storage/verification, live grant loss, owner revocation,
MFA assurance and substitution, service independence, native refresh across expiry,
session/logout checks, SQL immutability and PostgreSQL concurrent rotation. The UI's
one-time response bypasses query/mutation caches. The client package belongs to the
platform quality unit; its tests run in the platform environment without importing
Django. Config's sanctioned workspace edge adds only hierarchy_target_scope, a
read-only ancestry projection. No layer gains access to another domain's models.
Issue #2316 acceptance mapping¶
Paths below are relative to shifter/shifter_platform/ except the standalone client.
- [x] Human SDK assurance, exact identity and bounded revocation:
config/identity_platform.py:198,config/session_credentials.py:17andconfig/websocket_auth.py:17; assurance/session tests include factor-only enrollment rejection, wrong issuer/audience/tenant, logout, expiry and outage. - [x] Invalid bearer never falls through; substitution, binding collision and
disabled principals deny:
shared/api_tokens/authentication.py:38,config/service_identity.py:13,management/principals.py:106;tests/config/test_service_identity.py,tests/management/test_principals.pyandtests/config/test_session_credentials.py. - [x] Live-granted personal issue/use, action ceiling, finite immutable expiry,
no recursive minting and own revocation after grant loss:
management/personal_credentials.py:23,shared/api_tokens/policy.py:1andshared/api_tokens/models.py:26; personal-service, API, SQL-guard and PostgreSQL concurrent-rotation tests cover the lifecycle. - [x] Independent service identity/contact/lifecycle, separate application and
cloud authority:
management/service_credentials.py:1,management/principals.py:106,shared/api/principals.py:31andshifter/shifter_client/__init__.py:16(repository-root path).tests/management/test_service_admission.pyverifies creator independence. - [x] Supported native renewal across three ID/access token expiry cycles,
attached metadata and external federation/impersonation:
shifter/shifter_client/__init__.py:16(repository-root path), verified bytests/config/test_service_client.py; source-renewability limits and all three setup paths are documented above. - [x] Email-free event-confined authentication and ordinary QA service
participation:
config/credential_scope.py:1,shared/credentials.py:15andctf/services/principal_participation.py:18;tests/ctf/test_service_participation.py, the existing participant-account and authentication tests, andtests/shared/test_credential_context.py. Current login/recovery is preserved; the retired migration-0033 magic-link flow stays retired, as explicitly confirmed by the maintainer. - [x] Credential/service management API/UI, one-time secret presentation and
safe pagination:
management/api/credential_views.py:1,frontend/src/features/credentials/AccessCredentialsPage.tsx:1andfrontend/src/features/credentials/ServiceCredentialsPanel.tsx:1;tests/management/test_credential_api.pyand the page's component test. - [x] Deterministic S8 reissue mapping with no legacy proof verification:
shared/migrations/0027_personal_credential_metadata.py:10,shared/api_tokens/models.py:26, verified bytests/shared/test_personal_credentials.py. Knox and Google public library interfaces own proof generation/verification/refresh; no custom protocol or renewal daemon is added.
PLAT-102/106 and CTF-006 retain active contracts with reconciled traceability; PLAT-101/CTF-608 retain their historical statements marked deprecated, documenting the already-retired magic-link flow rather than claiming a new implementation.