WordPress authentication field notes
WordPress SSO with Amazon Cognito and Gatey | Social & Enterprise Login Guide
Amazon Cognito can act as one identity hub for social providers and an organization’s existing SAML or OIDC provider. Gatey brings that identity layer into WordPress through configurable sign-in, registration, MFA, and account experiences that can also keep working after a static export.
Before configuration
Three decisions shape the whole SSO design
Choose the identity hub
Keep social and enterprise providers behind one Cognito User Pool so applications consume a consistent set of users, attributes, groups, and tokens.
Use a public app client
A browser-based WordPress or static frontend cannot safely keep a client secret. Create the Cognito app client without one.
Define the authorization boundary
Cognito login can stop at browser sessions and JWTs, or continue through an Identity Pool when the frontend must obtain temporary AWS credentials.
Architecture
Why use Cognito as the identity hub?
A WordPress site may need low-friction social login for customers and enterprise SSO for employees, partners, or clients. Configuring every provider directly in WordPress creates several separate callback flows and makes later changes harder to coordinate.
Cognito places those providers behind one User Pool. Gatey then renders the WordPress-facing experience while authentication, MFA, user attributes, groups, and token issuance remain in Cognito.
- Use one User Pool as the application identity directory.
- Add each external provider to Cognito rather than rebuilding the WordPress login flow.
- Let Gatey present the resulting sign-in options inside WordPress.
This separation is especially useful when the same identity path must work on both a dynamic WordPress installation and a statically published frontend.
Cognito foundation
How should the User Pool and App Client be configured?
Start with a Cognito User Pool and a browser-oriented app client. The app client should not generate a secret. Enable the authorization code grant and register the exact callback and sign-out URLs used by the site.
Request only the scopes the frontend needs. A common baseline is openid, email, and profile. Add aws.cognito.signin.user.admin only when the account experience requires Cognito user-profile operations covered by that scope.
- Match callback URLs exactly, including protocol, hostname, path, and trailing slash.
- Enable every identity provider the app client is expected to offer.
- Create a Cognito domain for the managed authorization endpoints.
Test the Cognito authorization flow before styling the WordPress experience. A provider that fails in Cognito will also fail when launched through Gatey.
Identity providers
How do social and enterprise providers fit?
Cognito can federate common social providers such as Google, Facebook, Apple, and Amazon. Enterprise connections normally arrive through OIDC or SAML, allowing an existing corporate identity provider to remain the source of employee or partner identities.
Attribute mapping is the part most likely to cause subtle problems. Map email, given name, family name, and a stable provider identifier where available. Confirm which attributes are required by the User Pool before enabling the provider for production users.
- Test each provider independently through the Cognito-hosted authorization path.
- Inspect the returned claims and mapped attributes instead of assuming provider defaults match.
- Keep requested provider scopes and Cognito attributes as small as the application permits.
Provider display names are presentation choices in Gatey; the actual provider identifiers and trust configuration still belong to Cognito.
Social identity provider settings
| Provider | Credentials | Scopes | Typical mapping |
|---|---|---|---|
| OAuth Client ID + Secret | openid email profile |
email → email, family_name → family_name, given_name → given_name, sub → username |
|
| App ID + Secret | email public_profile |
email → email, last_name → family_name, first_name → given_name, id → username |
|
| Apple | Services ID, Key, Team ID | openid email name |
Map email; consider Apple private-relay emails in your UX. |
| Amazon | Login with Amazon Security Profile | profile (+ email if desired) |
email → email, name → given/family where available |
WordPress configuration
How is Cognito connected to Gatey?
In WordPress administration, open the SmartCloud settings area and configure Gatey with the AWS region, User Pool ID, App Client ID, Cognito domain, OAuth scopes, login mechanisms, and sign-up attributes used by the site.
Then add the Gatey Authenticator block to the sign-in or account page. Built-in social providers can be enabled in the block settings, while custom SAML and OIDC providers can be presented with the labels required by the project.
- Create and test a dedicated sign-in or account page first.
- Verify registration, confirmation, password recovery, MFA, and profile flows separately.
- Add custom provider buttons only after their Cognito identifiers are confirmed.
Gatey controls the WordPress presentation layer, but it does not move provider secrets, passwords, or the Cognito user directory into WordPress.
Admin access
Map an administrator group before replacing wp-login.php
Do not redirect or replace the native WordPress login until at least one tested Cognito identity maps to the required WordPress administrator role. Verify the full flow in a separate browser session and retain a recovery path so a provider or mapping mistake cannot lock every administrator out.
AWS API access
When is an Identity Pool and IAM role needed?
A User Pool is enough when the site only needs login, account screens, and JWT-authorized APIs. An Identity Pool becomes relevant when authenticated browser users must receive temporary AWS credentials and sign requests with AWS IAM.
The associated IAM roles should grant only the actions and resources required by that frontend. Group or claim-based authorization can still narrow application behavior, but it should not compensate for an overly broad IAM policy.
- Use JWT authorization when the API can validate Cognito tokens directly.
- Add an Identity Pool only for AWS credential and IAM-signing use cases.
- Scope execute-api and other permissions to the intended APIs and actions.
Keep identity authentication and resource authorization as separate design decisions. A successful sign-in should not automatically imply broad access to AWS services.
Pre-launch check
What should be tested before publishing the SSO flow?
Run every provider through the same sequence a real user will follow: start from WordPress, authenticate with the provider, return to the registered callback, inspect the resulting account data, sign out, and repeat with an existing account.
Also test failure paths. Redirect mismatches, missing openid scope, incomplete email mapping, an app client secret, and premature wp-login replacement are common causes of otherwise confusing SSO failures.
- Confirm exact callback and sign-out URLs in Cognito and WordPress.
- Confirm required claims, mapped attributes, groups, and WordPress roles.
- Test an administrator recovery path before changing the default login.
Once the identity path is reliable, styling and provider labels can be adjusted without changing the underlying trust relationships.
Configure the identity path first
Test Cognito before styling the WordPress login
Build and verify the User Pool, public app client, provider mappings, callbacks, and role boundaries first. Then use Gatey to place the resulting sign-in and account journey where WordPress users expect it.