0
# Authentication
1

2
Secure authentication using access/secret keys with token-based access control for all Qiniu services. The authentication system supports both standard Auth and MAC (Message Authentication Code) authentication methods.
3

4
## Capabilities
5

6
### Basic Authentication
7

8
The `Auth` class provides the primary authentication interface for Qiniu services.
9

10
```python { .api }
11
class Auth:
12
    def __init__(self, access_key: str, secret_key: str, disable_qiniu_timestamp_signature: bool = None):
13
        """
14
        Initialize authentication with access and secret keys.
15
        
16
        Args:
17
            access_key: Qiniu access key
18
            secret_key: Qiniu secret key  
19
            disable_qiniu_timestamp_signature: Whether to disable timestamp signatures
20
        """
21

22
    def get_access_key(self) -> str:
23
        """Get the access key."""
24

25
    def get_secret_key(self) -> str:
26
        """Get the secret key."""
27

28
    def upload_token(self, bucket: str, key: str = None, expires: int = 3600, policy: dict = None, strict_policy: bool = True) -> str:
29
        """
30
        Generate upload token for file uploads.
31
        
32
        Args:
33
            bucket: Target bucket name
34
            key: File key (optional for auto-generated key)
35
            expires: Token expiration time in seconds (default: 3600)
36
            policy: Upload policy dictionary (optional)
37
            strict_policy: Whether to enforce strict policy validation
38
            
39
        Returns:
40
            Upload token string
41
        """
42

43
    def private_download_url(self, url: str, expires: int = 3600) -> str:
44
        """
45
        Generate private download URL with expiration.
46
        
47
        Args:
48
            url: Original file URL
49
            expires: URL expiration time in seconds
50
            
51
        Returns:
52
            Signed private download URL
53
        """
54

55
    def token_of_request(self, url: str, body: str = None, content_type: str = None) -> str:
56
        """
57
        Generate management token for API requests.
58
        
59
        Args:
60
            url: Request URL
61
            body: Request body (optional)
62
            content_type: Content type header (optional)
63
            
64
        Returns:
65
            Management token string
66
        """
67

68
    def token_with_data(self, data: str) -> str:
69
        """
70
        Generate token with encoded data.
71
        
72
        Args:
73
            data: Data to encode in token
74
            
75
        Returns:
76
            Token string with encoded data
77
        """
78

79
    def verify_callback(self, origin_authorization: str, url: str, body: str, content_type: str = 'application/x-www-form-urlencoded', method: str = 'GET', headers: dict = None) -> bool:
80
        """
81
        Verify callback request authorization.
82
        
83
        Args:
84
            origin_authorization: Original authorization header
85
            url: Callback URL
86
            body: Request body
87
            content_type: Content type
88
            method: HTTP method
89
            headers: Request headers
90
            
91
        Returns:
92
            True if verification succeeds
93
        """
94

95
    @staticmethod
96
    def up_token_decode(up_token: str) -> tuple:
97
        """
98
        Decode upload token to extract policy information.
99
        
100
        Args:
101
            up_token: Upload token to decode
102
            
103
        Returns:
104
            (access_key, signature, policy_dict): Tuple containing access key, signature, and policy data
105
        """
106

107
    @staticmethod
108
    def get_bucket_name(up_token: str) -> str:
109
        """
110
        Extract bucket name from upload token.
111
        
112
        Args:
113
            up_token: Upload token
114
            
115
        Returns:
116
            Bucket name string
117
        """
118
```
119

120
### MAC Authentication
121

122
Advanced MAC authentication for direct HTTP client integration.
123

