Authentication and identity¶

eAkto supports two citizen sign-in choices: eGovPH SSO and eVerify. Both end by issuing an internal eAkto application session. Provider secrets and provider access tokens remain in FastAPI.

eGovPH SSO flow¶

Flutter requests /auth/egovph/start
  → backend reports whether partner credentials are configured
  → citizen obtains/scans an eGovPH one-time exchange code
  → Flutter sends only that code to /auth/egovph/callback
  → backend exchanges it using partner credentials
  → backend obtains the authorized citizen profile
  → eAkto creates or reuses a user and returns an eAkto session

The provider contract used by this repository does not require an EGOVPH_SSO_AUTHORIZE_URL. The configured values are the base URL, partner code, and partner secret.

The exchange code is short-lived and single-use. Never log it or store it in Flutter secure storage.

eVerify sign-in flow¶

eVerify sign-in uses explicit biometric consent and Face Liveness.

POST /auth/everify/start
  → one-time eAkto challenge + public Web SDK key
  → official Face Liveness Web SDK
  → one-time face_liveness_session_id
  → demographics OR signed National ID QR
  → POST /auth/everify/complete or /auth/everify/qr/complete
  → provider verification
  → HIGH-assurance eAkto session

The standard demographic flow submits the name and birth date entered by the citizen. The QR flow relays a signed QR value for verification. The raw QR value and biometric media are not persisted in the eAkto domain database.

eAkto application session¶

On successful sign-in, the backend returns a high-entropy session token once. The database stores only its SHA-256 hash.

Clients authenticate with:

Authorization: Bearer EAKTO_SESSION_TOKEN

X-Session-Token is accepted for compatibility, but Bearer authentication is preferred.

Sessions default to an eight-hour lifetime. Sign-out marks the server session inactive and clears Flutter secure storage. Flutter clears local state even when the server session has already expired.

High assurance¶

Some operations require more than an ordinary authenticated session:

• creating a journey with private document evidence;
• refreshing journey evidence;
• listing, uploading, or opening vault documents.

require_high_assurance requires a current assurance record for DOCUMENT_VAULT_ACCESS. The default assurance lifetime is 15 minutes and is configurable.

Profile data¶

The profile screen is read-only for SSO-derived information. The backend returns a minimized profile containing fields required by eAkto’s citizen experience, such as display name and optional contact/photo information. Profile editing is not exposed because authoritative updates belong to the identity provider.

Production controls still required¶

• Rate-limit public challenge creation and completion routes.
• Bind callbacks to approved HTTPS origins.
• Add replay monitoring for challenge and exchange-code failures.
• Define biometric consent records and retention with legal review.
• Review the exact authorized provider contract before deployment.