# 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:
1. `sync`\
Export all users of a Cognito User Pool into a local CSV file containing:\
`username,email`.
2. `add`\
Add users (specified by email) to one or more Cognito groups.
3. `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:
1. The sync CSV file (`username,email`)
2. 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](LICENSE) or
https://opensource.org/licenses/ISC)
