# Cognito Users

Fetches users from a specific user pool in AWS Cognito.

## Details

AWS Cognito is a user identity and access management service that lets you add user sign-up, sign-in, and access control to your web and mobile apps. This input connector retrieves user information from a specified Cognito User Pool, allowing you to monitor and analyze user accounts, their status, and attributes.

## Functionality

On initialization, Monad connects to the specified AWS Cognito User Pool in the configured region and retrieves user data. The connector supports optional filtering to narrow down the users retrieved based on specific attributes like user status or custom attributes. The connector maintains state to ensure efficient processing and can handle large user pools through automatic pagination.

## Requirements
- [IAM Role Assumption / Static Credentials](./index.mdx#authentication-methods)
- Example permission to attach to the role/user:
```json 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Action": [
        "cognito-idp:ListUsers",
        "cognito-idp:DescribeUserPool"
      ],
      "Resource": "*"
    }
  ]
}
```

## Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

#### Settings

| Setting  | Type   | Required | Description                                                                                                                                                     |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Region   | string | Yes      | The AWS region where the Cognito User Pool is located.                                                                                                                      |
| Role ARN | string | Yes      | The ARN of the IAM role to assume for accessing AWS Cognito.                                                                                         |
| Cron      | string | Yes      | Cron expression for scheduling the input.                             |
| User Pool ID      | string | Yes      | The ID of the AWS Cognito User Pool to extract users from.                             |
| Filter | object | No      | Optional filter for the ListUsers API to narrow down results. |

#### Filter Object Properties

| Setting  | Type   | Required | Description                                                                                                                                                     |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Attribute   | string | No      | The attribute to filter on (e.g., 'cognito:user_status').                                                                                                                      |
| Value      | string | No      | The value to filter by (e.g., 'CONFIRMED').                             |
| Operator      | string | No      | The operator to use for filtering.                             |

### Secrets (Static Credentials Only)

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| **Access Key** | string | Conditional | AWS Access Key ID |
| **Secret Key** | string | Conditional | AWS Secret Access Key |

> ⚠️ **Authentication**: Choose either Role ARN (recommended) or static credentials. See [AWS Authentication Guide](./index.mdx#authentication-methods) for setup instructions.

### Related Articles

- [AWS Cognito User Pools Guide](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html)
- [List Users API Reference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html)

## Sample Record

```json
{
  "Attributes": [
    {
      "Name": "email",
      "Value": "Alice Brown@mail.net"
    },
    {
      "Name": "given_name",
      "Value": "Tom Johnson"
    },
    {
      "Name": "family_name",
      "Value": "Miller"
    },
    {
      "Name": "email_verified",
      "Value": "true"
    },
    {
      "Name": "sub",
      "Value": "36a8a82e-2a23-ccae-da21-7d982ba6afc0"
    },
    {
      "Name": "preferred_username",
      "Value": "+1234567890"
    }
  ],
  "Enabled": "true",
  "MFAOptions": [
    {
      "AttributeName": "phone_number",
      "DeliveryMedium": "EMAIL"
    }
  ],
  "UserCreateDate": "2025-08-11T23:46:56.201762Z",
  "UserLastModifiedDate": "2025-08-11T23:46:56.201767Z",
  "UserStatus": "RESET_REQUIRED",
  "Username": "peterjones@example.com"
}
```

## Sync frequency

This input runs on a cron schedule (default hourly, `0 * * * *`), which you can configure on the pipeline. See [Input Sync Frequency](../../guides/sync-frequency) for details.