ElasticSearch

1 Connecting to Amazon OpenSearch Service

Set the following to connect to data:

• Server should be set to the Endpoint URL for the Amazon ES instance.

• Port should be set to 443.

• AWSRegion should be set to the Amazon AWS region where the Elasticsearch instance is being hosted (the provider will attempt to automatically identify the region based on the Server value).

The provider uses X-Pack Security for authentication and TLS/SSL encryption.

Note: Requests are signed using AWS Signature Version 4.

2 Authenticating to Elasticsearch

In addition to standard connection properties, select one of the below authentication methods to authenticate.

2.1 Obtaining the Access Key

To obtain the credentials for an IAM user, follow the steps below:

1. Sign into the IAM console.

2. In the navigation pane, select Users.

3. To create or manage the access keys for a user, select the user and then select the Security Credentials tab.

To obtain the credentials for your AWS root account, follow the steps below:

1. Sign into the AWS Management console with the credentials for your root account.

2. Select your account name or number and select My Security Credentials in the menu that is displayed.

3. Click Continue to Security Credentials and expand the Access Keys section to manage or create root account access keys.

2.2 Authenticating Using Standard Authentication

Set the AuthScheme to Basic, and set User and Password properties and/or use PKI (public key infrastructure) to authenticate. Once the provider is connected, X-Pack performs user authentication and grants role permissions based on the realms you have configured.

To use PKI, set the SSLClientCert, SSLClientCertType, SSLClientCertSubject, and SSLClientCertPassword properties.

Note: TLS/SSL and client authentication must be enabled on X-Pack to use PKI.

2.3 Securing Elasticsearch Connections

To enable TLS/SSL in the provider, prefix the Server value with 'https://'.

2.4 Authenticating with Root Credentials

To authenticate using account root credentials, set the following:

• AuthScheme: Set this to AwsRootKeys.

• AWSAccessKey: The access key associated with the AWS root account.

• AWSSecretKey: The secret key associated with the AWS root account.

Note: Use of this authentication scheme is discouraged by Amazon for anything but simple tests. The account root credentials have the full permissions of the user, making this the least secure authentication method.

2.5 Authenticating with Temporary Credentials

To authenticate using temporary credentials, specify the following:

• AuthScheme: Set this to TemporaryCredentials.

• AWSAccessKey: The access key of the IAM user to assume the role for.

• AWSSecretKey: The secret key of the IAM user to assume the role for.

• AWSSessionToken: Your AWS session token. This will have been provided alongside your temporary credentials. See this link for more info.

The provider can now request resources using the same permissions provided by long-term credentials (such as IAM user credentials) for the lifespan of the temporary credentials.

If you are also using an IAM role to authenticate, you must additionally specify the following:

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the provider to attempt to retrieve credentials for the specified role.

• AWSExternalId: Only if required when you assume a role in another account.

2.6 Authenticating as an AWS Role

In many situations it may be preferable to use an IAM role for authentication instead of the direct security credentials of an AWS root user.

To authenticate as an AWS role, set the following:

• AuthScheme: Set this to AwsIAMRoles.

• AWSRoleARN: Specify the Role ARN for the role you'd like to authenticate with. This will cause the provider to attempt to retrieve credentials for the specified role.

• AWSExternalId: Only if required when you assume a role in another account.

• AWSAccessKey: The access key of the IAM user to assume the role for.

• AWSSecretKey: The secret key of the IAM user to assume the role for.

Note: Roles may not be used when specifying the AWSAccessKey and AWSSecretKey of an AWS root user.

2.7 Authenticating with Kerberos

To authenticate to Elasticsearch using Kerberos, set the following properties:

• AuthScheme: Set this to KERBEROS

• KerberosKDC: Set this to the host name or IP Address of your Kerberos KDC machine.

• KerberosSPN: Set this to the service and host of the Elasticsearch Kerberos Principal. This will be the value prior to the '@' symbol (for instance, HTTP/MyHost) of the principal value (for instance, HTTP/[e-mail]).

2.7.1 Retrieve the Kerberos Ticket

You can use one of the following options to retrieve the required Kerberos ticket.

2.7.2 MIT Kerberos Credential Cache File

This option enables you to use the MIT Kerberos Ticket Manager or kinit command to get tickets. Note that you won't need to set the User or Password connection properties with this option.

1. Ensure that you have an environment variable created called KRB5CCNAME.

2. Set the KRB5CCNAME environment variable to a path pointing to your credential cache file (for instance, C:\krb_cache\krb5cc_0 or /tmp/krb5cc_0). This file will be created when generating your ticket with MIT Kerberos Ticket Manager.

3. To obtain a ticket, open the MIT Kerberos Ticket Manager application, click Get Ticket, enter your principal name and password, then click OK. If successful, ticket information will appear in Kerberos Ticket Manager and will now be stored in the credential cache file.

4. Now that the credential cache file has been created, the provider will use the cache file to obtain the kerberos ticket to connect to Elasticsearch.

As an alternative to setting the KRB5CCNAME environment variable, you can directly set the file path using the KerberosTicketCache property. When set, the provider will use the specified cache file to obtain the kerberos ticket to connect to Elasticsearch.

2.7.3 Keytab File

If the KRB5CCNAME environment variable has not been set, you can retrieve a Kerberos ticket using a Keytab File. To do this, set the User property to the desired username and set the KerberosKeytabFile property to a file path pointing to the keytab file associated with the user.

2.7.4 User and Password

If both the KRB5CCNAME environment variable and the KerberosKeytabFile property have not been set, you can retrieve a ticket using a User and Password combination. To do this, set the User and Password properties to the user/password combo that you use to authenticate with Elasticsearch.

2.7.5 Cross-Realm Authentication

More complex Kerberos environments may require cross-realm authentication where multiple realms and KDC servers are used (e.g. where one realm/KDC is used for user authentication and another realm/KDC used for obtaining the service ticket).

In such an environment, the KerberosRealm and KerberosKDC properties can be set to the values required for user authentication. The KerberosServiceRealm and KerberosServiceKDC properties can be set to the values required to obtain the service ticket.

2.8 Authenticating with APIKey

To authenticate using APIKey set the following:

• AuthScheme: Set this to APIKey.

• APIKey: Set this to APIKey returned from Elasticsearch.

• APIKeyId: Set this to the Id returned alongside APIKey.