0
# Authentication
1

2
Comprehensive authentication support for Swift v1 auth, Keystone v2/v3, and session-based authentication with multiple credential types and authentication methods.
3

4
## Capabilities
5

6
### Main Authentication Function
7

8
Central authentication function supporting multiple Swift authentication methods and OpenStack Keystone versions.
9

10
```python { .api }
11
def get_auth(auth_url, user, key, **kwargs):
12
    """
13
    Get authentication/authorization credentials.
14

15
    Parameters:
16
    - auth_url: str, authentication URL
17
    - user: str, username to authenticate as
18
    - key: str, key/password to authenticate with
19
    - auth_version: str, API version ('1', '2.0', '3', default '1')
20
    - os_options: dict, OpenStack identity service options
21
    - session: keystoneauth1.Session, existing session object
22
    - snet: bool, use SERVICENET internal network (default False)
23
    - cacert: str, CA bundle file for TLS verification
24
    - insecure: bool, disable SSL certificate verification
25
    - cert: str, client certificate file
26
    - cert_key: str, client certificate private key file
27
    - timeout: float, connection timeout in seconds
28
    - tenant_name: str, tenant name for v2.0 auth
29

30
    Returns:
31
    tuple: (storage_url, auth_token)
32

33
    Raises:
34
    ClientException: Authentication failed
35
    """
36
```
37

38
### Swift v1 Authentication
39

40
Original Swift authentication using HTTP headers, compatible with tempauth, swauth, and legacy Swift installations.
41

42
```python { .api }
43
def get_auth_1_0(url, user, key, snet, **kwargs):
44
    """
45
    Authenticate using Swift v1.0 authentication.
46

47
    Parameters:
48
    - url: str, authentication URL
49
    - user: str, username (often in format tenant:user)
50
    - key: str, authentication key/password
51
    - snet: bool, use SERVICENET internal network
52
    - cacert: str, CA bundle file for TLS verification
53
    - insecure: bool, disable SSL certificate verification
54
    - cert: str, client certificate file
55
    - cert_key: str, client certificate private key file
56
    - timeout: float, connection timeout in seconds
57

58
    Returns:
59
    tuple: (storage_url, auth_token)
60

61
    Raises:
62
    ClientException: Authentication failed
63
    """
64
```
65

66
### Keystone Authentication
67

68
OpenStack Identity (Keystone) authentication supporting v2.0 and v3 APIs with comprehensive credential options.
69

70
```python { .api }
71
def get_auth_keystone(auth_url, user, key, os_options, **kwargs):
72
    """
73
    Authenticate against Keystone identity service.
74

75
    Parameters:
76
    - auth_url: str, Keystone authentication URL
77
    - user: str, username for authentication
78
    - key: str, password for authentication
79
    - os_options: dict, OpenStack authentication options
80
    - auth_version: str, Keystone version ('2.0', '3')
81
    - cacert: str, CA bundle file for TLS verification
82
    - insecure: bool, disable SSL certificate verification
83
    - cert: str, client certificate file
84
    - cert_key: str, client certificate private key file
85
    - timeout: float, connection timeout in seconds
86

87
    Returns:
88
    tuple: (storage_url, auth_token)
89

90
    Raises:
91
    ClientException: Authentication failed
92
    """
93

94
def get_keystoneclient_2_0(auth_url, user, key, os_options, **kwargs):
95
    """
96
    Legacy wrapper for Keystone v2.0 authentication.
97

98
    Parameters:
99
    - auth_url: str, Keystone v2.0 authentication URL
100
    - user: str, username for authentication
101
    - key: str, password for authentication
102
    - os_options: dict, OpenStack authentication options
103

104
    Returns:
105
    tuple: (storage_url, auth_token)
106
    """
107
```
108

109
## OpenStack Options
110

111
The `os_options` dictionary supports comprehensive OpenStack identity configuration:
112

113
### Basic Identity Options
114

115
```python
116
os_options = {
117
    'tenant_id': 'tenant-uuid',
118
    'tenant_name': 'tenant-name',
119
    'project_id': 'project-uuid',
120
    'project_name': 'project-name',
121
    'user_id': 'user-uuid',
122
    'user_domain_id': 'user-domain-uuid',
123
    'user_domain_name': 'user-domain-name',
124
    'project_domain_id': 'project-domain-uuid',
125
    'project_domain_name': 'project-domain-name',
126
}
127
```
128

129
### Service Configuration
130

