cogops
cogops is a command-line tool for performing batch operations on AWS Cognito
user pools.
It supports synchronizing users into a local file, adding users to groups, and
removing users from groups.
Why
Some of our internal systems rely on AWS Cognito Group membership for authorization. However, Cognito:
- Does not support batch operations
- Requires the opaque Cognito username for group changes
- Does not allow group operations using the user’s email
- Can throttle if performing requests per user per group
- Each user lookup by email requires a full search query
Command sync Required?
Our Cognito User Pool integrates with Google Identity Provider.
Cognito usernames look like: Google_AbCdEf1234567890
Emails are stored only as attributes and cannot be passed to Cognito Admin APIs. Other internal systems only know users by email — mismatch.
Solution, the sync command downloads all users via paginated calls:
username,email
Google_a3be23de...,user@example.com
Google_91cfeacb...,another@example.com
This creates a local, up-to-date user index so later add and del operations run:
- 1 direct request per user
- No additional lookup/search required
- No wasted API calls
Features
- sync: Generates an optimized local mapping username,email of all Cognito users
- add: Add users in bulk to one or more groups
- Concurrency Control
- Operation timetout
Requirements
- Rust toolchain (Rust 1.75 or newer recommended)
- AWS credentials with Administrator privileges for the target Cognito user pool
- Access to the AWS API (environment variables, credential file, or IAM role)
To install Rust:
curl https://sh.rustup.rs -sSf | sh
Verify installation:
rustc --version
cargo --version
Building
Clone the repository and build the binary:
- Official: ssh://anon@ijanc.org/cogops
- Mirror Sourcehut: git@git.sr.ht:~ijanc/cogops
- Mirror Github: git@github.com:ijanc/cogops.git
git clone ssh://anon@ijanc.org/cogops
cd cogops
cargo build --release
The binary will be located at:
target/release/cogops
You can add it to your PATH or move it to /usr/local/bin.
AWS Credentials
cogops uses the official AWS Rust SDK and respects all standard credential
providers.
For example:
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1
Commands Overview
cogops provides three main operations:
sync
Export all users of a Cognito User Pool into a local CSV file containing:
username,email.add
Add users (specified by email) to one or more Cognito groups.del
Remove users from one or more Cognito groups.
1. Synchronizing users (sync)
This operation reads all users from the provided Cognito User Pool ID and writes them to a CSV file.
Example:
cogops sync --pool-id us-east-1_ABC123 --sync-file .sync
Output file format:
username,email
alice,alice@example.com
bob,bob@example.com
carol,carol@example.com
This file is later used by the add and del operations.
2. Adding users to groups (add)
This operation requires two input files:
- The sync CSV file (
username,email) - A text file containing one email per line
All emails will be normalized (lowercase, trim) before lookup.
Example:
cogops add --pool-id us-east-1_ABC123 --sync-file .sync \
--emails-file to_add.txt --group admin --group managers \
--concurrency 10
Where to_add.txt might contain:
alice@example.com
carol@example.com
john@example.com
For each email, cogops resolves the username from the sync map and calls the
Cognito Admin API to add the user to the specified groups.
A progress bar is displayed during processing.
3. Removing users from groups (del) (WIP)
This command mirrors the add command but removes users instead of adding
them.
Example:
cogops del --pool-id us-east-1_ABC123 --sync-file cognito_sync.csv \
--emails-file to_remove.txt --group admin --concurrency 5
Logging and verbosity
cogops uses tracing for structured logging.
By default, logs are shown at the INFO level.
Use -v to enable DEBUG logs:
cogops -v add ...
Or configure via RUST_LOG:
RUST_LOG=debug cogops add ...
License
Licensed under ISC license (LICENSE or https://opensource.org/licenses/ISC)