Set up Amazon Cognito for the Athena user connector

Every access model (A, B and C) starts with the same Cognito resources: a user pool that holds your users, an app client Abacus.AI signs them in with, an identity pool that turns Cognito tokens into AWS credentials, and user groups mapped to IAM roles. Complete this page first, then continue with your access model.

Step 1: Create a Cognito User Pool

If you don't already have a Cognito User Pool:

Go to the Amazon Cognito Console.
Click Create user pool.
Configure sign-in options (email, username, etc.) according to your organization's requirements.
Complete the creation wizard.

Step 2: Create a Cognito App Client

In your User Pool, navigate to App integration → App clients.
Click Create app client.
Configure the app client:
- App client name: e.g. AbacusAI-Athena
- Client type: Confidential client
- Allowed callback URLs: https://abacus.ai/oauth/callback
- OAuth 2.0 grant types: Authorization code grant
- OpenID Connect scopes: openid, profile, email
- Read attributes: Ensure email is included
Note the App Client ID. You'll need it for the connector configuration.

caution

The email scope and email read attribute are required for email-based row filtering (Option B and Option C). Without them, the ID token will not contain the email claim, and user-level filters will silently return zero rows.

Step 3: Configure the Cognito Hosted UI Domain

In your User Pool, navigate to App integration → Domain.
Set up a Cognito domain (e.g. my-app-auth). The full domain will be my-app-auth.auth.<region>.amazoncognito.com.
Note the domain prefix. You'll need it for the connector configuration.

Step 4: Create a Cognito Identity Pool

Go to the Amazon Cognito Federated Identities Console.
Click Create identity pool.
Under Authentication providers, add your Cognito User Pool:
- User Pool ID: Your User Pool ID (e.g. us-east-2_aBcDeFgHi)
- App Client ID: The App Client ID from Step 2
Configure the Authenticated role. This IAM role defines what AWS resources authenticated users can access (Athena, Glue, S3).
Note the Identity Pool ID (e.g. us-east-2:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Step 5: Create Cognito User Groups

Cognito User Groups let you assign different IAM roles to different categories of users. Each group maps to an IAM role that defines what AWS resources those users can access.

In your User Pool, navigate to Groups → Create group.
Create groups for each access level. For example:
- finance_analysts — access to finance tables
- hr_viewers — access to HR tables
- admins — access to all tables
For each group, specify the IAM role ARN that group members should assume (you'll create these roles in Step 6).
Assign users to groups: select a group → Add users → select the users who belong to that group.

You can also manage groups via the CLI:

# Create a group with an IAM role
aws cognito-idp create-group \
  --user-pool-id us-east-2_aBcDeFgHi \
  --group-name finance_analysts \
  --role-arn arn:aws:iam::123456789012:role/Athena-FinanceRole

# Add a user to the group
aws cognito-idp admin-add-user-to-group \
  --user-pool-id us-east-2_aBcDeFgHi \
  --username alice.finance \
  --group-name finance_analysts

Step 5b: Configure Identity Pool Role Mappings

After creating Cognito groups and their corresponding IAM roles, configure the Identity Pool to map authenticated users to the correct role based on their group membership:

In the Cognito Identity Pool Console, select your identity pool.
Click Edit identity pool → expand Authentication providers.
Under your Cognito User Pool provider, set:
- Role resolution: Choose Choose role from token. This uses the cognito:groups claim in the user's token to determine which IAM role to assign.
- Ambiguous role resolution: Select Use most-restrictive authenticated role (for cases where a user belongs to multiple groups).
Save changes.

Alternatively, use Rules-based mapping for more control:

Priority	Claim	Match type	Value	IAM Role
1	`cognito:groups`	Contains	`finance_analysts`	`arn:aws:iam::123456789012:role/Athena-FinanceRole`
2	`cognito:groups`	Contains	`hr_viewers`	`arn:aws:iam::123456789012:role/Athena-HRRole`
3	`cognito:groups`	Contains	`admins`	`arn:aws:iam::123456789012:role/Athena-AdminRole`

tip

With Choose role from token, the Identity Pool reads the cognito:groups claim and resolves the role from the group's configured RoleArn. This is the simplest approach when each group maps to exactly one role.

Step 6: Configure IAM Roles for Authenticated Users

Create one IAM role per Cognito group. The IAM role assigned to authenticated users in the Identity Pool should have permissions to query Athena. Example policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AthenaQueryExecution",
      "Effect": "Allow",
      "Action": [
        "athena:StartQueryExecution",
        "athena:GetQueryExecution",
        "athena:GetQueryResults",
        "athena:StopQueryExecution"
      ],
      "Resource": "arn:aws:athena:<region>:<account_id>:workgroup/*"
    },
    {
      "Sid": "GlueCatalogRead",
      "Effect": "Allow",
      "Action": [
        "glue:GetDatabase",
        "glue:GetTable",
        "glue:GetTables"
      ],
      "Resource": [
        "arn:aws:glue:<region>:<account_id>:catalog",
        "arn:aws:glue:<region>:<account_id>:database/<database_name>",
        "arn:aws:glue:<region>:<account_id>:table/<database_name>/*"
      ]
    },
    {
      "Sid": "S3DataRead",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::<data_bucket>",
        "arn:aws:s3:::<data_bucket>/*"
      ]
    },
    {
      "Sid": "S3ResultsReadWrite",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::<output_bucket>",
        "arn:aws:s3:::<output_bucket>/*"
      ]
    }
  ]
}

tip

Scope the Glue and S3 resources in each role's policy to the databases, tables and buckets that group should reach. For finer control (column-level and row-level security) use AWS Lake Formation, as described in the access model pages.

Token claims reference

When a user authenticates via Cognito, the ID token contains claims that drive access control decisions:

Claim	Example value	Used for
`sub`	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`	Unique user identifier, audit trails
`cognito:username`	`alice.finance`	Display name in the application
`cognito:groups`	`["finance_analysts"]`	Identity Pool role mapping (determines IAM role)
`email`	`alice@example.com`	Row-level filter via `${session:UserEmail}` (Options B and C)
`email_verified`	`true`	Trust check that confirms email ownership

Next step

Configure your access model: Option A — Role-level access, Option B — Email-based row filtering or Option C — Combined table and row isolation.

Step 1: Create a Cognito User Pool​

Step 2: Create a Cognito App Client​

Step 3: Configure the Cognito Hosted UI Domain​

Step 4: Create a Cognito Identity Pool​

Step 5: Create Cognito User Groups​

Step 5b: Configure Identity Pool Role Mappings​

Step 6: Configure IAM Roles for Authenticated Users​

Token claims reference​

Next step​