0
# pycognito
1
2
A comprehensive Python library for integrating with AWS Cognito authentication services, offering simplified user management operations including registration, authentication, password management, and token handling. It wraps Boto3's Cognito client with an easy-to-use interface that supports Secure Remote Password (SRP) authentication protocol, making it ideal for serverless applications and web services that require AWS Cognito user pool integration.
3
4
## Package Information
5
6
- **Package Name**: pycognito
7
- **Language**: Python
8
- **Installation**: `pip install pycognito`
9
10
## Core Imports
11
12
```python
13
from pycognito import Cognito
14
```
15
16
Import specific utilities:
17
18
```python
19
from pycognito import UserObj, GroupObj
20
from pycognito.aws_srp import AWSSRP
21
from pycognito.utils import RequestsSrpAuth, TokenType
22
```
23
24
Import exceptions:
25
26
```python
27
from pycognito.exceptions import (
28
TokenVerificationException,
29
MFAChallengeException,
30
ForceChangePasswordException
31
)
32
```
33
34
## Basic Usage
35
36
```python
37
from pycognito import Cognito
38
39
# Create Cognito instance
40
u = Cognito(
41
user_pool_id='your-user-pool-id',
42
client_id='your-client-id',
43
username='bob'
44
)
45
46
# Authenticate user
47
u.authenticate(password='bobs-password')
48
49
# Access tokens after authentication
50
print(u.access_token)
51
print(u.id_token)
52
print(u.refresh_token)
53
54
# Get user information
55
user = u.get_user()
56
print(user.username)
57
print(user.email)
58
59
# Update user profile
60
u.update_profile({'given_name': 'Bob', 'family_name': 'Smith'})
61
```
62
63
## Architecture
64
65
pycognito is built around several key components:
66
67
- **Cognito Class**: Main interface for all AWS Cognito operations including authentication, user management, and token handling
68
- **UserObj/GroupObj**: Object representations of Cognito users and groups with convenience methods
69
- **AWSSRP**: Low-level implementation of AWS Secure Remote Password protocol for authentication
70
- **RequestsSrpAuth**: Requests authentication plugin for automatic token handling in HTTP requests
71
- **Exception Classes**: Specialized exceptions for different authentication and authorization scenarios
72
73
The library handles complex authentication flows, token verification, user profile management, and group operations while abstracting away the underlying AWS API complexity.
74
75
## Capabilities
76
77
### Authentication and Token Management
78
79
Core authentication functionality including SRP authentication, admin authentication, token verification, renewal, and logout operations. Handles complex authentication flows and token lifecycle management.
80
81
```python { .api }
82
class Cognito:
83
def authenticate(self, password: str, client_metadata: dict = None) -> None: ...
84
def admin_authenticate(self, password: str) -> None: ...
85
def verify_tokens(self) -> None: ...
86
def check_token(self, renew: bool = True) -> bool: ...
87
def renew_access_token(self) -> None: ...
88
def logout(self) -> None: ...
89
```
90
91
[Authentication and Token Management](./authentication.md)
92
93
### User Management
94
95
Comprehensive user management including registration, profile updates, user retrieval, deletion, and administrative user operations. Supports both user-level and admin-level operations.
96
97
```python { .api }
98
class Cognito:
99
def register(self, username: str, password: str, attr_map: dict = None, client_metadata: dict = None) -> dict: ...
100
def get_user(self, attr_map: dict = None) -> UserObj: ...
101
def update_profile(self, attrs: dict, attr_map: dict = None) -> None: ...
102
def admin_create_user(self, username: str, temporary_password: str = "", **kwargs) -> dict: ...
103
def delete_user(self) -> None: ...
104
```
105
106
[User Management](./user-management.md)
107
108
### Password Management
109
110
Password-related operations including forgot password flows, password changes, confirmation codes, and password reset functionality with both user and admin capabilities.
111
112
```python { .api }
113
class Cognito:
114
def initiate_forgot_password(self) -> None: ...
115
def confirm_forgot_password(self, confirmation_code: str, password: str) -> None: ...
116
def change_password(self, previous_password: str, proposed_password: str) -> None: ...
117
def admin_reset_password(self, username: str, client_metadata: dict = None) -> None: ...
118
```
119
120
[Password Management](./password-management.md)
121
122
### Multi-Factor Authentication (MFA)
123
124
Complete MFA support including software token (TOTP) and SMS MFA. Handles MFA setup, verification, preferences, and challenge responses for enhanced security.
125
126
```python { .api }
127
class Cognito:
128
def associate_software_token(self) -> str: ...
129
def verify_software_token(self, code: str, device_name: str = "") -> bool: ...
130
def set_user_mfa_preference(self, sms_mfa: bool, software_token_mfa: bool, preferred: str = None) -> None: ...
131
def respond_to_software_token_mfa_challenge(self, code: str, mfa_tokens: dict = None) -> None: ...
132
def respond_to_sms_mfa_challenge(self, code: str, mfa_tokens: dict = None) -> None: ...
133
```
134
135
[Multi-Factor Authentication](./mfa.md)
136
137
### Group Management
138
139
Group operations including group creation, retrieval, user group membership management, and administrative group operations for organizing users.
140
141
```python { .api }
142
class Cognito:
143
def get_group(self, group_name: str) -> GroupObj: ...
144
def get_groups(self) -> list[GroupObj]: ...
145
def admin_add_user_to_group(self, username: str, group_name: str) -> None: ...
146
def admin_remove_user_from_group(self, username: str, group_name: str) -> None: ...
147
def admin_list_groups_for_user(self, username: str) -> list[str]: ...
148
```
149
150
[Group Management](./group-management.md)
151
152
### Device Authentication
153
154
Device tracking and authentication support including device confirmation, status management, and device-based authentication flows for enhanced security.
155
156
```python { .api }
157
class AWSSRP:
158
def confirm_device(self, tokens: dict, device_name: str = None) -> tuple: ...
159
def update_device_status(self, is_remembered: bool, access_token: str, device_key: str) -> str: ...
160
def forget_device(self, access_token: str, device_key: str) -> str: ...
161
```
162
163
[Device Authentication](./device-authentication.md)
164
165
### SRP Authentication Protocol
166
167
Low-level Secure Remote Password protocol implementation providing the cryptographic foundation for secure authentication without transmitting passwords.
168
169
```python { .api }
170
class AWSSRP:
171
def __init__(self, username: str, password: str, pool_id: str, client_id: str, **kwargs): ...
172
def authenticate_user(self, client=None, client_metadata: dict = None) -> dict: ...
173
def set_new_password_challenge(self, new_password: str, client=None) -> dict: ...
174
```
175
176
[SRP Authentication Protocol](./srp-authentication.md)
177
178
### HTTP Integration
179
180
Requests authentication plugin for seamless integration with HTTP clients, automatically handling token management and authentication headers.
181
182
```python { .api }
183
class RequestsSrpAuth:
184
def __init__(self, username: str = None, password: str = None, user_pool_id: str = None,
185
client_id: str = None, cognito: Cognito = None, **kwargs): ...
186
```
187
188
[HTTP Integration](./http-integration.md)
189
190
### Identity Provider Management
191
192
Administrative operations for managing external identity providers (SAML, OIDC, social providers) within the user pool for federated authentication.
193
194
```python { .api }
195
class Cognito:
196
def admin_create_identity_provider(self, pool_id: str, provider_name: str, provider_type: str, provider_details: dict, **kwargs) -> None: ...
197
def admin_describe_identity_provider(self, pool_id: str, provider_name: str) -> dict: ...
198
def admin_update_identity_provider(self, pool_id: str, provider_name: str, **kwargs) -> None: ...
199
```
200
201
### User Pool Client Management
202
203
Operations for managing user pool application clients, including configuration retrieval and updates for client settings.
204
205
```python { .api }
206
class Cognito:
207
def describe_user_pool_client(self, pool_id: str, client_id: str) -> dict: ...
208
def admin_update_user_pool_client(self, pool_id: str, client_id: str, **kwargs) -> None: ...
209
```
210
211
## Types
212
213
### Core Classes
214
215
```python { .api }
216
class Cognito:
217
"""Main class for AWS Cognito User Pool operations."""
218
def __init__(self, user_pool_id: str, client_id: str, user_pool_region: str = None,
219
username: str = None, id_token: str = None, refresh_token: str = None,
220
access_token: str = None, client_secret: str = None, access_key: str = None,
221
secret_key: str = None, session = None, botocore_config = None,
222
boto3_client_kwargs: dict = None): ...
223
224
# Properties
225
user_pool_url: str
226
id_claims: dict
227
access_claims: dict
228
229
class UserObj:
230
"""Represents a Cognito user with attributes and operations."""
231
def __init__(self, username: str, attribute_list: list, cognito_obj: Cognito,
232
metadata: dict = None, attr_map: dict = None): ...
233
234
# Properties
235
username: str
236
sub: str
237
email_verified: bool
238
phone_number_verified: bool
239
240
def save(self, admin: bool = False) -> None: ...
241
def delete(self, admin: bool = False) -> None: ...
242
243
class GroupObj:
244
"""Represents a Cognito user group."""
245
def __init__(self, group_data: dict, cognito_obj: Cognito): ...
246
247
# Properties
248
group_name: str
249
description: str
250
creation_date: datetime
251
last_modified_date: datetime
252
role_arn: str
253
precedence: int
254
255
class AWSSRP:
256
"""AWS SRP authentication protocol implementation."""
257
def __init__(self, username: str, password: str, pool_id: str, client_id: str, **kwargs): ...
258
259
class RequestsSrpAuth:
260
"""Requests authentication plugin for automatic Cognito authentication."""
261
def __init__(self, username: str = None, password: str = None, **kwargs): ...
262
```
263
264
### Enumerations
265
266
```python { .api }
267
class TokenType(str, Enum):
268
"""Token types for authentication."""
269
ID_TOKEN = "id_token"
270
ACCESS_TOKEN = "access_token"
271
```
272
273
### Exception Classes
274
275
```python { .api }
276
class WarrantException(Exception):
277
"""Base class for all pyCognito exceptions."""
278
279
class TokenVerificationException(WarrantException):
280
"""Raised when token verification fails."""
281
282
class MFAChallengeException(WarrantException):
283
"""Base class for MFA challenge exceptions."""
284
def get_tokens(self) -> dict: ...
285
286
class SoftwareTokenMFAChallengeException(MFAChallengeException):
287
"""Raised when Software Token MFA is required."""
288
289
class SMSMFAChallengeException(MFAChallengeException):
290
"""Raised when SMS MFA is required."""
291
292
class ForceChangePasswordException(WarrantException):
293
"""Raised when user is forced to change their password."""
294
```
295
296
### Utility Functions
297
298
```python { .api }
299
def cognito_to_dict(attr_list: list, attr_map: dict = None) -> dict:
300
"""Convert Cognito attribute list to dictionary."""
301
302
def dict_to_cognito(attributes: dict, attr_map: dict = None) -> list:
303
"""Convert dictionary to Cognito attribute format."""
304
305
def camel_to_snake(camel_str: str) -> str:
306
"""Convert CamelCase to snake_case."""
307
308
def snake_to_camel(snake_str: str) -> str:
309
"""Convert snake_case to CamelCase."""
310
```