{"id":"citizen-authentication","slug":"citizen-authentication","title":"Citizen Authentication: MyGovID and OIDC Access for Public Services","description":"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 ident","category":"modules","tags":["modules","compliance","geospatial"],"lastModified":"2026-04-14","source_ref":"content/modules/citizen-authentication.md","url":"/developers/citizen-authentication","htmlPath":"/developers/citizen-authentication","jsonPath":"/api/docs/modules/citizen-authentication","markdownPath":"/api/docs/modules/citizen-authentication?format=markdown","checksum":"24936147b05203e52dc02cf1cc03da4b10eef651d310f7e93b7d562ec2a19ae1","headings":[{"id":"overview","text":"Overview","level":2},{"id":"key-features","text":"Key Features","level":2},{"id":"use-cases","text":"Use Cases","level":2},{"id":"government-digital-services-access","text":"Government Digital Services Access","level":3},{"id":"representative-portal-sign-in","text":"Representative Portal Sign-In","level":3},{"id":"multi-portal-deployments","text":"Multi-Portal Deployments","level":3},{"id":"social-identity-fallback","text":"Social Identity Fallback","level":3},{"id":"custom-enterprise-oidc","text":"Custom Enterprise OIDC","level":3},{"id":"how-it-works","text":"How It Works","level":2},{"id":"integration","text":"Integration","level":2},{"id":"compliance","text":"Compliance","level":2}],"markdown":"# Citizen Authentication: MyGovID and OIDC Access for Public Services\n\n## Overview\n\nThe 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.\n\nThe module is designed for high-assurance public-sector deployments where identity verification, privacy, and cross-provider interoperability are non-negotiable requirements.\n\n## Key Features\n\n- **PKCE OAuth 2.0 Flow**: Proof Key for Code Exchange ensures authorization codes cannot be intercepted or replayed, meeting the security bar required for government digital services without requiring client secrets on public devices\n- **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\n- **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\n- **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\n- **Email Verification Enforcement**: Requires email_verified claims by default; configurable fallback policy allows tenants to accept unverified email for lower-assurance use cases\n- **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\n- **Tenant-Scoped Session Tokens**: Citizen access tokens carry both citizen_id and organisation_id claims and are issued in a separate cookie namespace from staff tokens, ensuring citizens can never traverse staff-only surfaces\n- **Separate Identity Store**: Citizen accounts are maintained in a dedicated database table distinct from staff user records, preventing accidental cross-table privilege escalation\n\n## Use Cases\n\n### Government Digital Services Access\nCitizens 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.\n\n### Representative Portal Sign-In\nElected 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.\n\n### Multi-Portal Deployments\nA 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.\n\n### Social Identity Fallback\nOrganisations 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.\n\n### Custom Enterprise OIDC\nRegional 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.\n\n## How It Works\n\n```mermaid\nsequenceDiagram\n    participant C as Citizen Browser\n    participant P as Public Portal\n    participant A as Auth Service\n    participant I as Identity Provider (MyGovID / Google / Custom)\n\n    C->>P: Visit protected portal page\n    P->>C: Redirect to /citizen/auth/login\n    C->>A: GET /citizen/auth/login?provider=mygov\n    A->>A: Generate PKCE verifier + challenge (SHA-256)\n    A->>C: Redirect to IdP authorise endpoint with code_challenge\n    C->>I: Follow redirect, citizen authenticates\n    I->>C: Redirect back with authorisation code\n    C->>A: GET /citizen/auth/callback?code=...\n    A->>I: POST token endpoint, exchange code + PKCE verifier\n    I->>A: ID token + access token\n    A->>A: Validate JWKS signature, normalise claims\n    A->>A: Create or update citizen_accounts record\n    A->>C: Set citizen_access_token cookie (24h), redirect to portal\n    C->>P: Access portal with scoped session\n```\n\n## Integration\n\nCitizen 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_access_token is verified by downstream portal workers using the auth service's token introspection endpoint. Provider configuration (client ID, 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.\n\n## Compliance\n\n- PKCE (RFC 7636) compliance prevents authorization code interception on public and mobile clients\n- Separate citizen and staff token namespaces enforce platform segmentation at the identity layer\n- SSRF protections on JWKS and discovery endpoints meet OWASP API Security requirements\n- Email verification enforcement supports Know Your Citizen requirements for service eligibility workflows\n- Audit events are recorded for every authentication attempt, token issuance, and provider error\n\n**Last Reviewed:** 2026-04-14\n**Last Updated:** 2026-04-14\n"}