131
```python
132
os_options = {
133
    'service_type': 'object-store',  # Default: 'object-store'
134
    'endpoint_type': 'publicURL',    # 'publicURL', 'internalURL', 'adminURL'
135
    'region_name': 'us-east-1',
136
    'auth_token': 'existing-token',
137
    'object_storage_url': 'https://swift.example.com/v1/AUTH_account',
138
}
139
```
140

141
### Application Credentials
142

143
```python
144
os_options = {
145
    'auth_type': 'v3applicationcredential',
146
    'application_credential_id': 'app-cred-id',
147
    'application_credential_secret': 'app-cred-secret',
148
}
149
```
150

151
## Usage Examples
152

153
### Swift v1 Authentication
154

155
```python
156
from swiftclient import get_auth
157

158
# Basic v1 auth
159
storage_url, token = get_auth(
160
    'http://swift.example.com/auth/v1.0',
161
    'tenant:username',
162
    'password'
163
)
164

165
# v1 auth with SSL
166
storage_url, token = get_auth(
167
    'https://swift.example.com/auth/v1.0',
168
    'tenant:username',
169
    'password',
170
    cacert='/path/to/ca-bundle.crt',
171
    insecure=False
172
)
173
```
174

175
### Keystone v2.0 Authentication
176

177
```python
178
# Basic v2.0 auth
179
storage_url, token = get_auth(
180
    'https://identity.example.com:5000/v2.0',
181
    'username',
182
    'password',
183
    auth_version='2.0',
184
    os_options={'tenant_name': 'project-name'}
185
)
186

187
# v2.0 with all options
188
storage_url, token = get_auth(
189
    'https://identity.example.com:5000/v2.0',
190
    'username',
191
    'password',
192
    auth_version='2.0',
193
    os_options={
194
        'tenant_name': 'project-name',
195
        'region_name': 'us-west-2',
196
        'service_type': 'object-store',
197
        'endpoint_type': 'publicURL'
198
    }
199
)
200
```
201

202
### Keystone v3 Authentication
203

204
```python
205
# Basic v3 auth
206
storage_url, token = get_auth(
207
    'https://identity.example.com:5000/v3',
208
    'username',
209
    'password',
210
    auth_version='3',
211
    os_options={
212
        'project_name': 'project-name',
213
        'user_domain_name': 'domain-name',
214
        'project_domain_name': 'domain-name'
215
    }
216
)
217

218
# v3 with domain IDs
219
storage_url, token = get_auth(
220
    'https://identity.example.com:5000/v3',
221
    'username',
222
    'password',
223
    auth_version='3',
224
    os_options={
225
        'project_id': 'project-uuid',
226
        'user_domain_id': 'user-domain-uuid',
227
        'project_domain_id': 'project-domain-uuid'
228
    }
229
)
230

231
# v3 application credentials
232
storage_url, token = get_auth(
233
    'https://identity.example.com:5000/v3',
234
    None,  # Not required for app creds
235
    None,  # Not required for app creds
236
    auth_version='3',
237
    os_options={
238
        'auth_type': 'v3applicationcredential',
239
        'application_credential_id': 'app-credential-id',
240
        'application_credential_secret': 'app-credential-secret'
241
    }
242
)
243
```
244

245
### Session-Based Authentication
246

247
```python
248
from keystoneauth1 import session
249
from keystoneauth1.identity import v3
250

251
# Create session with v3 password auth
252
auth = v3.Password(
253
    auth_url='https://identity.example.com:5000/v3',
254
    username='username',
255
    password='password',
256
    project_name='project-name',
257
    user_domain_name='domain-name',
258
    project_domain_name='domain-name'
259
)
260
sess = session.Session(auth=auth)
261

262
# Use session for authentication
263
storage_url, token = get_auth(
264
    None,  # Not required when using session
265
    None,  # Not required when using session
266
    None,  # Not required when using session
267
    session=sess,
268
    os_options={
269
        'service_type': 'object-store',
270
        'endpoint_type': 'public',
271
        'region_name': 'us-east-1'
272
    }
273
)
274
```
275

276
### Environment Variable Authentication
277

