diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d76c4c7..db9f6b32 100644 --- a/CHANGELOG.md +++ b/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)) @@ -20,4 +21,4 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ### Security -[Unreleased]: https://github.com/opensearch-project/opensearch-py/compare/2.0...HEAD \ No newline at end of file +[Unreleased]: https://github.com/opensearch-project/opensearch-py/compare/2.0...HEAD diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 3d3a777f..64025e68 100644 --- a/USER_GUIDE.md +++ b/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) - - [Point in Time API](#point-in-time-api-calls) + - [Making API calls](#making-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 @@ -428,4 +434,24 @@ response = client.search( print('\nSearch results:') print(response) -``` \ No newline at end of file +``` + +### 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() +``` diff --git a/setup.py b/setup.py index 50a01f36..a359cfb6 100644 --- a/setup.py +++ b/setup.py @@ -115,5 +115,6 @@ setup( "develop": tests_require + docs_require + generate_require, "docs": docs_require, "async": async_require, + "kerberos": ["requests_kerberos"], }, )