0
# Authentication and Security
1

2
Authentication mechanisms and security features for secure connections to OpenSearch clusters, including AWS IAM integration, SSL/TLS configuration, and credential management.
3

4
## Capabilities
5

6
### AWS IAM Authentication
7

8
AWS Signature Version 4 authentication for OpenSearch Service and self-managed clusters.
9

10
```python { .api }
11
class RequestsAWSV4SignerAuth:
12
    def __init__(self, credentials, region, service='es'):
13
        """
14
        AWS V4 signature authentication for requests-based connections.
15
        
16
        Parameters:
17
        - credentials: AWS credentials (boto3 credentials object)
18
        - region (str): AWS region
19
        - service (str): AWS service name (default: 'es')
20
        """
21

22
class Urllib3AWSV4SignerAuth:
23
    def __init__(self, credentials, region, service='es'):
24
        """
25
        AWS V4 signature authentication for urllib3-based connections.
26
        
27
        Parameters:
28
        - credentials: AWS credentials (boto3 credentials object)
29
        - region (str): AWS region
30
        - service (str): AWS service name (default: 'es')
31
        """
32

33
class AWSV4SignerAsyncAuth:
34
    def __init__(self, credentials, region, service='es'):
35
        """
36
        AWS V4 signature authentication for async connections.
37
        
38
        Parameters:
39
        - credentials: AWS credentials (boto3 credentials object)
40
        - region (str): AWS region
41
        - service (str): AWS service name (default: 'es')
42
        """
43
```
44

45
### Client Authentication Configuration
46

47
Authentication options available during client initialization.
48

49
```python { .api }
50
class OpenSearch:
51
    def __init__(
52
        self,
53
        hosts=None,
54
        http_auth=None,
55
        use_ssl=False,
56
        verify_certs=True,
57
        ssl_context=None,
58
        ssl_show_warn=True,
59
        ssl_assert_hostname=None,
60
        ssl_assert_fingerprint=None,
61
        ca_certs=None,
62
        client_cert=None,
63
        client_key=None,
64
        **kwargs
65
    ):
66
        """
67
        Initialize OpenSearch client with authentication and SSL settings.
68
        
69
        Authentication Parameters:
70
        - http_auth (tuple/callable): HTTP authentication (username, password) or auth handler
71
        - use_ssl (bool): Use HTTPS connections (default: False)
72
        - verify_certs (bool): Verify SSL certificates (default: True)
73
        - ssl_context: Custom SSL context
74
        - ssl_show_warn (bool): Show SSL warnings (default: True)
75
        - ssl_assert_hostname (str/bool): Assert SSL hostname
76
        - ssl_assert_fingerprint (str): Assert SSL certificate fingerprint
77
        - ca_certs (str): Path to CA certificate bundle
78
        - client_cert (str): Path to client certificate
79
        - client_key (str): Path to client private key
80
        """
81
```
82

83
### SSL/TLS Configuration
84

85
Secure connection configuration options.
86

87
```python { .api }
88
import ssl
89
from opensearchpy import OpenSearch
90

91
# Custom SSL context
92
ssl_context = ssl.create_default_context()
93
ssl_context.check_hostname = False
94
ssl_context.verify_mode = ssl.CERT_NONE
95

96
client = OpenSearch(
97
    hosts=[{'host': 'localhost', 'port': 9200}],
98
    use_ssl=True,
99
    ssl_context=ssl_context
100
)
101
```
102

103
## Usage Examples
104

105
### Basic HTTP Authentication
106

107
```python
108
from opensearchpy import OpenSearch
109

110
# Basic username/password authentication
111
client = OpenSearch(
112
    hosts=[{'host': 'localhost', 'port': 9200}],
113
    http_auth=('username', 'password'),
114
    use_ssl=True,
115
    verify_certs=True
116
)
117

118
# Test authentication
119
response = client.info()
120
print(f"Cluster: {response['cluster_name']}")
121
```
122

123
### AWS OpenSearch Service Authentication
124

125
```python
126
import boto3
127
from opensearchpy import OpenSearch, RequestsAWSV4SignerAuth
128

129
# Get AWS credentials from default credential chain
130
credentials = boto3.Session().get_credentials()
131
auth = RequestsAWSV4SignerAuth(credentials, 'us-east-1')
132

133
# Create client with AWS authentication
134
client = OpenSearch(
135
    hosts=[{'host': 'my-domain.us-east-1.es.amazonaws.com', 'port': 443}],
136
    http_auth=auth,
137
    use_ssl=True,
138
    verify_certs=True,
139
    ssl_assert_hostname=False,
140
    ssl_show_warn=False
141
)
142

143
# Test connection
144
response = client.cluster.health()
145
print(f"Cluster status: {response['status']}")
146
```
147

148
### AWS with Custom Credentials
149

150
```python
151
import boto3
152
from botocore.credentials import Credentials
153
from opensearchpy import OpenSearch, RequestsAWSV4SignerAuth
154

155
# Create custom credentials
156
credentials = Credentials(
157
    access_key='AKIAIOSFODNN7EXAMPLE',
158
    secret_key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
159
    token='session-token'  # Optional for temporary credentials
160
)
161

162
auth = RequestsAWSV4SignerAuth(credentials, 'us-west-2', service='es')
163

164
client = OpenSearch(
165
    hosts=[{'host': 'search-mydomain.us-west-2.es.amazonaws.com', 'port': 443}],
166
    http_auth=auth,
167
    use_ssl=True,
168
    verify_certs=True
169
)
170
```
171

172
### Client Certificate Authentication
173

174
```python
175
from opensearchpy import OpenSearch
176

177
# Client certificate authentication
178
client = OpenSearch(
179
    hosts=[{'host': 'secure-cluster.example.com', 'port': 9200}],
180
    use_ssl=True,
181
    verify_certs=True,
182
    ca_certs='/path/to/ca-bundle.crt',
183
    client_cert='/path/to/client.crt',
184
    client_key='/path/to/client.key',
185
    ssl_assert_hostname=True
186
)
187

188
# Test secure connection
189
response = client.ping()
190
print(f"Connection successful: {response}")
191
```
192

193
### Custom SSL Context
194

195
```python
196
import ssl
197
from opensearchpy import OpenSearch
198

199
# Create custom SSL context
200
ssl_context = ssl.create_default_context()
201
ssl_context.minimum_version = ssl.TLSVersion.TLSv1_2
202
ssl_context.set_ciphers('ECDHE+AESGCM:ECDHE+CHACHA20:DHE+AESGCM:DHE+CHACHA20:!aNULL:!MD5:!DSS')
203

204
# Load custom CA certificate
205
ssl_context.load_verify_locations('/path/to/custom-ca.pem')
206

207
# Load client certificate
208
ssl_context.load_cert_chain('/path/to/client.crt', '/path/to/client.key')
209

210
client = OpenSearch(
211
    hosts=[{'host': 'secure-cluster.example.com', 'port': 9200}],
212
    use_ssl=True,
213
    ssl_context=ssl_context
214
)
215
```
216

217
### Environment-Based Configuration
218

219
```python
220
import os
221
from opensearchpy import OpenSearch
222

223
# Configuration from environment variables
224
host = os.getenv('OPENSEARCH_HOST', 'localhost')
225
port = int(os.getenv('OPENSEARCH_PORT', '9200'))
226
username = os.getenv('OPENSEARCH_USERNAME')
227
password = os.getenv('OPENSEARCH_PASSWORD')
228
use_ssl = os.getenv('OPENSEARCH_USE_SSL', 'false').lower() == 'true'
229

230
auth = (username, password) if username and password else None
231

232
client = OpenSearch(
233
    hosts=[{'host': host, 'port': port}],
234
    http_auth=auth,
235
    use_ssl=use_ssl,
236
    verify_certs=use_ssl,
237
    ssl_show_warn=False
238
)
239
```
240

241
### Multiple Authentication Methods
242

243
```python
244
from opensearchpy import OpenSearch
245

246
class MultiAuthClient:
247
    def __init__(self):
248
        self.clients = {}
249
    
250
    def add_basic_auth_client(self, name, host, username, password):
251
        """Add client with basic authentication."""
252
        self.clients[name] = OpenSearch(
253
            hosts=[{'host': host, 'port': 9200}],
254
            http_auth=(username, password),
255
            use_ssl=True,
256
            verify_certs=True
257
        )
258
    
259
    def add_aws_client(self, name, host, region):
260
        """Add client with AWS authentication."""
261
        import boto3
262
        from opensearchpy import RequestsAWSV4SignerAuth
263
        
264
        credentials = boto3.Session().get_credentials()
265
        auth = RequestsAWSV4SignerAuth(credentials, region)
266
        
267
        self.clients[name] = OpenSearch(
268
            hosts=[{'host': host, 'port': 443}],
269
            http_auth=auth,
270
            use_ssl=True,
271
            verify_certs=True
272
        )
273
    
274
    def get_client(self, name):
275
        """Get client by name."""
276
        return self.clients.get(name)
277

278
# Usage
279
auth_manager = MultiAuthClient()
280
auth_manager.add_basic_auth_client('local', 'localhost', 'admin', 'admin')
281
auth_manager.add_aws_client('aws', 'search-domain.us-east-1.es.amazonaws.com', 'us-east-1')
282

283
local_client = auth_manager.get_client('local')
284
aws_client = auth_manager.get_client('aws')
285
```
286

287
### Connection Pool with Authentication
288

289
```python
290
from opensearchpy import OpenSearch
291
from opensearchpy.connection import create_ssl_context
292

293
# Multiple hosts with authentication
294
hosts = [
295
    {'host': 'node1.cluster.com', 'port': 9200},
296
    {'host': 'node2.cluster.com', 'port': 9200},
297
    {'host': 'node3.cluster.com', 'port': 9200}
298
]
299

300
# Custom SSL context for all connections
301
ssl_context = create_ssl_context(
302
    cafile='/path/to/ca.pem',
303
    certfile='/path/to/client.crt',
304
    keyfile='/path/to/client.key'
305
)
306

307
client = OpenSearch(
308
    hosts=hosts,
309
    http_auth=('cluster_user', 'cluster_password'),
310
    use_ssl=True,
311
    ssl_context=ssl_context,
312
    # Connection pool settings
313
    maxsize=25,
314
    max_retries=3,
315
    retry_on_timeout=True,
316
    # Health check settings
317
    sniff_on_start=True,
318
    sniff_on_connection_fail=True,
319
    sniffer_timeout=60
320
)
321
```
322

323
### Async Authentication
324

325
```python
326
import asyncio
327
import boto3
328
from opensearchpy import AsyncOpenSearch, AWSV4SignerAsyncAuth
329

330
async def async_auth_example():
331
    # AWS async authentication
332
    credentials = boto3.Session().get_credentials()
333
    auth = AWSV4SignerAsyncAuth(credentials, 'us-east-1')
334
    
335
    client = AsyncOpenSearch(
336
        hosts=[{'host': 'search-domain.us-east-1.es.amazonaws.com', 'port': 443}],
337
        http_auth=auth,
338
        use_ssl=True,
339
        verify_certs=True
340
    )
341
    
342
    try:
343
        # Test async connection
344
        response = await client.info()
345
        print(f"Async connection successful: {response['cluster_name']}")
346
        
347
        # Perform async operations
348
        health = await client.cluster.health()
349
        print(f"Cluster health: {health['status']}")
350
        
351
    finally:
352
        await client.close()
353

354
# Run async example
355
asyncio.run(async_auth_example())
356
```
357

358
### Custom Authentication Handler
359

360
```python
361
from opensearchpy import OpenSearch
362
import requests
363

364
class CustomTokenAuth:
365
    def __init__(self, token_url, client_id, client_secret):
366
        self.token_url = token_url
367
        self.client_id = client_id
368
        self.client_secret = client_secret
369
        self.token = None
370
        self.token_expires = 0
371
    
372
    def get_token(self):
373
        """Get or refresh access token."""
374
        import time
375
        
376
        if self.token and time.time() < self.token_expires:
377
            return self.token
378
        
379
        # Request new token
380
        response = requests.post(self.token_url, {
381
            'grant_type': 'client_credentials',
382
            'client_id': self.client_id,
383
            'client_secret': self.client_secret
384
        })
385
        
386
        token_data = response.json()
387
        self.token = token_data['access_token']
388
        self.token_expires = time.time() + token_data['expires_in'] - 60
389
        
390
        return self.token
391
    
392
    def __call__(self, r):
393
        """Add authorization header to request."""
394
        token = self.get_token()
395
        r.headers['Authorization'] = f'Bearer {token}'
396
        return r
397

398
# Use custom authentication
399
auth = CustomTokenAuth(
400
    token_url='https://oauth.example.com/token',
401
    client_id='your-client-id',
402
    client_secret='your-client-secret'
403
)
404

405
client = OpenSearch(
406
    hosts=[{'host': 'secure-cluster.example.com', 'port': 9200}],
407
    http_auth=auth,
408
    use_ssl=True,
409
    verify_certs=True
410
)
411
```