/cognito-federation

name: webiny-cognito-federation
description: >
  Configuring Cognito Federation for Webiny projects — federated sign-in via
  external identity providers (Google, Facebook, Apple, Amazon, OIDC/Entra ID)
  while keeping Cognito as the user pool. Use this skill when the developer asks
  about Cognito federation, SSO with Cognito, adding Google/Microsoft/OIDC login
  to Cognito, federated identity providers, CognitoSignInConfig, CognitoIdpConfig, external
  users, signInWithRedirect, OAuth redirect URLs, hiding the password form,
  allowCredentialsLogin, or customizing the federated login screen.

Cognito Federation

TL;DR

Webiny supports federated sign-in through Cognito — users authenticate via external identity providers (Google, Entra ID, etc.) while Cognito remains the user pool. Configure it by adding a `federation` prop to `<Cognito />` in `webiny.config.tsx`. This handles both infrastructure (Cognito User Pool Domain, IdP resources, OAuth client) and the admin login screen (provider buttons, OAuth for Amplify). Federated users are auto-detected and synced into Webiny. For advanced use cases, provide `apiConfig` (custom identity mapping) and/or `adminConfig` (custom login screen behavior).

Pattern / Core Concept

Cognito Federation has three layers:

1. **Infrastructure** — The `federation` prop on `<Cognito />`, under the hood, creates the Cognito User Pool Domain, Identity Provider resources, and configures OAuth on the User Pool Client.

2. **Admin Login Screen** — The federation config is passed as an `Admin.BuildParam` to the admin app. A `CognitoSignInConfig` abstraction provides the login screen with provider buttons, OAuth settings for Amplify, and credentials visibility. By default, this is auto-generated from the `federation` prop. For advanced customization (IP whitelists, async logic), provide an `adminConfig` extension.

3. **API Identity** — Federated tokens are auto-detected via the `identities` JWT claim and marked `external: true`. The `ExternalIdpUserSyncHandler` auto-creates/updates users on login. For custom role/team mapping, provide an `apiConfig` extension implementing `CognitoIdpConfig`.

How Federated Login Works

1. User clicks a provider button on the login screen 2. `signInWithRedirect()` redirects to Cognito Hosted UI 3. Cognito redirects to the external IdP (Google, Entra ID, etc.) 4. After authentication, Cognito creates an `idToken` with an `identities` claim 5. The admin app picks up the session via `fetchAuthSession()` 6. The API detects `identities` in the token, sets `external: true` 7. `ExternalIdpUserSyncHandler` creates/updates the Webiny user with roles/teams

Reference Tables

`<Cognito />` Props

| Prop | Type | Description | | ------------- | --------------------------------- | ------------------------------------------------ | | `federation` | `object \| () => Promise<object>` | Federation config (see below) — sync or async | | `mfa` | `boolean` | Enable TOTP MFA for all users (default: `false`) | | `apiConfig` | `string` | Path to API identity mapping extension | | `adminConfig` | `string` | Path to Admin login customization extension |

`federation` Object

| Field | Type | Required | Default | Description | | ----------------------- | ------------------- | -------- | -------------- | ------------------------------- | | `domain` | `string` | Yes | — | Cognito User Pool domain prefix | | `callbackUrls` | `string[]` | Yes | — | OAuth callback/redirect URLs | | `logoutUrls` | `string[]` | No | `callbackUrls` | OAuth logout redirect URLs | | `responseType` | `"code" \| "token"` | No | `"code"` | OAuth response type | | `allowCredentialsLogin` | `boolean` | No | `true` | Show email/password form | | `identityProviders` | `array` | Yes | — | List of federated IdPs |

`identityProviders[]` Items

| Field | Type | Required | Description | | ------------------ | --------------------------------------------------------- | -------- | ------------------------------------------------------------- | | `type` | `"google" \| "facebook" \| "amazon" \| "apple" \| "oidc"` | Yes | Provider type | | `name` | `string` | No | Custom provider name (required for OIDC) | | `label` | `string` | Yes | Button text on the login screen | | `providerDetails` | `object` | Yes | AWS Cognito provider details (client_id, client_secret, etc.) | | `attributeMapping` | `object` | No | Custom attribute mapping (overrides defaults) |

`CognitoSignInConfig.Interface` (Admin Customization)

| Method | Signature | Description | | ------------- | ----------------------- | ---------------------------------------------- | | `getConfig()` | `() => Promise<Config>` | Returns federation config for the login screen |

`CognitoSignInConfig.Config` (Return Type)

| Field | Type | Required | Description | | ----------------------- | ------------------------------