Citizen Services Portal Pack

We built this pack so you don't have to reverse-engineer OIDC flows, map legacy SOAP headers to modern JWTs, or manually audit every component for WCAG 2.1 AA compliance. Government portals sit at the intersection of three hard problems: strict accessibility mandates, legacy backend integration, and modern identity standards. Most teams treat these as separate tasks, which leads to brittle adapters, failed audits, and delayed launches. This skill pack gives you the architecture, the code, and the validation tools to solve all three simultaneously.

The Trap of Modernizing Legacy Government Portals

You are tasked with building a citizen-facing portal. The requirements are non-negotiable: it must support OIDC authentication, it must integrate with a legacy SOAP or REST backend that doesn't understand modern auth tokens, and it must pass WCAG 2.1 AA accessibility standards.

The problem isn't just technical complexity; it's the mismatch between modern frontend expectations and legacy backend reality. You spin up a React or Vue frontend. You configure an Identity Provider (IdP) like Keycloak. You get the OIDC tokens. Then you hit the wall: your backend is a 15-year-old SOAP service that expects Basic Auth or a specific header format. It doesn't accept JWTs. You end up writing a fragile middleware layer that decodes tokens, extracts claims, and reconstructs legacy headers. This adapter becomes a single point of failure. If the token refresh logic drifts, the whole portal breaks.

Then there's accessibility. WCAG 2.1 AA isn't a checkbox you tick at the end of a sprint. It's a structural requirement. Every form input needs proper labeling. Every color contrast must meet 4.5:1 ratios. Keyboard navigation must work flawlessly. Most engineering teams build the functionality first, then try to retrofit accessibility. That's when the rework starts. You end up rewriting components, adding ARIA attributes manually, and fixing contrast issues that should have been caught in design review.

If you're also building a Permit and Licensing Workflow Pack, you know how quickly these requirements compound. You need the same OIDC flow, the same legacy adapter, and the same accessibility rigor. Without a standardized approach, you're reinventing the wheel for every portal.

The Cost of Missing the 2026 DOJ Deadline

Ignoring these requirements isn't just a technical debt problem; it's a legal and operational risk. The Department of Justice has made it clear: government websites must comply with WCAG 2.1 Level AA standards by April 2026 ^[6]. This isn't a suggestion. It's a mandate under Title II of the ADA. If your portal doesn't comply, you're looking at potential lawsuits, fines, and forced remediation efforts.

The cost of non-compliance is steep. When an audit catches 40+ accessibility violations right before launch, you don't just delay the project. You lose citizen trust. You burn engineering hours fixing issues that could have been prevented. You risk public backlash. And if you're already behind schedule, the pressure to cut corners increases, which only makes the final audit worse.

The Web Content Accessibility Guidelines (WCAG) 2.1 cover a wide range of recommendations for making web content more accessible ^[1]. But translating those guidelines into code is where most teams struggle. You need a checklist that maps directly to DOJ requirements. You need automated tools that catch violations before they hit production. You need a workflow that enforces compliance at every stage. Without that, you're flying blind. And when the deadline approaches, you'll be scrambling.

If you're working on a Patient Portal Design Pack, you know the stakes even higher. Patient data is sensitive, and accessibility is a civil right. Missing the deadline isn't an option. The same applies to a Benefits Administration System Pack. Citizens rely on these services. If they can't access them due to poor design or broken auth, the government fails its mission.

How a Permit Portal Almost Failed Its Accessibility Audit

Imagine a mid-sized county building a citizen permit portal. The frontend is React. The backend is a legacy SOAP service that handles permit applications. The team decides to use Keycloak for OIDC authentication. They scaffold the IdP, configure the realm, and get the tokens working. They build the UI. They add forms for permit applications. They test the functionality. Everything works.

Then comes the accessibility audit. The auditor runs automated tools and performs manual testing. They find 40+ violations. Form labels are missing. Color contrast is too low. Keyboard navigation is broken on the permit status tracker. The audit fails. The launch is delayed by three months. The team has to rewrite components, add ARIA attributes, fix contrast issues, and retest. The engineering lead spends weeks firefighting. The project manager is stressed. The mayor is unhappy.

This scenario is common. The team had the OIDC flow working. They had the legacy adapter wired up. But they didn't have a structured approach to accessibility. They didn't have a checklist mapped to DOJ requirements. They didn't have automated tools to catch violations early. If they had used a standardized pack, they would have scaffolded Keycloak with the right config. They would have used a TypeScript adapter to inject OIDC tokens into the SOAP headers. They would have run an automated WCAG audit during development. They would have caught the violations before the auditor did. They would have launched on time.