124
```python { .api }
125
class QiniuMacAuth:
126
    def __init__(self, access_key: str, secret_key: str, disable_qiniu_timestamp_signature: bool = None):
127
        """
128
        Initialize MAC authentication.
129
        
130
        Args:
131
            access_key: Qiniu access key
132
            secret_key: Qiniu secret key
133
            disable_qiniu_timestamp_signature: Whether to disable timestamp signatures
134
        """
135

136
    def token_of_request(self, method: str, host: str, url: str, qheaders: dict, content_type: str = None, body: str = None) -> str:
137
        """
138
        Generate request token using MAC authentication.
139
        
140
        Args:
141
            method: HTTP method (GET, POST, etc.)
142
            host: Request host
143
            url: Request URL path
144
            qheaders: Qiniu-specific headers
145
            content_type: Request content type
146
            body: Request body
147
            
148
        Returns:
149
            MAC authentication token
150
        """
151

152
    def qiniu_headers(self, headers: dict) -> dict:
153
        """
154
        Process and filter Qiniu-specific headers.
155
        
156
        Args:
157
            headers: Original headers dictionary
158
            
159
        Returns:
160
            Filtered Qiniu headers
161
        """
162

163
    def verify_callback(self, origin_authorization: str, url: str, body: str, content_type: str, method: str, headers: dict) -> bool:
164
        """
165
        Verify callback authorization using MAC.
166
        
167
        Args:
168
            origin_authorization: Original authorization header
169
            url: Callback URL
170
            body: Request body
171
            content_type: Content type
172
            method: HTTP method
173
            headers: Request headers
174
            
175
        Returns:
176
            True if verification succeeds
177
        """
178

179
    @property
180
    def should_sign_with_timestamp(self) -> bool:
181
        """Whether timestamp signature should be used."""
182
```
183

184
### HTTP Client Integration
185

186
Authentication adapters for use with the `requests` library.
187

188
```python { .api }
189
class RequestsAuth:
190
    def __init__(self, auth: Auth):
191
        """
192
        Requests library auth adapter for basic Auth.
193
        
194
        Args:
195
            auth: Auth instance
196
        """
197

198
class QiniuMacRequestsAuth:
199
    def __init__(self, auth: QiniuMacAuth):
200
        """
201
        Requests library auth adapter for MAC authentication.
202
        
203
        Args:
204
            auth: QiniuMacAuth instance
205
        """
206
```
207

208
## Usage Examples
209

210
### Basic Authentication Setup
211

212
```python
213
from qiniu import Auth
214

215
# Initialize with your credentials
216
access_key = 'your_access_key'
217
secret_key = 'your_secret_key'
218
auth = Auth(access_key, secret_key)
219

220
# Generate upload token
221
bucket = 'my-bucket'
222
key = 'my-file.jpg'
223
token = auth.upload_token(bucket, key, expires=7200)  # 2 hours
224
print(f"Upload token: {token}")
225
```
226

227
### Advanced Upload Policy
228

229
```python
230
from qiniu import Auth
231

232
auth = Auth(access_key, secret_key)
233

234
# Custom upload policy
235
policy = {
236
    'scope': 'my-bucket:my-file.jpg',
237
    'deadline': 1893456000,  # Unix timestamp
238
    'insertOnly': 1,  # Prevent overwrite
239
    'fsizeLimit': 10485760,  # Max 10MB
240
    'callbackUrl': 'https://api.example.com/callback',
241
    'callbackBody': 'filename=$(fname)&filesize=$(fsize)'
242
}
243

244
token = auth.upload_token('my-bucket', 'my-file.jpg', policy=policy)
245
```
246

247
### Private Download URLs
248

249
```python
250
from qiniu import Auth
251

252
auth = Auth(access_key, secret_key)
253

254
# Original public URL
255
public_url = 'http://domain.com/file.jpg'
256

257
# Generate private download URL valid for 1 hour
258
private_url = auth.private_download_url(public_url, expires=3600)
259
print(f"Private URL: {private_url}")
260
```
261

262
### MAC Authentication with Requests
263

264
```python
265
import requests
266
from qiniu import QiniuMacAuth, QiniuMacRequestsAuth
267

268
mac_auth = QiniuMacAuth(access_key, secret_key)
269
requests_auth = QiniuMacRequestsAuth(mac_auth)
270

271
# Use with requests library
272
response = requests.get('https://rs.qiniu.com/bucket/my-bucket', auth=requests_auth)
273
print(response.json())
274
```