> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon Cognito (OIDC)

The Cognito connector integrates the Maverics Orchestrator with Amazon Cognito -- enabling OIDC-based single sign-on for applications that authenticate against Cognito user pools.

<Note>
  **Console terminology:** In the Maverics Console, this section is called
  **Identity Fabric**. The YAML configuration uses the `connectors` key to define
  identity provider integrations.
</Note>

## Overview

The Cognito connector uses OpenID Connect to federate authentication with Amazon Cognito and supports standard OIDC flows -- allowing you to bridge Cognito user pools with applications that don't natively support modern identity protocols.

## Use Cases

* **Unify SSO for AWS-native workloads** -- Extend Cognito user pool authentication to legacy and non-AWS applications, creating a consistent SSO experience across your AWS and hybrid environments
* **Rationalize away from Cognito** -- Gradually migrate users from Cognito to an enterprise IdP like Microsoft Entra ID or Okta without downtime, reducing the complexity of maintaining separate identity stores
* **Hybrid cloud identity orchestration** -- Route authentication across Cognito and enterprise identity providers based on application context, unifying access for organizations with multi-cloud deployments
* **AWS application resilience** -- Configure Cognito as a failover IdP for AWS-hosted applications, ensuring authentication continuity even when the primary identity provider is unavailable

## Setup

<Tabs>
  <Tab title="Console UI">
    To create an Amazon Cognito (OIDC) connector in the Maverics Console:

    1. Navigate to **Identity Fabric** in the Console sidebar.
    2. Click **Create** and select **Amazon Cognito (OIDC)**.
    3. Enter a **Name** for the connector -- this is the friendly name that identifies your Cognito integration.
    4. Enter the **OIDC Well Known URL** for your Cognito user pool. This follows the pattern `https://cognito-idp.{region}.amazonaws.com/{user-pool-id}/.well-known/openid-configuration` -- replace `{region}` with your AWS region (e.g., `us-east-1`) and `{user-pool-id}` with the Cognito user pool ID from the AWS Console.
    5. Enter the **OAuth Client ID** -- the app client ID from your Cognito user pool's App integration settings.
    6. Enter the **OAuth Client Secret** -- the app client secret associated with the client ID. Use the show/hide toggle to verify the value.
    7. Add one or more **Redirect URLs** -- the callback URL(s) where Cognito redirects users after authentication. The Maverics OIDC handler will be served on this URL.
    8. Optionally add **Logout Callback URLs** -- the URL(s) that Cognito calls after a successful logout.
    9. Optionally enter **Scopes** -- space-separated OIDC scopes to request (e.g., `openid profile email`). If left empty, default scopes are used.
    10. **Proof Key for Code Exchange (PKCE)** is enabled by default. Disable this toggle only if your Cognito app client is not configured to support PKCE.
    11. Optionally enable **Offline Access** if you need refresh tokens. When enabled, set your policy's `decision.lifetime` slightly longer than the interval for token refreshing.
    12. Click **Save**.
  </Tab>

  <Tab title="Configuration">
    ```yaml theme={null}
    connectors:
      - name: cognito
        type: cognito
        oidcWellKnownURL: "https://cognito-idp.{{ env.AWS_REGION }}.amazonaws.com/{{ env.COGNITO_USER_POOL_ID }}/.well-known/openid-configuration"
        oauthClientID: "{{ env.COGNITO_CLIENT_ID }}"
        oauthClientSecret: <vault.cognito_client_secret>
        oauthRedirectURL: "https://app.example.com/oidc/callback"
        scopes: "openid profile email"
    ```

    <Note>
      The Cognito well-known URL follows the pattern: `cognito-idp.{region}.amazonaws.com/{user-pool-id}/`. Replace the region and user pool ID with your Cognito configuration values from the AWS Console.
    </Note>

    ## Configuration Reference

    | Key                 | Type   | Required | Description                                                    |
    | ------------------- | ------ | -------- | -------------------------------------------------------------- |
    | `name`              | string | Yes      | Unique connector identifier referenced in app policies         |
    | `type`              | string | Yes      | Must be `cognito`                                              |
    | `oidcWellKnownURL`  | string | Yes      | OIDC discovery endpoint URL (Cognito user pool-specific)       |
    | `oauthClientID`     | string | Yes      | OAuth 2.0 app client ID from the Cognito user pool             |
    | `oauthClientSecret` | string | Yes      | OAuth 2.0 app client secret (use secret reference syntax)      |
    | `oauthRedirectURL`  | string | Yes      | Callback URL registered with the Cognito app client            |
    | `scopes`            | string | No       | Space-separated OAuth scopes (default: `openid profile email`) |
    | `tls`               | string | No       | Named TLS profile for provider communication                   |

    For the complete field reference including health checks, offline access, and PKCE settings, see [Identity Fabric](/reference/orchestrator/identity-fabric#configuration-reference).
  </Tab>
</Tabs>

## Troubleshooting

* **Verify the `oidcWellKnownURL` is accessible** from the Orchestrator host -- ensure the AWS region and user pool ID are correct
* **Ensure the `oauthRedirectURL` matches exactly** what is registered in the Cognito app client under Allowed callback URLs
* **Check that the client secret reference resolves correctly** via your secret provider -- ensure the Cognito app client is configured to generate a client secret

## Related Pages

<CardGroup cols={2}>
  <Card title="Identity Fabric" icon="id-badge" href="/reference/orchestrator/identity-fabric">
    Overview of all identity providers
  </Card>

  <Card title="Generic OIDC" icon="key" href="/reference/orchestrator/identity-fabric/custom-oidc">
    Generic OpenID Connect connector
  </Card>

  <Card title="Identity Fabric" icon="code" href="/reference/orchestrator/identity-fabric#configuration-reference">
    Full field-level reference for all connector types
  </Card>
</CardGroup>