Skip to content

Commit 9695ea6

Browse files
picandocodigopicandocodigo
committed
[DOCS] Adds information for connecting with security by default
1 parent 023936b commit 9695ea6

File tree

1 file changed

+104
-28
lines changed

1 file changed

+104
-28
lines changed

‎docs/connecting.asciidoc

+104-28
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,7 @@ This page contains the information you need to connect and use the Client with
1515
[[client-auth]]
1616
=== Authentication
1717

18-
This document contains code snippets to show you how to connect to various {es}
19-
providers.
20-
18+
This document contains code snippets to show you how to connect to various {es} providers.
2119

2220
[discrete]
2321
[[auth-ec]]
@@ -52,7 +50,7 @@ After this step you will get the `API key` in the API keys page.
5250

5351
image::docs/images/cloud_api_key.png["API key"]
5452

55-
**IMPORTANT**: you need to copy and store the `API key`in a secure place, since you will not be able to view it again in Elastic Cloud.
53+
**IMPORTANT**: you need to copy and store the `API key` in a secure place, since you will not be able to view it again in Elastic Cloud.
5654

5755
Once you have collected the `Cloud ID` and the `API key` you can use the client
5856
to connect to your Elastic Cloud instance, as follows:
@@ -65,18 +63,114 @@ client = Elasticsearch::Client.new(
6563
)
6664
------------------------------------
6765

66+
[discrete]
67+
[[connect-self-managed]]
68+
=== Connecting to a self-managed cluster
69+
70+
{es} 8.0 offers security by default, that means authentication and TLS are enabled.
71+
72+
To connect to the {es} cluster you’ll need to configure the Ruby {es} client to use HTTPS with the generated CA certificate in order to make requests successfully.
73+
74+
If you’re just getting started with {es} we recommend reading the documentation on configuring and starting {es} to ensure your cluster is running as expected.
75+
76+
When you start {es} for the first time you’ll see a distinct block like the one below in the output from {es} (you may have to scroll up if it’s been a while):
77+
78+
79+
```sh
80+
----------------------------------------------------------------
81+
-> Elasticsearch security features have been automatically configured!
82+
-> Authentication is enabled and cluster connections are encrypted.
83+
84+
-> Password for the elastic user (reset with `bin/elasticsearch-reset-password -u elastic`):
85+
lhQpLELkjkrawaBoaz0Q
86+
87+
-> HTTP CA certificate SHA-256 fingerprint:
88+
a52dd93511e8c6045e21f16654b77c9ee0f34aea26d9f40320b531c474676228
89+
...
90+
----------------------------------------------------------------
91+
```
92+
93+
Note down the `elastic` user password and HTTP CA fingerprint for the next sections. In the examples below they will be stored in the variables `ELASTIC_PASSWORD` and `CERT_FINGERPRINT` respectively.
94+
95+
Depending on the circumstances there are two options for verifying the HTTPS connection, either verifying with the CA certificate itself or via the HTTP CA certificate fingerprint.
96+
97+
98+
[discrete]
99+
[[ca-certificates]]
100+
==== Verifying HTTPS with CA certificates
101+
102+
The generated root CA certificate can be found in the `certs` directory in your {es} config location (`$ES_CONF_PATH/certs/http_ca.crt`). If you're running {es} in Docker there is https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html[additional documentation for retrieving the CA certificate].
103+
104+
Once you have the `http_ca.crt` file somewhere accessible pass the path to the client via `ca_certs`:
105+
106+
[source,ruby]
107+
------------------------------------
108+
client = Elasticsearch::Client.new(
109+
host: "https://elastic:#{ELASTIC_PASSWORD}@localhost:9200",
110+
transport_options: { ssl: { ca_path: CERT_DIR } }
111+
)
112+
------------------------------------
113+
114+
[discrete]
115+
[[ca-fingerprint]]
116+
==== Verifying HTTPS with certificate fingerprints
117+
118+
119+
This method of verifying the HTTPS connection takes advantage of the certificate fingerprint value noted down earlier. Take this SHA256 fingerprint value and pass it to the Ruby {es} client via `ca_fingerprint`:
120+
121+
[source,ruby]
122+
------------------------------------
123+
# Colons and uppercase/lowercase don't matter when using
124+
# the 'ca_fingerprint' parameter
125+
CERT_FINGERPRINT = '64F2593F...'
126+
127+
# Password for the 'elastic' user generated by Elasticsearch
128+
ELASTIC_PASSWORD = "<password>"
129+
130+
client = Elasticsearch::Client.new(
131+
host: "https://elastic:#{ELASTIC_PASSWORD}@localhost:9200",
132+
transport_options: { ssl: { verify: false } },
133+
ca_fingerprint: CERT_FINGERPRINT
134+
)
135+
------------------------------------
136+
137+
The verification will be run once per connection.
138+
139+
140+
The certificate fingerprint can be calculated using `openssl x509` with the certificate file:
141+
142+
[source,sh]
143+
----
144+
openssl x509 -fingerprint -sha256 -noout -in /path/to/http_ca.crt
145+
----
146+
147+
If you don't have access to the generated CA file from {es} you can use the following script to output the root CA fingerprint of the {es} instance with `openssl s_client`:
148+
149+
[source,sh]
150+
----
151+
# Replace the values of 'localhost' and '9200' to the
152+
# corresponding host and port values for the cluster.
153+
openssl s_client -connect localhost:9200 -servername localhost -showcerts </dev/null 2>/dev/null \
154+
| openssl x509 -fingerprint -sha256 -noout -in /dev/stdin
155+
----
156+
157+
The output of `openssl x509` will look something like this:
158+
159+
[source,sh]
160+
----
161+
SHA256 Fingerprint=A5:2D:D9:35:11:E8:C6:04:5E:21:F1:66:54:B7:7C:9E:E0:F3:4A:EA:26:D9:F4:03:20:B5:31:C4:74:67:62:28
162+
----
163+
164+
165+
68166

69167
[discrete]
70168
[[auth-api-key]]
71169
==== API Key authentication
72170

73-
You can also use the
74-
https://www.elastic.co/guide/en/elasticsearch/reference/7.16/security-api-create-api-key.html[ApiKey]
75-
authentication.
171+
You can also use https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-api-key.html[ApiKey] authentication.
76172

77-
NOTE: If you provide both basic authentication credentials and the ApiKey
78-
configuration, the ApiKey takes precedence.
79-
You can also use API Key authentication:
173+
NOTE: If you provide both basic authentication credentials and the ApiKey configuration, the ApiKey takes precedence.
80174

81175
[source,ruby]
82176
------------------------------------
@@ -140,24 +234,6 @@ Elasticsearch::Client.new(
140234
)
141235
------------------------------------
142236

143-
[discrete]
144-
[[ca-fingerprint]]
145-
==== CA fingerprint
146-
147-
You can configure the client to only trust certificates that are signed by a specific CA certificate (CA certificate pinning) by providing a `ca_fingerprint` option. This will verify that the fingerprint of the CA certificate that has signed the certificate of the server matches the supplied value:
148-
149-
[source,ruby]
150-
------------------------------------
151-
ca_fingerprint = '64F2593F...'
152-
client = Elasticsearch::Client.new(
153-
host: 'https://elastic:changeme@localhost:9200',
154-
transport_options: { ssl: { verify: false } },
155-
ca_fingerprint: ca_fingerprint
156-
)
157-
------------------------------------
158-
159-
The verification will be run once per connection.
160-
161237
[discrete]
162238
[[client-usage]]
163239
=== Usage

0 commit comments

Comments
 (0)