> ## 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.

## 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

**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**.

**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.

## 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).

## 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

> **[Identity Fabric](/reference/orchestrator/identity-fabric)**
>
> Overview of all identity providers

> **[Generic OIDC](/reference/orchestrator/identity-fabric/custom-oidc)**
>
> Generic OpenID Connect connector

> **[Identity Fabric](/reference/orchestrator/identity-fabric#configuration-reference)**
>
> Full field-level reference for all connector types