278
```python
279
import os
280

281
# Set environment variables
282
os.environ['ST_AUTH'] = 'http://swift.example.com/auth/v1.0'
283
os.environ['ST_USER'] = 'tenant:username'
284
os.environ['ST_KEY'] = 'password'
285

286
# Or OpenStack environment variables
287
os.environ['OS_AUTH_URL'] = 'https://identity.example.com:5000/v3'
288
os.environ['OS_USERNAME'] = 'username'
289
os.environ['OS_PASSWORD'] = 'password'
290
os.environ['OS_PROJECT_NAME'] = 'project-name'
291
os.environ['OS_USER_DOMAIN_NAME'] = 'domain-name'
292
os.environ['OS_PROJECT_DOMAIN_NAME'] = 'domain-name'
293

294
# Authentication will use environment variables
295
from swiftclient.service import get_conn
296
conn = get_conn({})  # Empty options uses environment variables
297
```
298

299
### Error Handling
300

301
```python
302
from swiftclient import ClientException, get_auth
303

304
try:
305
    storage_url, token = get_auth(
306
        'https://identity.example.com:5000/v3',
307
        'username',
308
        'wrong-password',
309
        auth_version='3',
310
        os_options={'project_name': 'project-name'}
311
    )
312
except ClientException as e:
313
    print(f"Authentication failed: {e}")
314
    if e.http_status == 401:
315
        print("Invalid credentials")
316
    elif e.http_status is None:
317
        print("Connection error")
318
```
319

320
### Pre-authenticated Connections
321

322
```python
323
# Skip authentication when you already have credentials
324
from swiftclient import Connection
325

326
conn = Connection(
327
    preauthurl='https://swift.example.com/v1/AUTH_account',
328
    preauthtoken='existing-auth-token'
329
)
330

331
# Use connection without authentication step
332
headers, containers = conn.get_account()
333
```
334

335
### Advanced Authentication Classes
336

337
Specialized authentication components for legacy Swift v1 authentication and keystoneauth1 integration.
338

339
```python { .api }
340
class ServiceCatalogV1:
341
    def __init__(self, auth_url, storage_url, account):
342
        """
343
        Service catalog for Swift v1 authentication.
344

345
        Parameters:
346
        - auth_url: str, authentication endpoint URL
347
        - storage_url: str, Swift storage URL
348
        - account: str, Swift account identifier
349
        """
350

351
    @property
352
    def storage_url(self):
353
        """Get the complete storage URL with account path."""
354

355
    @property
356
    def catalog(self):
357
        """Get service catalog in OpenStack format."""
358

359
class AccessInfoV1:
360
    def __init__(self, auth_url, storage_url, account, username, auth_token,
361
                 token_lifetime=None, session=None):
362
        """
363
        Access info container for Swift v1 authentication results.
364

365
        Parameters:
366
        - auth_url: str, authentication URL used
367
        - storage_url: str, Swift storage URL
368
        - account: str, Swift account
369
        - username: str, authenticated username
370
        - auth_token: str, authentication token
371
        - token_lifetime: int, token lifetime in seconds
372
        - session: Session, keystoneauth1 session
373
        """
374

375
    @property
376
    def expires(self):
377
        """Get token expiration datetime."""
378

379
    @property
380
    def will_expire_soon(self):
381
        """Check if token will expire within 30 seconds."""
382

383
class PasswordPlugin(base.BaseIdentityPlugin):
384
    def __init__(self, auth_url, username, password, account=None):
385
        """
386
        Keystoneauth1 plugin for Swift v1 password authentication.
387

388
        Parameters:
389
        - auth_url: str, Swift v1 auth URL
390
        - username: str, username for authentication
391
        - password: str, password for authentication
392
        - account: str, Swift account override
393
        """
394

395
    def get_auth_ref(self, session, **kwargs):
396
        """Authenticate and return access info."""
397

398
    def invalidate(self):
399
        """Invalidate current authentication."""
400

401
class PasswordLoader(loading.BaseLoader):
402
    """Configuration loader for Swift v1 password authentication."""
403

404
    available_load_methods = ['password']
405

406
    def get_available_load_methods(self):
407
        """Get available authentication methods."""
408

409
    def load_from_options(self, **kwargs):
410
        """Create plugin from configuration options."""
411
```
412

413
### Advanced Swift v1 Authentication
414

415
```python
416
from keystoneauth1 import session
417
from swiftclient.authv1 import PasswordPlugin, ServiceCatalogV1, AccessInfoV1
418

419
# Use Swift v1 plugin with keystoneauth1 session
420
auth = PasswordPlugin(
421
    auth_url='https://swift.example.com/auth/v1.0',
422
    username='tenant:user',
423
    password='password'
424
)
425

426
sess = session.Session(auth=auth)
427

428
# Get service catalog
429
catalog = sess.get_access().service_catalog
430

431
# Use with Connection
432
from swiftclient import Connection
433
conn = Connection(session=sess)
434
```