Overview#
The Citizen Authentication module provides a dedicated identity and access system for members of the public accessing government digital services. Separate from internal staff authentication, it supports government identity providers, social identity, and custom organisational OIDC providers through a standards-compliant OAuth 2.0 PKCE flow. Citizens authenticate once and receive a scoped session token that grants access to tenant-branded portals, service request tracking, representative query systems, and other public-facing workflows, without exposing any staff or internal platform surfaces.
The module is designed for high-assurance public-sector deployments where identity verification, privacy, and cross-provider interoperability are core requirements.
Key Features#
- PKCE OAuth 2.0 Flow: Proof Key for Code Exchange ensures authorisation codes cannot be intercepted or replayed, meeting the security requirements of government digital services without requiring client secrets on public devices
- MyGovID Integration: Native support for Ireland's national digital identity service, including automatic endpoint discovery, form_post response mode, and claim normalisation across given name, surname, and locale fields
- Multi-Provider Support: Connect MyGovID, Google, Apple, and any standards-compliant OIDC provider within the same tenant deployment; each provider is independently configured with its own client credentials and claim mapping
- JWT Claim Normalisation: Extracts verified identity attributes (name, email, locale, subject identifier) from non-uniform claim paths across providers, delivering a consistent citizen profile regardless of the upstream IdP
- Email Verification Enforcement: Requires email_verified claims by default; configurable fallback policy allows tenants to accept unverified email for lower-assurance use cases
- SSRF-Protected Discovery: All JWKS and metadata endpoint URLs are validated against private IP ranges before any network request is made, preventing server-side request forgery attacks in multi-tenant environments
- Tenant-Scoped Session Tokens: Citizen access tokens carry both a citizen identifier and an organisation identifier and are issued in a separate cookie namespace from staff tokens, ensuring citizens can never traverse staff-only surfaces
- Separate Identity Store: Citizen accounts are maintained in a dedicated database table distinct from staff user records, preventing accidental cross-table privilege escalation
- Account Takeover Protection: An identity provider asserting an email address can never silently take over an existing citizen account that was created with a password or is bound to a different provider; the citizen must sign in with their original method and link additional providers explicitly. Accounts matched by their stable provider identifier continue to sign in seamlessly, and genuinely unlinked accounts can still be linked on a verified email
- Assertion Replay Protection: Every provider sign-in binds a per-request one-time cryptographic value into the identity assertion and verifies it on return, so an assertion issued for one login attempt can never be substituted or replayed into another
- Generic Verification Errors: Identity verification failures return a generic message to the client; internal error details and library class names are never exposed in responses
Use Cases#
Government Digital Services Access#
Citizens authenticate with their national digital identity (such as MyGovID) to access personalised service dashboards, track open service requests, view correspondence history, and submit new enquiries, all without creating a separate platform password.
Representative Portal Sign-In#
Elected members and their constituency staff sign in through the citizen authentication flow to access the representative portal, file constituent queries, and manage case responses with organisation-scoped access.
Multi-Portal Deployments#
A single local authority deployment can serve a citizen self-service portal, a public planning portal, and a representative portal, each with its own branding and feature set, all backed by the same citizen authentication layer with per-tenant provider configuration.
Social Identity Fallback#
Organisations that do not mandate a national identity provider can offer Google or Apple sign-in as a fallback, with the same normalised profile output and session model, reducing barriers for digital service adoption. Where a resident holds multiple login options for the same email address, the account-takeover protections above prevent one provider from quietly claiming an account bound to another sign-in method.
Custom Enterprise OIDC#
Regional agencies or partner organisations with their own identity infrastructure configure a custom OIDC provider using standard metadata discovery, allowing staff from partner bodies to access shared portals under their own organisational credentials.
How It Works#
Integration#
Citizen Authentication integrates with the Representative Portal, Citizen Self-Service Portal, and Municipal CRM to provide the identity layer for all public-facing workflows. The issued citizen session token is verified by downstream portal services using the authentication service's token introspection endpoint. Provider configuration (client identifier, scopes, claim mappings) is managed per tenant through the administration console, allowing each local authority or agency to connect its own preferred identity provider without affecting other tenants.
Open Standards#
- OAuth 2.0 (RFC 6749) with PKCE (RFC 7636): The authorisation code flow uses Proof Key for Code Exchange throughout; a SHA-256 code challenge and verifier pair is generated per session, preventing authorisation code interception on public and mobile clients.
- OpenID Connect Core 1.0: Provider discovery via the standard well-known configuration document, ID token issuance, UserInfo endpoint consumption, and the standard subject, email, email-verification, and locale claims are all implemented; claim normalisation bridges non-uniform claim paths across MyGovID, Google, Apple, and custom providers.
- JSON Web Token (RFC 7519): All citizen session tokens are RS256-signed JWTs carrying the standard issuer, audience, subject, expiry, issued-at, not-before, and token-identifier claims alongside a scope claim; the implementation enforces mandatory claim presence and audience segregation between citizen and staff tokens.
- JSON Web Key Sets (RFC 7517): JWKS endpoints are fetched from upstream identity providers to verify incoming ID token signatures, and a dedicated citizen JWKS endpoint is exposed so downstream portal services can verify citizen tokens without shared secrets.
- OpenID for Verifiable Presentations (OpenID4VP): An abstract verifier interface and remote adapter support wallet-based credential presentation for EU Digital Identity Wallet (EUDI) integration, allowing high-assurance identity verification where providers expose an OpenID4VP endpoint.
- OAuth 2.1 (draft): The magic-link authentication path is implemented as an OAuth 2.1 flow, issuing Bearer tokens with explicit audience, scopes, and JTI-based session revocation.
- RFC 1918 / SSRF mitigations: All JWKS and OIDC metadata URLs are validated against RFC 1918 private address ranges and link-local networks before any outbound request, with DNS resolved once and the resulting IP pinned to prevent DNS-rebinding attacks.
Compliance#
- PKCE (RFC 7636) compliance prevents authorisation code interception on public and mobile clients
- Separate citizen and staff token namespaces enforce platform segmentation at the identity layer
- SSRF protections on JWKS and discovery endpoints meet OWASP API Security requirements
- Email verification enforcement supports Know Your Citizen requirements for service eligibility workflows
- Audit events are recorded for every authentication attempt, token issuance, and provider error
- Layered account-takeover protections require explicit provider linking, and per-request one-time value binding blocks cross-session assertion replay, supporting high-assurance protection of resident accounts
Last Reviewed: 2026-07-16 Last Updated: 2026-07-16