0
# Authentication
1

2
Comprehensive authentication support for HashiCorp Vault with multiple authentication methods. The provider supports all major Vault authentication backends with flexible configuration options for different deployment scenarios.
3

4
## Capabilities
5

6
### Supported Authentication Methods
7

8
The provider supports the following authentication methods with their corresponding configuration parameters:
9

10
```python { .api }
11
SUPPORTED_AUTH_TYPES = [
12
    "token",        # Token-based authentication
13
    "approle",      # AppRole authentication
14
    "github",       # GitHub authentication  
15
    "gcp",          # Google Cloud Platform authentication
16
    "kubernetes",   # Kubernetes service account authentication
17
    "ldap",         # LDAP authentication
18
    "userpass",     # Username/password authentication
19
    "aws_iam",      # AWS IAM authentication
20
    "azure",        # Azure Active Directory authentication
21
    "radius"        # RADIUS authentication
22
]
23
```
24

25
### Token Authentication
26

27
Direct token-based authentication using Vault tokens.
28

29
```python { .api }
30
# Via token parameter
31
VaultHook(
32
    vault_conn_id='vault_conn',
33
    auth_type='token',
34
    token='your-vault-token'
35
)
36

37
# Via token file
38
VaultHook(
39
    vault_conn_id='vault_conn', 
40
    auth_type='token',
41
    token_path='/path/to/token/file'
42
)
43
```
44

45
**Parameters:**
46
- `token` (str): Direct token value
47
- `token_path` (str): Path to file containing token
48

49
### AppRole Authentication
50

51
AppRole authentication for applications and services.
52

53
```python { .api }
54
VaultHook(
55
    vault_conn_id='vault_conn',
56
    auth_type='approle',
57
    role_id='12345678-1234-1234-1234-123456789012',
58
    secret_id='abcdef12-3456-7890-abcd-ef1234567890',
59
    auth_mount_point='approle'  # Optional, default: 'approle'
60
)
61
```
62

63
**Parameters:**
64
- `role_id` (str): AppRole role ID
65
- `secret_id` (str): AppRole secret ID  
66
- `auth_mount_point` (str): Mount point for AppRole auth method
67

68
### Kubernetes Authentication
69

70
Authentication using Kubernetes service account tokens.
71

72
```python { .api }
73
VaultHook(
74
    vault_conn_id='vault_conn',
75
    auth_type='kubernetes',
76
    kubernetes_role='airflow-role',
77
    kubernetes_jwt_path='/var/run/secrets/kubernetes.io/serviceaccount/token',
78
    auth_mount_point='kubernetes'  # Optional, default: 'kubernetes'
79
)
80
```
81

82
**Parameters:**
83
- `kubernetes_role` (str): Kubernetes role bound to service account
84
- `kubernetes_jwt_path` (str): Path to JWT token file
85
- `auth_mount_point` (str): Mount point for Kubernetes auth method
86

87
### AWS IAM Authentication
88

89
Authentication using AWS IAM credentials with optional assume role support.
90

91
```python { .api }
92
VaultHook(
93
    vault_conn_id='vault_conn',
94
    auth_type='aws_iam',
95
    role_id='vault-role',
96
    key_id='AKIAIOSFODNN7EXAMPLE',  # From connection login
97
    secret_id='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',  # From connection password
98
    region='us-east-1',
99
    assume_role_kwargs={
100
        'RoleArn': 'arn:aws:iam::123456789012:role/VaultRole',
101
        'RoleSessionName': 'airflow-vault-session'
102
    }
103
)
104
```
105

106
**Parameters:**
107
- `role_id` (str): Vault role for IAM authentication
108
- `key_id` (str): AWS access key ID
109
- `secret_id` (str): AWS secret access key
110
- `region` (str): AWS region for STS calls
111
- `assume_role_kwargs` (dict): Parameters for STS assume role
112

113
### Google Cloud Authentication
114

115
Authentication using Google Cloud Platform service accounts.
116

117
```python { .api }
118
# Using key file path
119
VaultHook(
120
    vault_conn_id='vault_conn',
121
    auth_type='gcp',
122
    gcp_key_path='/path/to/service-account.json',
123
    gcp_scopes='https://www.googleapis.com/auth/cloud-platform'
124
)
125

126
# Using key dictionary
127
VaultHook(
128
    vault_conn_id='vault_conn',
129
    auth_type='gcp', 
130
    gcp_keyfile_dict={
131
        'type': 'service_account',
132
        'project_id': 'my-project',
133
        'private_key_id': '...',
134
        'private_key': '...',
135
        'client_email': 'service@my-project.iam.gserviceaccount.com',
136
        'client_id': '...'
137
    }
138
)
139
```
140

141
**Parameters:**
142
- `gcp_key_path` (str): Path to service account JSON key file
143
- `gcp_keyfile_dict` (dict): Service account key as dictionary
144
- `gcp_scopes` (str): OAuth2 scopes (comma-separated)
145

146
### Azure Active Directory Authentication
147

148
Authentication using Azure AD service principals.
149

150
```python { .api }
151
VaultHook(
152
    vault_conn_id='vault_conn',
153
    auth_type='azure',
154
    azure_tenant_id='12345678-1234-1234-1234-123456789012',
155
    key_id='client-id',  # Client ID
156
    secret_id='client-secret',  # Client secret
157
    azure_resource='https://vault.hashicorp.com'
158
)
159
```
160

