Architecture · Application identity
Cognito Day-2 Identity Architecture for WordPress
Treat Cognito as an identity subsystem, not just a login screen: browser authentication, federation, groups, token context and optional AWS credentials remain separate from WordPress content and sessions.
WordPress page → Gatey UI
↓ browser
Amazon Cognito User Pool
├→ social / SAML / OIDC providers
├→ MFA + profile flows
├→ groups / token context
└→ optional Identity Pool
↓
protected APIs / static access
Identity boundary
WordPress renders the experience; Cognito owns application identity
Gatey provides the frontend experience, while Cognito authenticates users and supplies identity artifacts that other services can validate. This keeps login usable on dynamic or static WordPress without making the WordPress users table the application identity source.
Visitor browser
→ Gatey authenticator
→ Cognito User Pool
├→ sign-in / sign-up / MFA / profile
├→ SAML / OIDC / social federation
└→ group and token context
├→ JWT-authorized APIs
├→ optional IAM credentials
└→ protected-static signer decision
Authorization boundary Successful authentication does not grant universal application access. Protected APIs and static resources must enforce their own scopes, IAM or signed-access policies using the identity context Cognito provides.
What the template provisions
The identity stack includes more than a User Pool. This inventory shows the browser client, federation/domain options, lifecycle triggers, optional AWS credentials and outputs that form the application identity boundary.
| Building block | Why it exists | Key design choice | Operational note |
|---|---|---|---|
| User Pool + App Client | Primary user directory and OAuth client for browser-based WordPress login | No client secret; code/SRP-friendly public-client setup | Can be created by the stack or attached to an existing pool depending on template mode. |
| Optional custom domain | Branded sign-in and OAuth callback flows | ACM certificate and optional Route53 alias when the hosted zone is available | DNS and certificate ownership must be explicit before production rollout. |
| Identity Pool | Exchange authenticated Cognito users for AWS credentials when IAM-signed APIs are needed | Separate AuthenticatedRole from RegisteredRole | Useful for IAM-protected API Gateway calls from static frontends. |
| Custom Email Sender | Replace plain Cognito emails with HTML templates and branded flows | Templates live in S3; SES is used when configured, otherwise Cognito delivery can remain the fallback | Treat templates as versioned product assets, not inline console text. |
| Pre Sign-Up trigger | Validate sign-up quality before users enter the pool | Optional reCAPTCHA, trusted-domain behavior and external IdP linking by email | Failures should be clear enough for frontend UX and logged enough for debugging. |
| Pre Token Generation trigger | Project group membership into access-token scopes | Add scopes such as sc.group.registered or sc.group.admin | Makes API Gateway scope checks more declarative. |
| Post Confirmation trigger | Move confirmed users into the Registered group | Only handles real sign-up confirmations, not every confirmation event | Decouples “authenticated” from “registered enough to call APIs”. |
| Outputs | Let other stacks and plugins consume identity artifacts | Expose pool IDs, client IDs, domain, roles, groups and function ARNs | Outputs are the contract between this stack and the rest of the platform. |
Token and authorization model
Cognito exposes several identity artifacts, but each has a different role. This table separates browser authentication, groups, scopes, temporary AWS credentials and service-side authorization.
| Layer | Artifact | What it proves | What it should not do |
|---|---|---|---|
| Gatey/browser | Cognito tokens and local auth state | The user completed the configured Cognito flow | Store secrets on the WordPress server or proxy passwords through PHP. |
| User Pool groups | registered, admin or project-specific groups | The user belongs to a business role | Become the only runtime enforcement point. |
| Access-token scopes | sc.group.<group> | The token carries API-readable role context | Replace backend authorization where resource ownership matters. |
| Identity Pool role | AuthenticatedRole or RegisteredRole | The browser can obtain temporary AWS credentials for allowed actions | Grant broad account-level permissions. |
| API Gateway method | Cognito scope or IAM authorization | The route enforces identity at the service boundary | Rely on hidden buttons or CSS-only restrictions. |
Operational failure modes
Identity failures often look like generic login problems even when the cause is email delivery, federation, token scopes or DNS. This table maps user-visible symptoms to the operational boundary to inspect.
| Failure mode | User-visible symptom | Likely cause | Runbook direction |
|---|---|---|---|
| reCAPTCHA rejects sign-up | User cannot create an account | Wrong site key/secret, stale token, low score or action mismatch | Check clientMetadata token path, SSM secret, score threshold and Lambda logs. |
| Custom email not delivered | No confirmation/password email arrives | SES identity not verified, sandbox restriction, template read failure or FROM mismatch | Check SES identity, CloudWatch logs, S3 template key and fallback behavior. |
| Social login creates duplicate users | Same email appears under separate provider identities | External IdP linking disabled or failed | Review Pre Sign-Up logs and AdminLinkProviderForUser permissions. |
| API call denied after login | Frontend authenticates but protected API returns 401/403 | User not in Registered group, scopes missing, Identity Pool role not mapped or API authorizer misconfigured | Inspect token scopes, group membership, Post Confirmation logs and API Gateway authorizer settings. |
| Custom domain fails | Hosted UI or callback domain does not resolve | Certificate region/validation, Route53 zone mismatch or alias target issue | Validate ACM cert, DNS zone ownership and Cognito domain status. |
Implementation path
Build identity around the application boundary, not around a WordPress session
The useful day-2 work begins after the User Pool exists: federation, lifecycle behavior, authorization and repeatable configuration.
- Define who owns identity — Keep WordPress focused on content and presentation, and use Cognito when the same visitor identity must extend to static pages, APIs or other application surfaces.
- Configure the required login and federation paths — Enable the sign-in, sign-up, MFA, profile, social or SAML/OIDC providers the project actually needs through Cognito and Gatey.
- Map identity to runtime permissions — Use token claims, scopes, groups or optional IAM credentials so backend services can authorize actions independently of frontend visibility.
- Test lifecycle and failure states — Verify confirmation, password recovery, MFA, provider sign-in, changed group membership, token expiry and API denial paths separately from the page rendering flow.
When Cognito should own the application identity layer
Good fit
Identity must extend beyond WordPress itself
- The same users need login on a static frontend or on pages where WordPress PHP is not serving the request.
- Frontend identity must authorize APIs, protected resources or other application surfaces.
- The organization already has or expects social, SAML or OIDC federation requirements.
Keep WordPress-native auth
WordPress sessions may be simpler when
- Only wp-admin or ordinary dynamic WordPress pages require authenticated users.
- No external application, protected API or static frontend needs the same identity.
- Existing plugins depend directly on WordPress user/session behavior and there is no business reason to introduce a separate identity subsystem.
Problem guides
Identity decisions this architecture supports
When should Amazon Cognito replace WordPress as the application identity layer?
See Use Amazon Cognito Instead of WordPress as the Application Identity Layer. It frames the buyer decision: WordPress remains the CMS while Cognito owns visitor identity for the wider application.
How do I connect existing SAML or OIDC identity providers?
See Connect WordPress to Existing SAML and OIDC Identity Providers Without Building Separate Login Flows. Cognito acts as the federation hub while Gatey keeps one frontend login experience in WordPress.
How does this work on static WordPress?
See Add Login to Static WordPress Without Bringing PHP Sessions Back. Browser-side Cognito login can survive static publishing because authentication does not depend on a WordPress PHP session.
How are protected static files different from protected APIs?
Use Secure Static WordPress with CloudFront Signed Cookies for static delivery. APIs should independently validate JWT, IAM or another supported authorization mechanism.
Start with the identity decision
Use Cognito when visitor identity needs to outlive the WordPress request
Choose the application-identity guide for the core decision, or the SSO guide when federation with existing identity providers is the primary requirement.