### Introduction

Single Sign-On has become a baseline expectation for both end-users and enterprises. Visitors don’t want to create yet another username and password — they expect to log in with Google or Apple in one click. At the same time, companies require secure integrations with their existing identity providers like Azure AD or Okta.

For WordPress, this balance is tricky: the native login system was never designed for modern OAuth/OIDC or SAML flows, and static exports break the default authentication completely.

By combining **Amazon Cognito** (as the identity hub) with **Gatey** (as the WordPress integration layer), you can offer seamless social logins for individuals and enterprise SSO for organizations — all while keeping your site secure, scalable, and even compatible with static hosting.

**What you’ll learn**

-   How to configure Cognito _User Pools_, _App Clients_, and the **Hosted UI** (domain, callbacks, scopes).
-   How to connect Social IdPs (Google, Facebook, Apple, Amazon) and Enterprise IdPs (OIDC/SAML).
-   How to map attributes for clean WordPress profiles and role mapping.
-   How to wire everything into WordPress with **Gatey** (User Pools, General, Social & Custom Providers).
-   (Optional) How to enable IAM so Cognito users can call AWS-hosted APIs from the browser.

**Pre-requisites**

-   **Gatey plugin** available in WordPress.  
    • If not installed: 
    ```
    Plugins → Add New → Gatey → Install
    ```
     and activate.  
    • If already installed: continue with 
    ```
    WP Admin → Gatey → Settings
    ```
     and complete the configuration below.
-   **AWS Cognito access** to a User Pool you can use (existing or new) and permission to edit App Clients, Identity Providers, and Domain settings.

[Try Gatey Free →](https://wordpress.org/plugins/gatey/)

[Read the Docs](https://wpsuite.io/docs/)

### Why SSO for WordPress

-   **Frictionless onboarding** — one-click sign-up with existing Google/Apple accounts.
-   **Enterprise compliance** — hook up Azure AD, Okta, Ping, Auth0 via SAML or OIDC.
-   **Centralized identity** — Cognito holds users and policies (incl. MFA/conditional access).
-   **Static-friendly** — Gatey talks to Cognito in the browser, no PHP callback, works after static export.

### Step-by-Step: Setup Guide

#### Step 1: Choose or create a Cognito User Pool & App Client

You can **use an existing User Pool** or create a new one. In both cases you need an **App client** with the **Hosted UI** enabled and the right OAuth settings.

-   **If you already have a User Pool**: verify that it has an App Client for this website. If the existing client _uses a client secret_, **create a new client without a secret** for front-end only (static-friendly) flows.
-   **If you don’t have one yet**: create a User Pool, then add an App Client.

#### Important – No client secret!

Pick an App Client type that does not issue a client secret (so the flow works without a backend and remains static-export friendly). In the Cognito wizard, choose the **SPA** or **Mobile** application template. If your current client has a secret, create a parallel client without one and use that in WordPress.

[![Cognito App client settings showing Hosted UI callbacks and identity providers.](https://wpsuite.io/wp-content/uploads/2025/09/cognito-appclient.png "Amazon Cognito App Client – Hosted UI settings")](https://wpsuite.io/wp-content/uploads/2025/09/cognito-appclient.png)

Configure callback URLs, sign-out URLs, and identity providers for your Cognito App Client.

-   **OAuth grant**: Authorization code grant.
-   **Callback URLs**: your WP route (e.g. 
    ```
    https://<site>/sign-in
    ```
    ).
-   **Sign-out URLs**: same hostname and path family.
-   **Scopes**: 
    ```
    openid
    ```
     (required), plus 
    ```
    email
    ```
    , 
    ```
    profile
    ```
    . If you plan to call AWS APIs later, also include 
    ```
    aws.cognito.signin.user.admin
    ```
    .

**Tip:** Keep a notepad of your _User pool ID_, _App client ID_, _Region_, and _Hosted UI domain_ — you’ll paste them into Gatey.

Docs: [App client & IdP settings](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-app-idp-settings.html)

#### Step 2: Assign (or verify) a Hosted UI domain

Every WordPress site that uses the Hosted UI needs a domain on the pool. If your pool already has one, **reuse it**. Otherwise, add a new AWS-managed subdomain or a custom domain via CloudFront + ACM.

[![Cognito custom domain setup with CloudFront alias and ACM certificate.](https://wpsuite.io/wp-content/uploads/2025/09/cognito-domain.png "Cognito Hosted UI custom domain")](https://wpsuite.io/wp-content/uploads/2025/09/cognito-domain.png)

Example of using a custom subdomain for Cognito’s Hosted UI.

Docs: [Add a domain to your user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-assign-domain.html)

#### Step 3: Add or enable Social identity providers

In _Authentication → Social and external providers_ either **enable existing providers** on your App Client or **add the missing ones** by supplying their credentials and scopes.

 Provider | Credentials | Scopes | Typical mapping |
| --- | --- | --- | --- |
 **Google** | OAuth Client ID + Secret | 
```
openid email profile
```
 | 
```
email → email
```
, 
```
family_name → family_name
```
, 
```
given_name → given_name
```
, 
```
sub → username
```
 |
 **Facebook** | 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 |

[![Cognito Google identity provider with attribute mapping.](https://wpsuite.io/wp-content/uploads/2025/09/cognito-google.png "Cognito – Google IdP configuration")](https://wpsuite.io/wp-content/uploads/2025/09/cognito-google.png)

Attribute mapping between Google profile fields and Cognito user attributes.

[![Cognito Facebook identity provider with attribute mapping.](https://wpsuite.io/wp-content/uploads/2025/09/cognito-facebook.png "Cognito – Facebook IdP configuration")](https://wpsuite.io/wp-content/uploads/2025/09/cognito-facebook.png)

Attribute mapping for Facebook user profile data in Cognito.

**Tip:** After (re)enabling a provider, test via Hosted UI and inspect ID token claims. Confirm 
```
email
```
, 
```
given_name
```
, 
```
family_name
```
 before moving to WordPress.

Docs: [Google](https://docs.aws.amazon.com/cognito/latest/developerguide/google.html#set-up-google-1.javascript) • [Facebook](https://docs.aws.amazon.com/cognito/latest/developerguide/facebook.html) • [Apple](https://docs.aws.amazon.com/cognito/latest/developerguide/apple.html) • [Login with Amazon](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon.html)

#### Step 4: Connect an Enterprise IdP (OIDC / SAML) or reuse your existing one

For B2B logins connect (or verify) the customer’s IdP (Okta, Azure AD, Ping, Auth0…). With OIDC set Issuer, Client ID/Secret, scopes; with SAML upload 
```
metadata.xml
```
. Ensure attribute mapping for 
```
email
```
, 
```
given_name
```
, 
```
family_name
```
 and a stable identifier (
```
sub
```
 or NameID).

[![Cognito OIDC provider configuration with Auth0.](https://wpsuite.io/wp-content/uploads/2025/09/cognito-auth0.png "Cognito – OIDC IdP (Auth0) setup")](https://wpsuite.io/wp-content/uploads/2025/09/cognito-auth0.png)

Example OIDC integration: Issuer, token endpoints, and attribute mapping.

Docs: [OIDC](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-oidc-idp.html) • [SAML](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-saml-idp.html)

##### Quick Setup Links — Top IdPs

Most used providers with direct links to their OAuth2 / SAML setup docs.

 Provider | Console | Docs |
| --- | --- | --- |
 **Login with Amazon** | Login with Amazon → Security Profile → Web Settings | [Login with Amazon](https://developer.amazon.com/docs/login-with-amazon/documentation-overview.html) |
 **Google** | Google Cloud Console → APIs & Services → Credentials | [OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect) |
 **Apple** | Apple Developer → Certificates, Identifiers & Profiles → Identifiers | [Sign in with Apple](https://developer.apple.com/documentation/signinwithapple) |
 **Facebook (Meta)** | Meta for Developers → App Dashboard → Facebook Login | [Facebook Login (Web)](https://developers.facebook.com/docs/facebook-login/web/) |
 **Microsoft Entra ID** | Azure Portal → Entra ID → App registrations | [Register an application (OIDC)](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) / [SAML SSO](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso) |
 **Okta** | Okta Admin → Applications → Create App Integration | [OIDC](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) / [SAML](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) |
 **Auth0** | Auth0 Dashboard → Applications | [Social / OIDC](https://auth0.com/docs/authenticate/identity-providers/social-identity-providers) / [SAML](https://auth0.com/docs/authenticate/protocols/saml) |
 **Keycloak** | Keycloak Admin → Clients / Identity Providers | [OIDC clients](https://www.keycloak.org/docs/latest/server_admin/#openid-connect) / [SAML clients](https://www.keycloak.org/docs/latest/server_admin/#saml-v2-0) |

#### More OIDC / SAML Identity Providers

Additional enterprise & developer IdPs you can connect via OIDC or SAML. (The Top 8 above are not repeated here.)

Enterprise & Workforce

 Provider | Console | OIDC / OAuth2 docs | SAML docs |
| --- | --- | --- | --- |
 **Azure AD B2C** | Azure Portal → Azure AD B2C → App registrations | [Register apps](https://learn.microsoft.com/en-us/azure/active-directory-b2c/register-apps) | [SAML app (B2C)](https://learn.microsoft.com/en-us/azure/active-directory-b2c/register-apps#saml-application) |
 **OneLogin** | OneLogin Admin → Applications | [OpenID Connect](https://developers.onelogin.com/openid-connect) | [SAML](https://developers.onelogin.com/saml) |
 **Ping Identity** | PingOne / PingFederate | [PingOne OIDC](https://docs.pingidentity.com/pingone/integrations/p1_add_idp_oidc.html) | [PingFederate SAML](https://docs.pingidentity.com/solution-guides/workforce_use_cases/htg_config_saml_app.html) |
 **GitLab (as IdP)** | GitLab Admin → Applications → OIDC Provider | [OIDC provider](https://docs.gitlab.com/integration/openid_connect_provider/) | — |
 **Salesforce** | Setup → App Manager → New Connected App | [Connected App (OAuth)](https://help.salesforce.com/s/articleView?id=platform.ev_relay_create_connected_app.htm&type=5) | [SAML SSO](https://help.salesforce.com/s/articleView?id=sf.sso_saml_about.htm&type=5) |
 **IBM Security Verify** | Verify Admin → Applications | [OpenID Connect](https://www.ibm.com/docs/en/security-verify?topic=applications-openid-connect) | [SAML (Docs hub)](https://www.ibm.com/docs/en/security-verify) |
 **Oracle Identity Cloud** | Oracle Cloud → Identity → Applications | [OIDC (Auth Code)](https://docs.oracle.com/en/cloud/paas/identity-cloud/idcsa/openidconnectauthcode.html) | [SAML SSO](https://docs.oracle.com/en/solutions/configure-sso-between-cust-app-and-identity-cloud/) |
 **JumpCloud** | Admin Portal → SSO Applications | [OIDC SSO](https://jumpcloud.com/support/sso-with-oidc) | [SAML SSO](https://jumpcloud.com/support/get-started-applications-saml-sso) |
 **ADFS** | AD FS Management → Relying Party Trusts | — | [Create relying party trust](https://learn.microsoft.com/en-us/power-pages/security/authentication/saml2-settings#create-an-ad-fs-relying-party-trust) |
 **Google Workspace (as SAML IdP)** | Admin Console → Apps → Web & mobile apps | — | [Custom SAML app](https://support.google.com/a/answer/6087519) |

Developer & Community

 Provider | Console | OIDC / OAuth2 docs | SAML docs |
| --- | --- | --- | --- |
 **GitHub** | Developer settings → OAuth Apps | [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) | — |
 **LinkedIn** | Developer Portal → Your App → Auth | [OAuth 2.0](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authentication) | — |
 **X (Twitter)** | X Developer Portal → App → User auth | [OAuth 2.0 (Auth Code)](https://docs.x.com/resources/fundamentals/authentication/oauth-2-0/authorization-code) | — |
 **Reddit** | reddit.com/prefs/apps | [OAuth 2.0](https://www.reddit.com/dev/api/oauth/) | — |
 **Spotify** | Developer Dashboard → Your Apps | [Authorization Code flow](https://developer.spotify.com/documentation/web-api/tutorials/code-flow) | — |
 **Slack** | Slack API → Your App → Authentication | [Sign in with Slack](https://docs.slack.dev/authentication/sign-in-with-slack/) | — |

##### Tip — scopes & redirects

Keep scopes minimal and consistent across Cognito and the IdP:
```
openid email profile
```
Redirect URIs must match exactly (scheme, host, path).

#### Step 5: Wire Cognito to WordPress using Gatey

At this point you need to configure WordPress with Gatey. **If Gatey is not yet installed**: install it from the WP plugin repository (_Plugins → Add New → Gatey → Install_) and activate. **If Gatey is already installed**: go to 
```
WP Admin → Gatey → Settings
```
 and complete the configuration below.

#### 5.1 Paste your pool settings

In 
```
Gatey → Settings → User Pools
```
, fill in:-   **User Pool ID**, **App Client ID**, **Region**
-   **OAuth Domain** (Hosted UI domain)
-   **OAuth scopes** (e.g. 
    ```
    openid email profile
    ```
     and optionally 
    ```
    aws.cognito.signin.user.admin
    ```
    )
-   (Optional) **Identity Pool ID** for IAM-based API calls

[![Gatey plugin User Pools configuration in WordPress.](https://wpsuite.io/wp-content/uploads/2025/09/gatey-userpool.png "Gatey – User Pools settings")](https://wpsuite.io/wp-content/uploads/2025/09/gatey-userpool.png)

Configure Pool ID, App Client ID, region, and OAuth scopes in Gatey.

#### 5.2 Configure general login options

In 
```
Gatey → Settings → General
```
, set:-   **Login mechanisms**: Username / Email / Phone — match your Cognito pool.
-   **Sign-up attributes**: e.g. 
    ```
    given_name
    ```
    , 
    ```
    family_name
    ```
    , 
    ```
    email
    ```
    .
-   **Sign In Page** (usually 
    ```
    /sign-in
    ```
    ).
-   Enable built-in **Social Providers** for visible buttons.

[![Gatey plugin General settings in WordPress.](https://wpsuite.io/wp-content/uploads/2025/09/gatey-general.png "Gatey – General login settings")](https://wpsuite.io/wp-content/uploads/2025/09/gatey-general.png)

Set login mechanisms, sign-up attributes, and sign-in page in Gatey.

#### 5.3 Add Custom Providers (enterprise buttons)

If you configured an enterprise IdP (e.g. Auth0) in Cognito, mirror it under 
```
Gatey → Settings → Custom Providers
```
. Give it a provider name, a public title, and an icon (base64 SVG is supported). Gatey will render the button on your sign-in screen.

[![Gatey plugin Custom Providers settings with Auth0 entry.](https://wpsuite.io/wp-content/uploads/2025/09/gatey-custom-providers.png "Gatey – Custom Providers setup")](https://wpsuite.io/wp-content/uploads/2025/09/gatey-custom-providers.png)

Add enterprise IdPs like Auth0 to the WordPress login screen.

**Tip:** Whether you just installed Gatey or it was already active, the final step is the same: finish filling these settings so WordPress can talk to Cognito.

#### Step 6: (Optional) Replace 
```
/wp-login.php
```
 with Cognito

Open 
```
Gatey → Settings → WordPress Login
```
 to replace the native login screen and map Cognito groups to WordPress roles.

**Don’t lock yourself out:** create a Cognito group for admins, add yourself to it, then map that group → _Administrator_ before enabling the replacement.

#### Step 7: (Optional) Call AWS APIs with IAM credentials

If your site should call AWS-hosted APIs (e.g. the Static WordPress Site Guardian that issues/revokes CloudFront signed cookies):

1.  Include 
    ```
    aws.cognito.signin.user.admin
    ```
     among your OAuth scopes (in Gatey → User Pools too).
2.  Create an **Identity Pool** with an _authenticated role_ that can call your APIs.

**Example IAM policy (authenticated role)**

```
{
  "Version": "2012-10-17",
  "Statement": \[
    {
      "Effect": "Allow",
      "Action": \["cognito-identity:GetCredentialsForIdentity"\],
      "Resource": \["\*"\]
    },
    {
      "Action": \["execute-api:Invoke"\],
      "Resource": \["arn:aws:execute-api:\*:637423296378:\*"\],
      "Effect": "Allow"
    }
  \]
}
```

**Trusted relationships (assume via Cognito Identity)**

```
{
  "Version": "2012-10-17",
  "Statement": \[
    {
      "Effect": "Allow",
      "Principal": { "Federated": "cognito-identity.amazonaws.com" },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "cognito-identity.amazonaws.com:aud": "us-west-1:ed28c718-ef84-4600-af7c-520ebaec46ba"
        },
        "ForAnyValue:StringLike": {
          "cognito-identity.amazonaws.com:amr": "authenticated"
        }
      }
    }
  \]
}
```

### Pro Tips & Common Mistakes

#### Pro Tips

-   Test every IdP through the Hosted UI and inspect the ID token claims before touching WP.
-   Plan for IAM early: add 
    ```
    aws.cognito.signin.user.admin
    ```
     to scopes and set up an Identity Pool.
-   For Apple: expect private-relay emails; let users change their e-mail in Edit Profile.
-   Use Gatey’s CSS variables (e.g. 
    ```
    --gatey-account-group-admin
    ```
    ) to show/hide admin UI parts.

#### Common Mistakes

-   **Client secret present** on your App Client → breaks backend-less/static flows. Use SPA/Mobile client (no secret).
-   Missing 
    ```
    openid
    ```
     → login fails.
-   Mismatched callback domain/path → state/nonce errors.
-   No 
    ```
    email
    ```
     mapping → incomplete profiles in WP.
-   Replacing 
    ```
    /wp-login.php
    ```
     before mapping your admin group → potential lock-out.

### Pre-publish checklist

-   Hosted UI domain active; callback & sign-out URLs correct.
-   **App Client has no client secret** (use SPA/Mobile template).
-   Each IdP tested; ID tokens include 
    ```
    email
    ```
    , 
    ```
    given_name
    ```
    , 
    ```
    family_name
    ```
    .
-   Gatey → _User Pools_ filled (Pool ID, App Client ID, Region, Domain, Scopes).
-   Gatey → _General_ set (login mechanisms, sign-up attributes, Sign-in page).
-   (Optional) Identity Pool + IAM permissions if calling AWS APIs.
-   Group→Role mapping in Gatey before replacing 
    ```
    /wp-login.php
    ```
    .

### Key Takeaways

-   Cognito centralizes both social and enterprise identities behind a secure Hosted UI.
-   Use an App Client **without a client secret** (SPA/Mobile) to keep flows backend-less and static-friendly.
-   Gatey turns Cognito into a polished WordPress experience — no PHP callbacks, no secrets in WP, 22 languages.
-   With IAM + Identity Pools your logged-in users can call AWS APIs directly from the browser.

AWS Docs quick links: [App client](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-app-idp-settings.html) · [Domain](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-assign-domain.html) · [Google](https://docs.aws.amazon.com/cognito/latest/developerguide/google.html#set-up-google-1.javascript) · [Facebook](https://docs.aws.amazon.com/cognito/latest/developerguide/facebook.html) · [Apple](https://docs.aws.amazon.com/cognito/latest/developerguide/apple.html) · [Amazon](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon.html) · [OIDC](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-oidc-idp.html) · [SAML](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-saml-idp.html)