161
**Parameters:**
162
- `azure_tenant_id` (str): Azure AD tenant ID
163
- `key_id` (str): Azure application client ID
164
- `secret_id` (str): Azure application client secret
165
- `azure_resource` (str): Resource URL for the application
166

167
### LDAP Authentication
168

169
Authentication using LDAP credentials.
170

171
```python { .api }
172
VaultHook(
173
    vault_conn_id='vault_conn',
174
    auth_type='ldap',
175
    username='john.doe',  # From connection login
176
    password='ldap_password',  # From connection password
177
    auth_mount_point='ldap'  # Optional, default: 'ldap'
178
)
179
```
180

181
**Parameters:**
182
- `username` (str): LDAP username
183
- `password` (str): LDAP password
184
- `auth_mount_point` (str): Mount point for LDAP auth method
185

186
### Username/Password Authentication
187

188
Authentication using Vault's userpass auth method.
189

190
```python { .api }
191
VaultHook(
192
    vault_conn_id='vault_conn',
193
    auth_type='userpass',
194
    username='vault_user',  # From connection login
195
    password='vault_password',  # From connection password
196
    auth_mount_point='userpass'  # Optional, default: 'userpass'
197
)
198
```
199

200
**Parameters:**
201
- `username` (str): Vault username
202
- `password` (str): Vault password
203
- `auth_mount_point` (str): Mount point for userpass auth method
204

205
### GitHub Authentication
206

207
Authentication using GitHub personal access tokens.
208

209
```python { .api }
210
VaultHook(
211
    vault_conn_id='vault_conn',
212
    auth_type='github',
213
    token='github_personal_access_token',  # From connection password
214
    auth_mount_point='github'  # Optional, default: 'github'
215
)
216
```
217

218
**Parameters:**
219
- `token` (str): GitHub personal access token
220
- `auth_mount_point` (str): Mount point for GitHub auth method
221

222
### RADIUS Authentication
223

224
Authentication using RADIUS protocol.
225

226
```python { .api }
227
VaultHook(
228
    vault_conn_id='vault_conn',
229
    auth_type='radius',
230
    username='radius_user',  # From connection login
231
    radius_secret='shared_secret',
232
    radius_host='radius.example.com',
233
    radius_port=1812  # Optional, default: 1812
234
)
235
```
236

237
**Parameters:**
238
- `username` (str): RADIUS username
239
- `radius_secret` (str): RADIUS shared secret
240
- `radius_host` (str): RADIUS server hostname
241
- `radius_port` (int): RADIUS server port
242

243
## Connection Configuration
244

245
### Connection Parameters
246

247
Authentication parameters can be configured via Airflow connections using the `extra` field:
248

249
```json
250
{
251
  "auth_type": "kubernetes",
252
  "kubernetes_role": "airflow-prod",
253
  "auth_mount_point": "k8s",
254
  "kv_engine_version": 2
255
}
256
```
257

258
### URL Scheme Examples
259

260
Vault connection URLs support various authentication schemes:
261

262
```python
263
# Token authentication
264
vault://user:token@vault.example.com:8200/secret?auth_type=token
265

266
# AppRole authentication  
267
vault://role_id:secret_id@vault.example.com:8200/secret?auth_type=approle
268

269
# Kubernetes authentication
270
vault://service-account:@vault.example.com:8200/secret?auth_type=kubernetes&kubernetes_role=airflow
271

272
# AWS IAM authentication
273
vault://access_key:secret_key@vault.example.com:8200/secret?auth_type=aws_iam&role_id=vault-role
274
```
275

276
## Mount Point Configuration
277

278
Each authentication method can use a custom mount point. The following are the default mount points used by the authentication methods:
279

280
```python { .api }
281
# Authentication methods use these default mount points when auth_mount_point is not specified
282
# These defaults are handled internally by the hvac library
283
DEFAULT_MOUNT_POINTS = {
284
    'approle': 'approle',
285
    'aws_iam': 'aws', 
286
    'azure': 'azure',
287
    'gcp': 'gcp',
288
    'github': 'github',
289
    'kubernetes': 'kubernetes',
290
    'ldap': 'ldap',
291
    'radius': 'radius',
292
    'token': None,  # Token auth does not use a mount point
293
    'userpass': 'userpass'
294
}
295
```
296

297
Override default mount points with the `auth_mount_point` parameter:
298

299
```python
300
VaultHook(
301
    auth_type='kubernetes',
302
    auth_mount_point='k8s-prod',  # Custom mount point
303
    kubernetes_role='airflow-role'
304
)
305
```
306

307
## Error Handling
308

309
Authentication failures raise appropriate exceptions:
310

311
- **VaultError**: General Vault authentication failures
312
- **ConnectionError**: Network connectivity issues
313
- **PermissionError**: Insufficient Vault permissions
314
- **ConfigurationError**: Invalid authentication configuration
315

316
Handle authentication errors gracefully:
317

318
```python
319
from hvac.exceptions import VaultError
320

321
try:
322
    hook = VaultHook(vault_conn_id='vault_default')
323
    secret = hook.get_secret('path/to/secret')
324
except VaultError as e:
325
    print(f"Vault authentication failed: {e}")
326
except Exception as e:
327
    print(f"Unexpected error: {e}")
328
```