Skip to content

Commit ee9f57d

Browse files
Anaethelionszabosteve
Anaethelion
and
szabosteve
authored
Add security on by default documentation (#491)
* Add security on by default documentation * Fix id collision in connecting section * Update .doc/connecting.asciidoc Co-authored-by: István Zoltán Szabó <[email protected]> * Update .doc/connecting.asciidoc Co-authored-by: István Zoltán Szabó <[email protected]> * Update .doc/connecting.asciidoc Co-authored-by: István Zoltán Szabó <[email protected]> Co-authored-by: István Zoltán Szabó <[email protected]>
1 parent 7ddad3a commit ee9f57d

File tree

2 files changed

+197
-15
lines changed

2 files changed

+197
-15
lines changed

‎.doc/connecting.asciidoc‎

Lines changed: 186 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,186 @@ This page contains the information you need to connect and use the Client with
66

77
**On this page**
88

9-
* <<auth-reference, Authentication options>>
9+
* Connecting
10+
** <<connecting-to-elastic-cloud, Connecting to Elastic Cloud>>
11+
** <<connecting-to-self-managed, Connecting to a self-managed cluster>>
12+
** <<verifying-with-ca, Verifying HTTPS with CA certificates>>
13+
** <<verifying-with-fingerprint, Verifying HTTPS with certificate fingerprint>>
14+
** <<connecting-without-security, Connecting without security enabled>>
15+
** <<connecting-multiple-nodes, Connecting to multiple nodes>>
16+
* <<auth-reference, Authentication>>
17+
** <<auth-basic, Basic Authentication>>
18+
** <<auth-token, HTTP Bearer authentication>>
19+
* <<compatibility-mode, Compatibility mode>>
1020
* <<client-usage, Using the client>>
21+
* <<connecting-faas, Using the Client in a Function-as-a-Service Environment>>
22+
23+
[discrete]
24+
[[connecting-to-elastic-cloud]]
25+
==== Connecting to Elastic Cloud
26+
27+
If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers
28+
an easy way to connect to it. You must pass the Cloud ID that you can find in
29+
the cloud console and the corresponding API key.
30+
31+
[source,go]
32+
------------------------------------
33+
cfg := elasticsearch.Config{
34+
CloudID: "CLOUD_ID",
35+
APIKey: "API_KEY"
36+
}
37+
es, err := elasticsearch.NewClient(cfg)
38+
------------------------------------
39+
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.
40+
41+
[discrete]
42+
[[connecting-to-self-managed]]
43+
==== Connecting to a self-managed cluster
44+
45+
Starting from version 8.0, {es} offers security by default with authentication and TLS enabled.
46+
47+
To connect to the {es} cluster you need to configure the client to use the generated CA certificate. 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.
48+
49+
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):
50+
51+
```sh
52+
----------------------------------------------------------------
53+
-> Elasticsearch security features have been automatically configured!
54+
-> Authentication is enabled and cluster connections are encrypted.
55+
-> Password for the elastic user (reset with `bin/elasticsearch-reset-password -u elastic`):
56+
lhQpLELkjkrawaBoaz0Q
57+
-> HTTP CA certificate SHA-256 fingerprint:
58+
a52dd93511e8c6045e21f16654b77c9ee0f34aea26d9f40320b531c474676228
59+
...
60+
----------------------------------------------------------------
61+
```
62+
63+
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.
64+
65+
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.
66+
67+
[discrete]
68+
[[verifying-with-ca]]
69+
==== Verifying HTTPS with CA certificates
70+
71+
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].
72+
73+
Once you have the `http_ca.crt` file somewhere accessible pass the content of the file to the client via `CACert`:
74+
75+
[source,go]
76+
------------------------------------
77+
cert, _ := ioutil.ReadFile("/path/to/http_ca.crt")
78+
79+
cfg := elasticsearch.Config{
80+
Addresses: []string{
81+
"https://localhost:9200",
82+
},
83+
Username: "elastic",
84+
Password: ELASTIC_PASSWORD
85+
CACert: cert
86+
}
87+
es, err := elasticsearch.NewClient(cfg)
88+
------------------------------------
89+
90+
[discrete]
91+
[[verifying-with-fingerprint]]
92+
==== Verifying HTTPS with certificate fingerprint
93+
94+
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 Go {es} client via `ca_fingerprint`:
95+
96+
[source,go]
97+
------------------------------------
98+
cfg := elasticsearch.Config{
99+
Addresses: []string{
100+
"https://localhost:9200",
101+
},
102+
Username: "elastic",
103+
Password: ELASTIC_PASSWORD
104+
CertificateFingerprint: CERT_FINGERPRINT
105+
}
106+
es, err := elasticsearch.NewClient(cfg)
107+
------------------------------------
108+
109+
The certificate fingerprint can be calculated using openssl x509 with the certificate file:
110+
111+
[source,sh]
112+
----
113+
openssl x509 -fingerprint -sha256 -noout -in /path/to/http_ca.crt
114+
----
115+
116+
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`:
117+
118+
[source,sh]
119+
----
120+
# Replace the values of 'localhost' and '9200' to the
121+
# corresponding host and port values for the cluster.
122+
openssl s_client -connect localhost:9200 -servername localhost -showcerts </dev/null 2>/dev/null \
123+
| openssl x509 -fingerprint -sha256 -noout -in /dev/stdin
124+
----
125+
126+
The output of `openssl x509` will look something like this:
127+
128+
[source,sh]
129+
----
130+
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
131+
----
132+
133+
[discrete]
134+
[[connecting-without-security]]
135+
==== Connecting without security enabled
136+
137+
WARNING: Running {es} without security enabled is not recommended.
138+
139+
If your cluster is configured with
140+
https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html[security explicitly disabled]
141+
then you can connect via HTTP:
142+
143+
[source,go]
144+
----
145+
cfg := elasticsearch.Config{
146+
Addresses: []string{
147+
"http://localhost:9200",
148+
},
149+
}
150+
es, err := elasticsearch.NewClient(cfg)
151+
----
152+
153+
[discrete]
154+
[[connecting-multiple-nodes]]
155+
==== Connecting to multiple nodes
156+
157+
The Go {es} client supports sending API requests to multiple nodes in the
158+
cluster. This means that work will be more evenly spread across the cluster
159+
instead of hammering the same node over and over with requests. To configure the
160+
client with multiple nodes you can pass a list of URLs, each URL will be used as
161+
a separate node in the pool.
162+
163+
[source,go]
164+
----
165+
cfg := elasticsearch.Config{
166+
Addresses: []string{
167+
"https://localhost:9200",
168+
"https://localhost:9201",
169+
},
170+
CACert: caCert,
171+
Username: "elastic",
172+
Password: ELASTIC_PASSWORD,
173+
}
174+
es, err := elasticsearch.NewClient(cfg)
175+
----
176+
177+
By default nodes are selected using round-robin, but alternate node selection
178+
strategies can be implemented via the `elastictransport.Selector` interface and provided to the client configuration.
179+
180+
NOTE: If your {es} cluster is behind a load balancer like when using Elastic
181+
Cloud you won't need to configure multiple nodes. Instead use the load balancer
182+
host and port.
11183

12184
[discrete]
13185
[[auth-reference]]
14186
=== Authentication
15187

16-
This document contains code snippets to show you how to connect to various {es}
17-
providers.
188+
This section contains code snippets to show you how to authenticate with {es}.
18189

19190

20191
[discrete]
@@ -27,8 +198,8 @@ To set the cluster endpoints, the username, and the password programatically, pa
27198
------------------------------------
28199
cfg := elasticsearch.Config{
29200
Addresses: []string{
30-
"http://localhost:9200",
31-
"http://localhost:9201",
201+
"https://localhost:9200",
202+
"https://localhost:9201",
32203
},
33204
Username: "foo",
34205
Password: "bar",
@@ -42,20 +213,22 @@ You can also include the username and password in the endpoint URL:
42213
'https://username:password@localhost:9200'
43214
```
44215

