From 0ab79cbdb61f3e26eda6b8c25e06a7b7a3ac9f1b Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 8 Dec 2021 15:00:01 -0800 Subject: [PATCH 1/5] Added security instructions to Java clients Signed-off-by: keithhc2 --- _clients/java-rest-high-level.md | 33 +++- _clients/java.md | 149 +++++++++++++++++- .../audit-logs/field-reference.md | 2 +- _security-plugin/audit-logs/storage-types.md | 2 +- 4 files changed, 175 insertions(+), 11 deletions(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index df0c298b..951563db 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -6,9 +6,6 @@ nav_order: 60 # Java high-level REST client -Although the OpenSearch Java high-level REST client is still usable, we recommend that you use the [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/), which replaces the existing Java high-level REST client. -{: .note} - The OpenSearch Java high-level REST client lets you interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON. ## Setup @@ -25,7 +22,33 @@ To start using the OpenSearch Java high-level REST client, ensure that you have You can now start your OpenSearch cluster. The OpenSearch 1.x high-level REST client works with the 1.x versions of OpenSearch. -The following example uses credentials that come with the default OpenSearch configuration. If you’re using the high-level REST client with your own OpenSearch cluster, be sure to change the code to use your own credentials. +## Security + +This code example uses basic credentials that come with the default OpenSearch configuration. If you’re using the OpenSearch Java high-level REST client with your own OpenSearch cluster, be sure to change the code to use your own credentials. +{: .note} + +Before you can securely connect to an OpenSearch cluster, you need to first add your root certificates to a truststore: + +```bash +keytool -import -alias -keystore +``` + +You can now point your Java client to the truststore and set basic authentication credentials that can access a secure cluster. + +```java +//Point to keystore with appropriate certificates for security. +System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore"); +System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore"); + +//Establish credentials to use basic authentication. +//Only for demo purposes. Don't specify your credentials in code. +final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); +credentialsProvider.setCredentials(AuthScope.ANY, + new UsernamePasswordCredentials("admin", "admin")); +``` + +If you run into issues when configuring security, see [common issues]({{site.url}}{{site.baseurl}}/troubleshoot/index) and [troubleshoot TLS]({{site.url}}{{site.baseurl}}/troubleshoot/tls). + ## Sample code @@ -64,7 +87,7 @@ public class RESTClientSample { System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore"); //Establish credentials to use basic authentication. - //Only for demo purposes. Do not specify your credentials in code. + //Only for demo purposes. Don't specify your credentials in code. final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); credentialsProvider.setCredentials(AuthScope.ANY, diff --git a/_clients/java.md b/_clients/java.md index c80870e0..ca88908d 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -6,11 +6,14 @@ nav_order: 65 # Java client +The OpenSearch Java client is currently in its beta phase, so we recommend that you use the [OpenSearch Java high-level REST client]({{site.url}}{{site.baseurl}}/clients/java-rest-high-level). +{: .note} + The OpenSearch Java client allows you to interact with your OpenSearch clusters through Java methods and data structures rather than HTTP methods and raw JSON. For example, you can submit requests to your cluster using objects to create indices, add data to documents, or complete some other operation using the client's built-in methods. -## Setup +## Install the client To start using the OpenSearch Java client, ensure that you have the following dependencies in your project's `pom.xml` file: @@ -38,9 +41,32 @@ dependencies { You can now start your OpenSearch cluster. -The following example uses credentials that come with the default OpenSearch configuration. If you're using the OpenSearch Java client with your own OpenSearch cluster, be sure to change the code to use your own credentials. +## Security -## Sample code +This code example uses basic credentials that come with the default OpenSearch configuration. If you’re using the OpenSearch Java client with your own OpenSearch cluster, be sure to change the code to use your own credentials. +{: .note} + +Before you can securely connect to an OpenSearch cluster, you need to first add your root certificates to a truststore: + +```bash +keytool -import -alias -keystore +``` + +You can now point your Java client to the truststore and set basic authentication credentials that can access a secure cluster. + +```java +System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore"); +System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore"); + +//Only for demo purposes. Don't specify your credentials in code. +final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); +credentialsProvider.setCredentials(AuthScope.ANY, + new UsernamePasswordCredentials("admin", "admin")); +``` + +If you run into issues when configuring security, see [common issues]({{site.url}}{{site.baseurl}}/troubleshoot/index) and [troubleshoot TLS]({{site.url}}{{site.baseurl}}/troubleshoot/tls). + +## Sample data This section uses a class called `IndexData`, which is a simple Java class that stores basic data and methods. For your own OpenSearch cluster, you might find that you need a more robust class to store your data. @@ -79,7 +105,122 @@ static class IndexData { } ``` -### OpenSearch client example +## Initialize the client with SSL and TLS enabled + +The following sample code initializes a client with SSL and TLS enabled: + +```java +import org.apache.http.HttpHost; +import org.apache.http.auth.AuthScope; +import org.apache.http.auth.UsernamePasswordCredentials; +import org.apache.http.client.CredentialsProvider; +import org.apache.http.impl.client.BasicCredentialsProvider; +import org.apache.http.impl.nio.client.HttpAsyncClientBuilder; +import org.opensearch.client.RestClient; +import org.opensearch.client.RestClientBuilder; +import org.opensearch.clients.base.RestClientTransport; +import org.opensearch.clients.base.Transport; +import org.opensearch.clients.json.jackson.JacksonJsonpMapper; +import org.opensearch.clients.opensearch.OpenSearchClient; +import org.opensearch.clients.opensearch._global.IndexRequest; +import org.opensearch.clients.opensearch._global.IndexResponse; +import org.opensearch.clients.opensearch._global.SearchResponse; +import org.opensearch.clients.opensearch.indices.*; +import org.opensearch.clients.opensearch.indices.put_settings.IndexSettingsBody; + +import java.io.IOException; + +public class OpenSearchClientExample { + public static void main(String[] args) { + try{ + System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore"); + System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore"); + + //Only for demo purposes. Don't specify your credentials in code. + final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); + credentialsProvider.setCredentials(AuthScope.ANY, + new UsernamePasswordCredentials("admin", "admin")); + + //Initialize the client with SSL and TLS enabled + RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200, "https")). + setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() { + @Override + public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) { + return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider); + } + }).build(); + Transport transport = new RestClientTransport(restClient, new JacksonJsonpMapper()); + OpenSearchClient client = new OpenSearchClient(transport); + } + } +} +``` + +## OpenSearch client examples + +This section has sample code that shows you how to create an index with non-default settings, add a document to the index, search for the document, delete the document, and finally delete the index. + +### Create an index with non-default settings + +```java +String index = "sample-index"; +CreateRequest createIndexRequest = new CreateRequest.Builder().index(index).build(); +client.indices().create(createIndexRequest); + +IndexSettings indexSettings = new IndexSettings.Builder().autoExpandReplicas("0-all").build(); +IndexSettingsBody settingsBody = new IndexSettingsBody.Builder().settings(indexSettings).build(); +PutSettingsRequest putSettingsRequest = new PutSettingsRequest.Builder().index(index).value(settingsBody).build(); +client.indices().putSettings(putSettingsRequest); +``` + +### Index data + +```java +IndexData indexData = new IndexData("first_name", "Bruce"); +IndexRequest indexRequest = new IndexRequest.Builder().index(index).id("1").value(indexData).build(); +client.index(indexRequest); +``` + +### Search for the document + +```java +SearchResponse searchResponse = client.search(s -> s.index(index), IndexData.class); +for (int i = 0; i< searchResponse.hits().hits().size(); i++) { + System.out.println(searchResponse.hits().hits().get(i).source()); +} +``` + +### Delete the document + +The following sample code deletes a document whose ID is 1. + +```java +client.delete(b -> b.index(index).id("1")); +``` + +### Delete the index + +```java +DeleteRequest deleteRequest = new DeleteRequest.Builder().index(index).build(); +DeleteResponse deleteResponse = client.indices().delete(deleteRequest); + +restClient.close(); +} catch (IOException e){ + System.out.println(e.toString()); +} finally { + try { + if (client != null) { + client.close(); + } + } catch (IOException e) { + System.out.println(e.toString()); + } + } + } +} +``` + +## Complete code sample ```java import org.apache.http.HttpHost; diff --git a/_security-plugin/audit-logs/field-reference.md b/_security-plugin/audit-logs/field-reference.md index d5d8ca69..989de205 100644 --- a/_security-plugin/audit-logs/field-reference.md +++ b/_security-plugin/audit-logs/field-reference.md @@ -1,7 +1,7 @@ --- layout: default title: Audit log field reference -parent: Audit Logs +parent: Audit logs nav_order: 1 --- diff --git a/_security-plugin/audit-logs/storage-types.md b/_security-plugin/audit-logs/storage-types.md index 6c25f036..774ac6f4 100644 --- a/_security-plugin/audit-logs/storage-types.md +++ b/_security-plugin/audit-logs/storage-types.md @@ -1,7 +1,7 @@ --- layout: default title: Audit log storage types -parent: Audit Logs +parent: Audit logs nav_order: 10 --- From 8d1dfa504026016bd64ddb803293e8ba830cd05e Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 9 Dec 2021 11:18:01 -0800 Subject: [PATCH 2/5] Language tweaks Signed-off-by: keithhc2 --- _clients/java-rest-high-level.md | 2 +- _clients/java.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 951563db..2d13f834 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -27,7 +27,7 @@ You can now start your OpenSearch cluster. The OpenSearch 1.x high-level REST cl This code example uses basic credentials that come with the default OpenSearch configuration. If you’re using the OpenSearch Java high-level REST client with your own OpenSearch cluster, be sure to change the code to use your own credentials. {: .note} -Before you can securely connect to an OpenSearch cluster, you need to first add your root certificates to a truststore: +Before you can securely connect to an OpenSearch cluster, you must first add your root certificates to a truststore. If you don't already have a custom truststore, the following command creates a truststore and adds in a certificate. ```bash keytool -import -alias -keystore diff --git a/_clients/java.md b/_clients/java.md index ca88908d..a8bb382f 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -46,7 +46,7 @@ You can now start your OpenSearch cluster. This code example uses basic credentials that come with the default OpenSearch configuration. If you’re using the OpenSearch Java client with your own OpenSearch cluster, be sure to change the code to use your own credentials. {: .note} -Before you can securely connect to an OpenSearch cluster, you need to first add your root certificates to a truststore: +Before you can securely connect to an OpenSearch cluster, you must first add your root certificates to a truststore. If you don't already have a custom truststore, the following command creates a truststore and adds in a certificate. ```bash keytool -import -alias -keystore From 44711700ad47df736ee6232a8d369f98c390d829 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 9 Dec 2021 15:48:48 -0800 Subject: [PATCH 3/5] Addressed comments Signed-off-by: keithhc2 --- _clients/java-rest-high-level.md | 22 +++++----------------- _clients/java.md | 19 +++++-------------- 2 files changed, 10 insertions(+), 31 deletions(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 2d13f834..2e854227 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -24,34 +24,22 @@ You can now start your OpenSearch cluster. The OpenSearch 1.x high-level REST cl ## Security -This code example uses basic credentials that come with the default OpenSearch configuration. If you’re using the OpenSearch Java high-level REST client with your own OpenSearch cluster, be sure to change the code to use your own credentials. -{: .note} +Before using the REST client in your Java application, you need to configure the application's truststore to connect to the security plugin. If you are using self-signed certificates or demo configurations, you can use the following command to create a custom truststore and add in root authority certificates. -Before you can securely connect to an OpenSearch cluster, you must first add your root certificates to a truststore. If you don't already have a custom truststore, the following command creates a truststore and adds in a certificate. +If you're using certificates from a trusted Certificate Authority (CA), you don't need to configure the truststore. ```bash keytool -import -alias -keystore ``` -You can now point your Java client to the truststore and set basic authentication credentials that can access a secure cluster. - -```java -//Point to keystore with appropriate certificates for security. -System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore"); -System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore"); - -//Establish credentials to use basic authentication. -//Only for demo purposes. Don't specify your credentials in code. -final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); -credentialsProvider.setCredentials(AuthScope.ANY, - new UsernamePasswordCredentials("admin", "admin")); -``` +You can now point your Java client to the truststore and set basic authentication credentials that can access a secure cluster (refer to the sample code below on how to do so). If you run into issues when configuring security, see [common issues]({{site.url}}{{site.baseurl}}/troubleshoot/index) and [troubleshoot TLS]({{site.url}}{{site.baseurl}}/troubleshoot/tls). - ## Sample code +This code example uses basic credentials that come with the default OpenSearch configuration. If you’re using the OpenSearch Java high-level REST client with your own OpenSearch cluster, be sure to change the code to use your own credentials. + ```java import org.apache.http.HttpHost; import org.apache.http.auth.AuthScope; diff --git a/_clients/java.md b/_clients/java.md index a8bb382f..7f70671c 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -43,26 +43,15 @@ You can now start your OpenSearch cluster. ## Security -This code example uses basic credentials that come with the default OpenSearch configuration. If you’re using the OpenSearch Java client with your own OpenSearch cluster, be sure to change the code to use your own credentials. -{: .note} +Before using the REST client in your Java application, you need to configure the application's truststore to connect to the security plugin. If you are using self-signed certificates or demo configurations, you can use the following command to create a custom truststore and add in root authority certificates. -Before you can securely connect to an OpenSearch cluster, you must first add your root certificates to a truststore. If you don't already have a custom truststore, the following command creates a truststore and adds in a certificate. +If you're using certificates from a trusted Certificate Authority (CA), you don't need to configure the truststore. ```bash keytool -import -alias -keystore ``` -You can now point your Java client to the truststore and set basic authentication credentials that can access a secure cluster. - -```java -System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore"); -System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore"); - -//Only for demo purposes. Don't specify your credentials in code. -final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); -credentialsProvider.setCredentials(AuthScope.ANY, - new UsernamePasswordCredentials("admin", "admin")); -``` +You can now point your Java client to the truststore and set basic authentication credentials that can access a secure cluster (refer to the sample code below on how to do so). If you run into issues when configuring security, see [common issues]({{site.url}}{{site.baseurl}}/troubleshoot/index) and [troubleshoot TLS]({{site.url}}{{site.baseurl}}/troubleshoot/tls). @@ -107,6 +96,8 @@ static class IndexData { ## Initialize the client with SSL and TLS enabled +This code example uses basic credentials that come with the default OpenSearch configuration. If you’re using the Java client with your own OpenSearch cluster, be sure to change the code to use your own credentials. + The following sample code initializes a client with SSL and TLS enabled: ```java From f12a98cb4b454b61ac280d2c3541de1166710f12 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 9 Dec 2021 15:50:01 -0800 Subject: [PATCH 4/5] Language tweaks Signed-off-by: keithhc2 --- _clients/java-rest-high-level.md | 2 +- _clients/java.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 2e854227..35778af7 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -24,7 +24,7 @@ You can now start your OpenSearch cluster. The OpenSearch 1.x high-level REST cl ## Security -Before using the REST client in your Java application, you need to configure the application's truststore to connect to the security plugin. If you are using self-signed certificates or demo configurations, you can use the following command to create a custom truststore and add in root authority certificates. +Before using the REST client in your Java application, you must configure the application's truststore to connect to the security plugin. If you are using self-signed certificates or demo configurations, you can use the following command to create a custom truststore and add in root authority certificates. If you're using certificates from a trusted Certificate Authority (CA), you don't need to configure the truststore. diff --git a/_clients/java.md b/_clients/java.md index 7f70671c..7c1ce770 100644 --- a/_clients/java.md +++ b/_clients/java.md @@ -43,7 +43,7 @@ You can now start your OpenSearch cluster. ## Security -Before using the REST client in your Java application, you need to configure the application's truststore to connect to the security plugin. If you are using self-signed certificates or demo configurations, you can use the following command to create a custom truststore and add in root authority certificates. +Before using the REST client in your Java application, you must configure the application's truststore to connect to the security plugin. If you are using self-signed certificates or demo configurations, you can use the following command to create a custom truststore and add in root authority certificates. If you're using certificates from a trusted Certificate Authority (CA), you don't need to configure the truststore. From 78b8930f58158d6331af7b8b0fa5a6d9e4443b64 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 15 Dec 2021 13:13:18 -0800 Subject: [PATCH 5/5] Fixed cert names Signed-off-by: keithhc2 --- _security-plugin/configuration/generate-certificates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_security-plugin/configuration/generate-certificates.md b/_security-plugin/configuration/generate-certificates.md index 8206e2fa..579efc00 100755 --- a/_security-plugin/configuration/generate-certificates.md +++ b/_security-plugin/configuration/generate-certificates.md @@ -166,8 +166,8 @@ This process generates many files, but these are the ones you need to add to eac - `root-ca.pem` - `admin.pem` - `admin-key.pem` -- (Optional) `one-node-cert.pem` -- (Optional) `one-node-key.pem` +- (Optional) `node1.pem` +- (Optional) `node1-key.pem` On one node, the security configuration portion of `opensearch.yml` might look like this: