Example of authenticating with kerberos (#214)

Signed-off-by: Pablo Saiz <[email protected]>

Signed-off-by: Pablo Saiz <[email protected]>
Co-authored-by: Pablo Saiz <[email protected]>
Co-authored-by: Harsha Vamsi Kalluri <[email protected]>

CHANGELOG.md

@@ -6,6 +6,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added Point in time API rest API([#191](https://github.com/opensearch-project/opensearch-py/pull/191))
 - Github workflow for changelog verification ([#218](https://github.com/opensearch-project/opensearch-py/pull/218))
 - Added overload decorators to helpers-actions.pyi-"bulk" ([#239](https://github.com/opensearch-project/opensearch-py/pull/239))
+- Document Keberos authenticaion ([214](https://github.com/opensearch-project/opensearch-py/pull/214))
 - Add release workflows ([#240](https://github.com/opensearch-project/opensearch-py/pull/240))
 ### Changed
 - Updated getting started to user guide ([#233](https://github.com/opensearch-project/opensearch-py/pull/233))

USER_GUIDE.md

@@ -1,4 +1,4 @@
-- [Getting Started with the OpenSearch Python Client](#getting-started-with-the-opensearch-python-client)
+- [Getting started with the OpenSearch Python client](#getting-started-with-the-opensearch-python-client)
   - [Setup](#setup)
   - [Sample code](#sample-code)
     - [Creating a client](#creating-a-client)
@@ -9,8 +9,8 @@
     - [Searching for a document](#searching-for-a-document)
     - [Deleting a document](#deleting-a-document)
     - [Deleting an index](#deleting-an-index)
-  - [Making API Calls](#making-api-calls)
+  - [Making API calls](#making-api-calls)
-    - [Point in Time API](#point-in-time-api-calls)
+    - [Point in time API](#point-in-time-api-calls)
   - [Using plugins](#using-plugins)
     - [Alerting plugin](#alerting-plugin)
       - [**Searching for monitors**](#searching-for-monitors)
@@ -19,10 +19,12 @@
       - [**Creating a destination**](#creating-a-destination)
       - [**Getting alerts**](#getting-alerts)
       - [**Acknowledge alerts**](#acknowledge-alerts)
-  - [Using IAM credentials for authentication](#using-iam-credentials-for-authentication)
+  - [Using different authentication methods](#using-different-authentication-methods)
+    - [Using IAM credentials](#using-iam-credentials)
       - [Pre-requisites to use `AWSV4SignerAuth`](#pre-requisites-to-use-awsv4signerauth)
+    - [Using Kerberos](#using-kerberos)
 
-# User guide of OpenSearch Python Client
+# User guide of OpenSearch Python client
 
 ## Setup
 
@@ -193,9 +195,9 @@ response = client.indices.delete(
 print('\nDeleting index:')
 print(response)
 ```
-## Making API Calls
+## Making API calls
 
-### Point in Time API
+### Point in time API
 
 ```python
 # create a point in time on a index
@@ -378,13 +380,17 @@ query = {
 response = client.plugins.alerting.acknowledge_alert(query)
 print(response)
 ```
-## Using IAM credentials for authentication
+## Using different authentication methods
+
+It is possible to use different methods for the authentication to OpenSearch. The parameters of `connection_class` and `http_auth` can be used for this. The following examples show how to authenticate using IAM credentials and using Kerberos.
+
+### Using IAM credentials
 
 Refer the AWS documentation regarding usage of IAM credentials to sign requests to OpenSearch APIs - [Signing HTTP requests to Amazon OpenSearch Service.](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/request-signing.html#request-signing-python)
 
 Opensearch-py client library also provides an in-house IAM based authentication feature, `AWSV4SignerAuth` that will help users to connect to their opensearch clusters by making use of IAM roles.
 
-#### Pre-requisites to use `AWSV4SignerAuth`
+##### Pre-requisites to use `AWSV4SignerAuth`
  - Python version 3.6 or above,
  - Install [botocore](https://pypi.org/project/botocore/) using pip
 
@@ -429,3 +435,23 @@ response = client.search(
 print('\nSearch results:')
 print(response)
 ```
+
+### Using Kerberos
+
+There are several python packages that provide Kerberos support over HTTP connections, such as [requests-kerberos](http://pypi.org/project/requests-kerberos) and [requests-gssapi](https://pypi.org/project/requests-gssapi). The following example shows how to setup the authentication. Note that some of the parameters, such as `mutual_authentication` might depend on the server settings.
+
+```python
+
+from opensearchpy import OpenSearch, RequestsHttpConnection
+from requests_kerberos import HTTPKerberosAuth, OPTIONAL
+
+client = OpenSearch(
+    ['htps://...'],
+    use_ssl=True,
+    verify_certs=True,
+    connection_class=RequestsHttpConnection,
+    http_auth=HTTPKerberosAuth(mutual_authentication=OPTIONAL)
+)
+
+health = client.cluster.health()
+```

setup.py

@@ -115,5 +115,6 @@ setup(
         "develop": tests_require + docs_require + generate_require,
         "docs": docs_require,
         "async": async_require,
+        "kerberos": ["requests_kerberos"],
     },
 )