45-
46216
[discrete]
47-
[[auth-ec]]
48-
==== Elastic Cloud
217+
[[auth-token]]
218+
==== HTTP Bearer authentication
49219

50-
If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers
51-
an easy way to connect to it. You must pass the Cloud ID that you can find in
52-
the cloud console and the corresponding API key.
220+
HTTP Bearer authentication uses the `ServiceToken` parameter by passing the token
221+
as a string. This authentication method is used by
222+
https://www.elastic.co/guide/en/elasticsearch/reference/master/security-api-create-service-token.html[Service Account Tokens]
223+
and https://www.elastic.co/guide/en/elasticsearch/reference/master/security-api-get-token.html[Bearer Tokens].
53224

54225
[source,go]
55226
------------------------------------
56227
cfg := elasticsearch.Config{
57-
CloudID: "CLOUD_ID",
58-
APIKey: "API_KEY"
228+
Addresses: []string{
229+
"https://localhost:9200",
230+
},
231+
ServiceToken: "token-value",
59232
}
60233
es, err := elasticsearch.NewClient(cfg)
61234
------------------------------------

‎README.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,8 @@ to the `elasticsearch.NewClient()` function.
119119
```golang
120120
cfg := elasticsearch.Config{
121121
Addresses: []string{
122-
"http://localhost:9200",
123-
"http://localhost:9201",
122+
"https://localhost:9200",
123+
"https://localhost:9201",
124124
},
125125
// ...
126126
}
@@ -150,6 +150,15 @@ cfg := elasticsearch.Config{
150150
}
151151
```
152152

153+
To set a fingerprint to validate the HTTPS connectionm use the `CertificateFingerprint` configuration option.
154+
155+
```golang
156+
cfg := elasticsearch.Config{
157+
// ...
158+
CertificateFingerprint: fingerPrint,
159+
}
160+
```
161+
153162
To configure other HTTP settings, pass an [`http.Transport`](https://golang.org/pkg/net/http/#Transport)
154163
object in the configuration object.
155164

0 commit comments

Comments
 (0)