[[auth-reference]]
== Authentication

This document contains code snippets to show you how to connect to various {es} 
providers.


=== Elastic Cloud

If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers 
an easy way to connect to it via the `cloud` option. You must pass the Cloud ID 
that you can find in the cloud console, then your username and password inside 
the `auth` option.

NOTE: When connecting to Elastic Cloud, the client will automatically enable 
both request and response compression by default, since it yields significant 
throughput improvements. Moreover, the client will also set the ssl option 
`secureProtocol` to `TLSv1_2_method` unless specified otherwise. You can still 
override this option by configuring them.

IMPORTANT: Do not enable sniffing when using Elastic Cloud, since the nodes are 
behind a load balancer, Elastic Cloud will take care of everything for you.

[source,js]
----
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
  cloud: {
    id: 'name:bG9jYWxob3N0JGFiY2QkZWZnaA==',
  },
  auth: {
    username: 'elastic',
    password: 'changeme'
  }
})
----


=== Basic authentication

You can provide your credentials by passing the `username` and `password` 
parameters via the `auth` option.

NOTE: If you provide both basic authentication credentials and the Api Key configuration, the Api Key will take precedence.

[source,js]
----
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
  node: 'https://localhost:9200',
  auth: {
    username: 'elastic',
    password: 'changeme'
  }
})
----


Otherwise, you can provide your credentials in the node(s) URL.

[source,js]
----
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
  node: 'https://username:password@localhost:9200'
})
----


=== ApiKey authentication

You can use the 
https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html[ApiKey] 
authentication by passing the `apiKey` parameter via the `auth` option. The 
`apiKey` parameter can be either a base64 encoded string or an object with the 
values that you can obtain from the 
https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html[create api key endpoint].

NOTE: If you provide both basic authentication credentials and the Api Key configuration, the Api Key will take precedence.

[source,js]
----
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
  node: 'https://localhost:9200',
  auth: {
    apiKey: 'base64EncodedKey'
  }
})
----

[source,js]
----
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
  node: 'https://localhost:9200',
  auth: {
    apiKey: {
      id: 'foo',
      api_key: 'bar'
    }
  }
})
----


=== SSL configuration

Without any additional configuration you can specify `https://` node urls, and 
the certificates used to sign these requests will be verified. To turn off certificate verification, you must specify an `ssl` object in the top level config and set `rejectUnauthorized: false`. The default `ssl` values are the same that Node.js's https://nodejs.org/api/tls.html#tls_tls_connect_options_callback[`tls.connect()`] 
uses.

[source,js]
----
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
  node: 'https://localhost:9200',
  auth: {
    username: 'elastic',
    password: 'changeme'
  },
  ssl: {
    ca: fs.readFileSync('./cacert.pem'),
    rejectUnauthorized: false
  }
})
----