1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
# 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:
```
git clone https://github.com/ijanc/cogops.git
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)
|