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
```