0
# Authentication Methods
1
2
Comprehensive authentication backend support for various identity providers, cloud platforms, and authentication systems. HVAC supports 15+ authentication methods that integrate with existing identity infrastructure and security workflows.
3
4
## Capabilities
5
6
### Token Authentication
7
8
Direct token operations including creation, renewal, revocation, and lookup for Vault's native token system.
9
10
```python { .api }
11
class Token:
12
def create(
13
self,
14
id: str = None,
15
role_name: str = None,
16
policies: list = None,
17
meta: dict = None,
18
no_parent: bool = None,
19
no_default_policy: bool = None,
20
renewable: bool = None,
21
ttl: str = None,
22
type: str = None,
23
explicit_max_ttl: str = None,
24
display_name: str = None,
25
num_uses: int = None,
26
period: str = None,
27
entity_alias: str = None,
28
wrap_ttl: str = None,
29
mount_point: str = "token"
30
) -> dict: ...
31
32
def create_orphan(self, **kwargs) -> dict: ...
33
def lookup(self, token: str = None, wrap_ttl: str = None) -> dict: ...
34
def lookup_self(self, wrap_ttl: str = None) -> dict: ...
35
def renew(self, token: str, increment: int = None, wrap_ttl: str = None) -> dict: ...
36
def renew_self(self, increment: int = None, wrap_ttl: str = None) -> dict: ...
37
def revoke(self, token: str, mount_point: str = "token") -> None: ...
38
def revoke_self(self, mount_point: str = "token") -> None: ...
39
```
40
41
### Username/Password Authentication
42
43
Traditional username and password authentication with user management capabilities.
44
45
```python { .api }
46
class Userpass:
47
def login(
48
self,
49
username: str,
50
password: str,
51
use_token: bool = True,
52
mount_point: str = "userpass"
53
) -> dict: ...
54
55
def create_or_update_user(
56
self,
57
username: str,
58
password: str = None,
59
policies: list = None,
60
**kwargs
61
) -> None: ...
62
63
def list_users(self, mount_point: str = "userpass") -> dict: ...
64
def read_user(self, username: str, mount_point: str = "userpass") -> dict: ...
65
def delete_user(self, username: str, mount_point: str = "userpass") -> None: ...
66
def update_password_on_user(
67
self,
68
username: str,
69
password: str,
70
mount_point: str = "userpass"
71
) -> None: ...
72
```
73
74
### LDAP Authentication
75
76
Enterprise LDAP integration with comprehensive directory service configuration.
77
78
```python { .api }
79
class Ldap:
80
def login(
81
self,
82
username: str,
83
password: str,
84
use_token: bool = True,
85
mount_point: str = "ldap"
86
) -> dict: ...
87
88
def configure(
89
self,
90
userdn: str = None,
91
groupdn: str = None,
92
url: str = None,
93
starttls: bool = None,
94
certificate: str = None,
95
binddn: str = None,
96
bindpass: str = None,
97
userattr: str = None,
98
groupattr: str = None,
99
**kwargs
100
) -> None: ...
101
102
def read_configuration(self, mount_point: str = "ldap") -> dict: ...
103
def create_or_update_user(
104
self,
105
username: str,
106
policies: list = None,
107
groups: list = None,
108
**kwargs
109
) -> None: ...
110
def create_or_update_group(
111
self,
112
name: str,
113
policies: list = None,
114
**kwargs
115
) -> None: ...
116
```
117
118
### AppRole Authentication
119
120
Machine-to-machine authentication using role IDs and secret IDs for automated systems.
121
122
```python { .api }
123
class AppRole:
124
def login(
125
self,
126
role_id: str,
127
secret_id: str = None,
128
use_token: bool = True,
129
mount_point: str = "approle"
130
) -> dict: ...
131
132
def create_or_update_approle(
133
self,
134
role_name: str,
135
bind_secret_id: bool = None,
136
secret_id_bound_cidrs: list = None,
137
secret_id_num_uses: int = None,
138
secret_id_ttl: str = None,
139
token_ttl: str = None,
140
token_max_ttl: str = None,
141
token_policies: list = None,
142
**kwargs
143
) -> None: ...
144
145
def read_role_id(self, role_name: str, mount_point: str = "approle") -> dict: ...
146
def generate_secret_id(
147
self,
148
role_name: str,
149
metadata: dict = None,
150
cidr_list: list = None,
151
wrap_ttl: str = None,
152
mount_point: str = "approle"
153
) -> dict: ...
154
def destroy_secret_id(
155
self,
156
role_name: str,
157
secret_id: str,
158
mount_point: str = "approle"
159
) -> None: ...
160
```
161
162
### AWS Authentication
163
164
Cloud-native authentication for AWS EC2 instances and IAM principals.
165
166
```python { .api }
167
class Aws:
168
def iam_login(
169
self,
170
access_key: str,
171
secret_key: str,
172
session_token: str = None,
173
role: str = None,
174
use_token: bool = True,
175
mount_point: str = "aws"
176
) -> dict: ...
177
178
def ec2_login(
179
self,
180
pkcs7: str,
181
role: str = None,
182
use_token: bool = True,
183
mount_point: str = "aws"
184
) -> dict: ...
185
186
def configure(
187
self,
188
access_key: str = None,
189
secret_key: str = None,
190
endpoint: str = None,
191
region: str = None,
192
**kwargs
193
) -> None: ...
194
195
def create_role(
196
self,
197
role: str,
198
role_type: str,
199
bound_ami_id: list = None,
200
bound_account_id: list = None,
201
bound_region: list = None,
202
bound_vpc_id: list = None,
203
bound_subnet_id: list = None,
204
bound_instance_id: list = None,
205
bound_iam_role_arn: list = None,
206
bound_iam_instance_profile_arn: list = None,
207
**kwargs
208
) -> None: ...
209
```
210
211
### Azure Authentication
212
213
Microsoft Azure Managed Service Identity (MSI) authentication for Azure resources.
214
215
```python { .api }
216
class Azure:
217
def login(
218
self,
219
role: str,
220
jwt: str,
221
use_token: bool = True,
222
mount_point: str = "azure"
223
) -> dict: ...
224
225
def configure(
226
self,
227
tenant_id: str,
228
resource: str,
229
client_id: str = None,
230
client_secret: str = None,
231
**kwargs
232
) -> None: ...
233
234
def create_role(
235
self,
236
name: str,
237
bound_service_principal_ids: list = None,
238
bound_resource_groups: list = None,
239
bound_locations: list = None,
240
bound_subscription_ids: list = None,
241
**kwargs
242
) -> None: ...
243
```
244
245
### Google Cloud Authentication
246
247
GCP service account JWT authentication for Google Cloud Platform resources.
248
249
```python { .api }
250
class Gcp:
251
def login(
252
self,
253
role: str,
254
jwt: str,
255
use_token: bool = True,
256
mount_point: str = "gcp"
257
) -> dict: ...
258
259
def configure(
260
self,
261
credentials: str = None,
262
google_certs_endpoint: str = None,
263
**kwargs
264
) -> None: ...
265
266
def create_role(
267
self,
268
name: str,
269
role_type: str, # "iam" or "gce"
270
project_id: str,
271
bound_service_accounts: list = None, # for iam type
272
bound_zones: list = None, # for gce type
273
bound_regions: list = None, # for gce type
274
bound_instance_groups: list = None, # for gce type
275
**kwargs
276
) -> None: ...
277
```
278
279
### Kubernetes Authentication
280
281
Kubernetes service account token authentication for containerized workloads.
282
283
```python { .api }
284
class Kubernetes:
285
def login(
286
self,
287
role: str,
288
jwt: str,
289
use_token: bool = True,
290
mount_point: str = "kubernetes"
291
) -> dict: ...
292
293
def configure(
294
self,
295
kubernetes_host: str,
296
kubernetes_ca_cert: str = None,
297
token_reviewer_jwt: str = None,
298
pem_keys: list = None,
299
**kwargs
300
) -> None: ...
301
302
def create_role(
303
self,
304
name: str,
305
bound_service_account_names: list,
306
bound_service_account_namespaces: list,
307
audience: str = None,
308
**kwargs
309
) -> None: ...
310
```
311
312
### GitHub Authentication
313
314
GitHub organization and team-based authentication using personal access tokens.
315
316
```python { .api }
317
class Github:
318
def login(
319
self,
320
token: str,
321
use_token: bool = True,
322
mount_point: str = "github"
323
) -> dict: ...
324
325
def configure(
326
self,
327
organization: str,
328
base_url: str = None,
329
ttl: str = None,
330
max_ttl: str = None,
331
**kwargs
332
) -> None: ...
333
334
def map_team(
335
self,
336
team_name: str,
337
policies: list = None,
338
mount_point: str = "github"
339
) -> None: ...
340
341
def map_user(
342
self,
343
user_name: str,
344
policies: list = None,
345
mount_point: str = "github"
346
) -> None: ...
347
```
348
349
### JWT/OIDC Authentication
350
351
JSON Web Token and OpenID Connect authentication for modern identity providers.
352
353
```python { .api }
354
class JWT:
355
def jwt_login(
356
self,
357
role: str,
358
jwt: str,
359
use_token: bool = True,
360
mount_point: str = "jwt"
361
) -> dict: ...
362
363
def configure(
364
self,
365
oidc_discovery_url: str = None,
366
jwt_validation_pubkeys: list = None,
367
bound_issuer: str = None,
368
**kwargs
369
) -> None: ...
370
371
class OIDC:
372
def oidc_authorization_url_request(
373
self,
374
role: str,
375
redirect_uri: str,
376
mount_point: str = "oidc"
377
) -> dict: ...
378
379
def oidc_callback(
380
self,
381
code: str,
382
state: str,
383
mount_point: str = "oidc"
384
) -> dict: ...
385
```
386
387
### Certificate Authentication
388
389
TLS client certificate authentication using trusted certificate authorities.
390
391
```python { .api }
392
class Cert:
393
def login(self, use_token: bool = True, mount_point: str = "cert") -> dict: ...
394
395
def create_ca_certificate_role(
396
self,
397
name: str,
398
certificate: str,
399
allowed_common_names: list = None,
400
allowed_dns_sans: list = None,
401
allowed_email_sans: list = None,
402
allowed_uri_sans: list = None,
403
**kwargs
404
) -> None: ...
405
406
def configure_tls_certificate(
407
self,
408
certificate: str = None,
409
certificate_file: str = None,
410
**kwargs
411
) -> None: ...
412
```
413
414
### Enterprise Identity Providers
415
416
Additional authentication methods for enterprise identity systems.
417
418
```python { .api }
419
class Okta:
420
def login(
421
self,
422
username: str,
423
password: str,
424
use_token: bool = True,
425
mount_point: str = "okta"
426
) -> dict: ...
427
428
def configure(
429
self,
430
org_name: str,
431
api_token: str = None,
432
base_url: str = None,
433
bypass_okta_mfa: bool = None,
434
**kwargs
435
) -> None: ...
436
437
class Radius:
438
def login(
439
self,
440
username: str,
441
password: str,
442
use_token: bool = True,
443
mount_point: str = "radius"
444
) -> dict: ...
445
446
def configure(
447
self,
448
host: str,
449
secret: str,
450
port: int = None,
451
dial_timeout: int = None,
452
**kwargs
453
) -> None: ...
454
```
455
456
## Usage Examples
457
458
### AppRole Authentication (Recommended for Applications)
459
460
```python
461
import hvac
462
463
client = hvac.Client(url='https://vault.example.com:8200')
464
465
# Configure AppRole
466
client.auth.approle.create_or_update_approle(
467
role_name='myapp',
468
token_policies=['myapp-policy'],
469
token_ttl='1h',
470
token_max_ttl='4h'
471
)
472
473
# Get role ID (usually done during deployment)
474
role_id_response = client.auth.approle.read_role_id('myapp')
475
role_id = role_id_response['data']['role_id']
476
477
# Generate secret ID (usually done during application startup)
478
secret_response = client.auth.approle.generate_secret_id('myapp')
479
secret_id = secret_response['data']['secret_id']
480
481
# Authenticate application
482
auth_response = client.auth.approle.login(
483
role_id=role_id,
484
secret_id=secret_id
485
)
486
print(f"Authenticated successfully, token TTL: {auth_response['auth']['lease_duration']}")
487
```
488
489
### Kubernetes Authentication
490
491
```python
492
import hvac
493
494
client = hvac.Client(url='https://vault.example.com:8200')
495
496
# Configure Kubernetes auth (admin operation)
497
client.auth.kubernetes.configure(
498
kubernetes_host='https://kubernetes.default.svc.cluster.local',
499
kubernetes_ca_cert=open('/var/run/secrets/kubernetes.io/serviceaccount/ca.crt').read()
500
)
501
502
# Create role for service account
503
client.auth.kubernetes.create_role(
504
name='myapp-role',
505
bound_service_account_names=['myapp-sa'],
506
bound_service_account_namespaces=['production'],
507
token_policies=['myapp-policy'],
508
token_ttl='1h'
509
)
510
511
# Authenticate from pod
512
jwt_token = open('/var/run/secrets/kubernetes.io/serviceaccount/token').read()
513
auth_response = client.auth.kubernetes.login(
514
role='myapp-role',
515
jwt=jwt_token
516
)
517
```
518
519
### LDAP Authentication
520
521
```python
522
import hvac
523
524
client = hvac.Client(url='https://vault.example.com:8200')
525
526
# Configure LDAP (admin operation)
527
client.auth.ldap.configure(
528
url='ldaps://ldap.company.com',
529
userdn='ou=users,dc=company,dc=com',
530
groupdn='ou=groups,dc=company,dc=com',
531
userattr='uid',
532
groupattr='memberUid'
533
)
534
535
# Map LDAP groups to policies
536
client.auth.ldap.create_or_update_group(
537
name='developers',
538
policies=['developer-policy']
539
)
540
541
# User authentication
542
auth_response = client.auth.ldap.login(
543
username='john.doe',
544
password='user_password'
545
)
546
```
547
548
### AWS IAM Authentication
549
550
```python
551
import hvac
552
import boto3
553
554
client = hvac.Client(url='https://vault.example.com:8200')
555
556
# Configure AWS auth (admin operation)
557
client.auth.aws.configure(
558
access_key='aws_access_key',
559
secret_key='aws_secret_key',
560
region='us-east-1'
561
)
562
563
# Create role for EC2 instances
564
client.auth.aws.create_role(
565
role='ec2-role',
566
role_type='ec2',
567
bound_ami_id=['ami-12345678'],
568
bound_account_id=['123456789012'],
569
token_policies=['ec2-policy']
570
)
571
572
# Authenticate from EC2 instance
573
import requests
574
pkcs7_response = requests.get(
575
'http://169.254.169.254/latest/dynamic/instance-identity/pkcs7',
576
timeout=2
577
)
578
auth_response = client.auth.aws.ec2_login(
579
pkcs7=pkcs7_response.text,
580
role='ec2-role'
581
)
582
```