0
# Security Document Management
1
2
Management of database security documents for controlling access permissions and user roles in Cloudant and CouchDB databases. Security documents define who can read, write, and administer databases.
3
4
## Capabilities
5
6
### Security Document Operations
7
8
Manage database security documents with context manager support for automatic fetch and save operations.
9
10
```python { .api }
11
class SecurityDocument(dict):
12
"""
13
Encapsulates a JSON security document for managing database access permissions.
14
15
Parameters:
16
- database: CouchDatabase or CloudantDatabase instance
17
"""
18
def __init__(self, database): ...
19
20
def fetch(self):
21
"""
22
Retrieves security document content from remote database.
23
Overwrites local content with remote document.
24
"""
25
26
def save(self):
27
"""
28
Saves local security document changes to remote database.
29
"""
30
31
def json(self):
32
"""
33
Returns JSON string representation of security document.
34
35
Returns:
36
str: Encoded JSON string containing security document data
37
"""
38
39
def __enter__(self):
40
"""Context manager entry - automatically fetches document."""
41
42
def __exit__(self, *args):
43
"""Context manager exit - automatically saves document."""
44
45
@property
46
def document_url(self):
47
"""
48
Constructs security document URL.
49
50
Returns:
51
str: Security document URL
52
"""
53
54
@property
55
def r_session(self):
56
"""
57
Returns Python requests session used by security document.
58
59
Returns:
60
requests.Session: The session object
61
"""
62
```
63
64
## Usage Examples
65
66
### Context Manager Pattern (Recommended)
67
68
```python
69
from cloudant import cloudant
70
from cloudant.security_document import SecurityDocument
71
72
with cloudant(username, password, account=account_name) as client:
73
db = client['my_database']
74
75
# Context manager automatically fetches and saves
76
with SecurityDocument(db) as security_doc:
77
# Add users to Cloudant roles
78
if 'cloudant' not in security_doc:
79
security_doc['cloudant'] = {}
80
81
security_doc['cloudant']['julia'] = ['_reader', '_writer']
82
security_doc['cloudant']['ruby'] = ['_admin', '_replicator']
83
84
# Add users to CouchDB roles
85
if 'admins' not in security_doc:
86
security_doc['admins'] = {'names': [], 'roles': []}
87
if 'members' not in security_doc:
88
security_doc['members'] = {'names': [], 'roles': []}
89
90
security_doc['admins']['names'].append('admin_user')
91
security_doc['members']['names'].append('regular_user')
92
# Document automatically saved on context exit
93
```
94
95
### Manual Operations
96
97
```python
98
from cloudant.security_document import SecurityDocument
99
100
with cloudant(username, password, account=account_name) as client:
101
db = client['my_database']
102
security_doc = SecurityDocument(db)
103
104
# Manually fetch current security document
105
security_doc.fetch()
106
107
# Modify permissions
108
security_doc['cloudant'] = {
109
'admin_user': ['_admin'],
110
'read_user': ['_reader']
111
}
112
113
# Manually save changes
114
security_doc.save()
115
116
# Get JSON representation
117
json_string = security_doc.json()
118
print(json_string)
119
```
120
121
### Reading Current Security Settings
122
123
```python
124
with SecurityDocument(database) as security_doc:
125
# Check current Cloudant permissions
126
if 'cloudant' in security_doc:
127
for user, roles in security_doc['cloudant'].items():
128
print(f"User {user} has roles: {roles}")
129
130
# Check CouchDB permissions
131
if 'admins' in security_doc:
132
admin_users = security_doc['admins']['names']
133
print(f"Admin users: {admin_users}")
134
135
if 'members' in security_doc:
136
member_users = security_doc['members']['names']
137
print(f"Member users: {member_users}")
138
```
139
140
## Security Document Structure
141
142
### Cloudant Security Format
143
144
```python
145
{
146
"cloudant": {
147
"username": ["_reader", "_writer", "_admin", "_replicator"],
148
"another_user": ["_reader"]
149
}
150
}
151
```
152
153
### CouchDB Security Format
154
155
```python
156
{
157
"admins": {
158
"names": ["admin_user"],
159
"roles": ["admin_role"]
160
},
161
"members": {
162
"names": ["member_user"],
163
"roles": ["member_role"]
164
}
165
}
166
```
167
168
## Types
169
170
```python { .api }
171
# Security document roles for Cloudant
172
CLOUDANT_ROLES = ["_reader", "_writer", "_admin", "_replicator"]
173
174
# Security document structure
175
SecurityDocumentData = dict[str, Any]
176
177
# CouchDB section structure
178
CouchDBSection = dict[str, list[str]] # keys: "names", "roles"
179
180
# Cloudant section structure
181
CloudantSection = dict[str, list[str]] # username -> list of roles
182
```
183
184
## Import Statements
185
186
```python
187
from cloudant.security_document import SecurityDocument
188
```