Compare this to a team building a Government Procurement System (SAM.gov) Pack. They use a structured workflow. They define requirements upfront. They implement auth and accessibility from day one. They don't face the same rework. The difference isn't skill. It's process. And process is what this pack provides.

What Changes When OIDC and WCAG Are Built In

Once you install this skill pack, the workflow changes. You stop guessing. You start shipping. Here's what the after-state looks like:

OIDC Auth is Production-Ready Out of the Box

You get a keycloak-realm.json template that implements OIDC auth, identity brokering, essential claim enforcement, and strict audience validation. You don't have to figure out the JSON structure. You don't have to debug the flow. You scaffold the realm, configure the client, and you're done. The tokens are issued correctly. The claims are enforced. The integration is secure.

Legacy Integration is Handled by a TypeScript Adapter

You get a legacy-adapter.ts file that handles token refresh and secure header forwarding. You inject OIDC access tokens into legacy SOAP/REST endpoints without rewriting the backend. The adapter decodes the JWT, extracts the claims, and reconstructs the legacy headers. It handles refresh tokens automatically. It's a clean, maintainable layer that bridges modern auth and legacy systems.

WCAG 2.1 AA Compliance is Automated

You get a wcag-compliance-checklist.md that maps DOJ deadlines, S.508 requirements, and testing workflows. You get a run-wcag-audit.sh script that runs axe-core against your target URL and generates an HTML report. If violations are detected, the script exits non-zero. You get a tests/axe-integration.test.js suite that verifies React components meet WCAG 2.1 AA. You catch violations during development, not after launch. The audit is part of the build pipeline.

Validation is Enforced

You get a validate-keycloak-config.sh script that parses the realm JSON and enforces required fields. If the schema fails, the build fails. You don't deploy broken configs. You don't ship non-compliant code. You ship secure, accessible portals.

If you're also building an Internal Developer Platform, you'll appreciate the consistency. The same OIDC patterns, the same validation logic, the same accessibility standards. You don't have to reinvent the wheel for every project. You install the pack, you follow the workflow, you ship.

What's in the Citizen Services Portal Pack

This pack includes everything you need to build secure, accessible citizen portals. Here's the file manifest:

• skill.md — Orchestrator skill that defines the 360° workflow, references all templates, references, scripts, validators, and examples, and instructs the agent on secure citizen portal architecture.
• templates/keycloak-realm.json — Production-grade Keycloak realm configuration implementing OIDC auth, kc_idp_hint identity brokering, essential claim enforcement, and strict audience validation for JWT client assertions.
• templates/legacy-adapter.ts — TypeScript adapter pattern for injecting OIDC access tokens into legacy SOAP/REST government endpoints, handling token refresh and secure header forwarding.
• templates/wcag-compliance-checklist.md — Structured WCAG 2.1 AA compliance checklist tailored for citizen portals, mapping DOJ deadlines, S.508 requirements, and automated/manual testing workflows.
• references/oidc-keycloak-patterns.md — Embedded canonical Keycloak documentation covering OIDC authorization flow, kc_idp_hint, account linking, essential claims, audience validation, and OAuth2 IDP configuration.
• references/wcag-2-1-aa-standards.md — Embedded canonical WCAG 2.1 AA and DOJ Title II requirements, including compliance deadlines (2026/2027), remediation strategies, and accessibility testing methodologies.
• scripts/run-wcag-audit.sh — Executable shell script that runs axe-core via Node.js against a target URL, generates an HTML report, and exits non-zero if accessibility violations are detected.
• scripts/scaffold-keycloak.sh — Executable shell script that uses kcadm.sh to programmatically create a Keycloak realm, OIDC client, and identity provider instances based on the template.
• validators/validate-keycloak-config.sh — Validator script that parses keycloak-realm.json using jq, enforces required fields (realm, clients, identityProviders, essentialClaims), and exits 1 on schema failure.
• tests/axe-integration.test.js — Jest test suite using axe-core to verify React citizen portal components meet WCAG 2.1 AA, handling async rendering and throwing on violations.
• examples/worked-example-portal.md — Step-by-step worked example demonstrating OIDC integration, legacy adapter wiring, WCAG audit execution, and compliance validation for a municipal service portal.

Stop Guessing. Start Shipping Compliant Portals.

You don't have to reverse-engineer OIDC flows. You don't have to manually audit every component. You don't have to hope the legacy adapter works. Upgrade to Pro to install the Citizen Services Portal Pack. Scaffold Keycloak. Wire the adapter. Run the audit. Ship.