Access Control Architecture

Property	Value
Controls	SID-AUTH-02, SID-HARD-03, SID-HARD-05, SID-CRYPTO-02
ISO 27001	A.8.1 (User endpoint devices), A.8.2 (Privileged access rights), A.8.18 (Use of privileged utility programs)

Purpose

This document describes the access control architecture across the SIROS ID platform: authentication mechanisms per endpoint, the tenant isolation model, privileged (admin) access controls, and rate limiting. It addresses the finding that platform-level endpoint protection exists but formal documentation of the admin token lifecycle and operator-side device/access policies was incomplete.

Authentication Mechanisms

User Authentication (JWT)

All user-facing API requests are authenticated via HMAC-signed JWT bearer tokens issued after WebAuthn login.

Property	go-wallet-backend	facetec-api
Algorithm	HS256	HS256/384/512
Claims	user_id, did, tenant_id, jti, exp, iss, aud	tenant_id, optional iss
Revocation	In-memory JTI blacklist	None (expiry only)
Refresh	Rotating refresh token	N/A
Source	WebAuthn login flow	External provisioning

Admin Authentication (Bearer Token)

The go-wallet-backend admin API uses a pre-shared bearer token on a separate port:

Property	Value
Token size	32 bytes (256 bit), hex-encoded
Generation	crypto/rand.Read() via GenerateAdminToken()
Comparison	Constant-time (crypto/subtle.ConstantTimeCompare)
Sources	WALLET_SERVER_ADMIN_TOKEN env, admin_token_path file, server.admin_token config, or auto-generated at startup
Scope	Full admin API access (tenant/user/issuer/verifier CRUD)

OIDC Gate

Registration and login can be gated by OIDC identity provider validation:

• Per-tenant OIDC provider configuration (issuer, audience, JWKS URI)
• Two gate types: GateTypeRegistration (new users), GateTypeLogin (returning users)
• Validator instances cached per issuer with JWKS auto-refresh
• Optional bind_identity mode: binds OIDC subject to user record

vc Platform Authentication

Mechanism	Scope	Details
Basic Auth	apigw restricted routes	Username/password map for credential notification endpoints
JWT + SPOCP	apigw authorised routes	ECDSA-signed JWTs with S-expression policy engine for fine-grained path/method/subject authorisation
Per-credential auth_method	Credential issuance	Each credential type references an auth method (basic or pid_auth); pid_auth requires presenting a valid PID credential
Admin GUI session	Registry admin	Form login with encrypted cookie session (HttpOnly, Path=/admin, MaxAge=3600)

go-trust (AuthZEN PDP)

The AuthZEN evaluation endpoint (POST /evaluation) is unauthenticated. Security relies on:

• Network-level controls (deploy behind reverse proxy or service mesh)
• go-wallet-backend's SPOCP-authorised proxy firewall (fail-closed in production)

Tenant Isolation Model

Key properties:

• JWT tenant_id claim is authoritative — if X-Tenant-ID header differs, JWT wins
• Disabled tenants receive 403 regardless of valid JWT
• User-tenant membership optionally verified via TenantMembershipMiddleware
• Cross-tenant login prevented by tenant hash verification in WebAuthn userHandle (v1 format)
• facetec-api: JWT tenant_id selects per-tenant policy engine and issuer parameters

Privileged Access Controls

Admin API Separation

The admin API runs on a separate port (default 8081) with its own http.Server instance:

Property	Value
Default bind	Configurable (0.0.0.0 or loopback) — security enforced by deployment network policy
Disable	Set admin_port: 0
Unauthenticated routes	/admin/status (health check only)
Authenticated routes	All other /admin/* — tenant CRUD, user management, issuer/verifier config, invite management

Admin Token Lifecycle

Operator responsibilities:

• Configure explicit admin token via environment variable or file path for production
• Restrict admin port to management plane using Kubernetes Service/Ingress scope and NetworkPolicy
• Establish token rotation schedule (no built-in rotation mechanism)
• Ensure DEBUG-level logs are not shipped to broadly-accessible log aggregators

SPOCP Authorization Firewall

The go-wallet-backend includes a SPOCP (S-expression) authorization layer that gates AuthZEN evaluation queries forwarded to the trust PDP:

• Fail-closed in production: refuses to start with NoOpAuthorizer when GIN_MODE=release
• Policy rules define allowed (api (service)(method)(path)(subject)) patterns
• Ensures only expected query patterns reach the unauthenticated PDP

Rate Limiting

Component	Scope	Mechanism	Default
go-wallet-backend (auth)	WebAuthn registration/login, token refresh	Per-identifier sliding window with lockout	10 attempts/60s, 300s lockout; failed attempts cost 2 tokens
go-wallet-backend (registry)	VCTM registry queries	Per-tenant (auth) + shared anonymous pool	Configurable RPM; privacy-preserving (no IP tracking for anonymous)
facetec-api	Biometric endpoints	Per-IP sliding window + concurrency semaphore	Configurable RPM + MaxConcurrentBiometric; 503 when full; 10 MB body cap
go-trust	All API endpoints	Per-IP token bucket	Configurable RPS + burst (optional)
vc (verifier)	Token/authorize/register	Per-IP token bucket	20/min for token endpoint

Public (Unauthenticated) Endpoints

These endpoints are accessible without authentication and should be protected at the network level:

Component	Endpoints	Purpose
go-wallet-backend	/health, /status, /readyz	Kubernetes probes
go-wallet-backend	/api/v1/tenants/:id/config	Public tenant configuration
go-wallet-backend	WebAuthn begin/finish (register, login)	User authentication flows (rate-limited, OIDC-gated)
facetec-api	/livez, /readyz, /healthz	Kubernetes probes
facetec-api	/metrics	Prometheus scraping
go-trust	/readyz, /livez	Kubernetes probes
go-trust	/.well-known/authzen-configuration	AuthZEN discovery
go-trust	/evaluation	AuthZEN trust evaluation

Operator Responsibilities

The platform provides the authentication and authorization mechanisms above. Operators must additionally:

Responsibility	Guidance
Network-restrict admin port	Treat admin API as management-plane only: enforce ClusterIP/private ingress scope plus Kubernetes NetworkPolicy
Network-restrict go-trust	Deploy behind service mesh or reverse proxy; do not expose evaluation endpoint publicly
Network-restrict metrics/health	Ensure /metrics endpoints are only reachable by Prometheus/monitoring infrastructure
Manage admin token rotation	Use file-based token source (admin_token_path) for rotation without restart
Configure CORS for production	Set explicit AllowedOrigins list; do not use wildcard with credentials enabled
Manage device policies	Implement endpoint device management policies per organisational requirements (outside platform scope)