> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simple Authentication

> Provides the necessary configurations for Apinizer to access the Elasticsearch application using Simple Authentication. Explains how to establish a secure connection by enabling Elasticsearch security options and defining credentials through Apinizer API Manager.

## License Check

The Elasticsearch license must be **Elastic Basic License**. Apinizer uses the simple authentication method supported by the X-Pack security plugin included in this license.

To check the Elasticsearch license information, make the following request:

```bash theme={null}
curl -X GET "http://<ELASTICSEARCH_IP_ADDRESS>:<PORT>/_xpack/license?pretty"
```

## Enabling Security

By default, Elasticsearch security settings are not enabled. To enable the security option, add the following property to the **config/elasticsearch.yml** file.

<Tip>
  If there are multiple nodes, this property must be enabled on all of them.
</Tip>

```yaml theme={null}
xpack.security.enabled: true
```

<Info>
  After this operation, the Elasticsearch application must be restarted.
</Info>

### Encrypting Communication Between Nodes in the Cluster (TLS Settings)

If you encounter the following error after Elasticsearch restarts, or if there are multiple nodes, the settings in this section should be configured. When security is enabled and running in a production environment, communication between Elasticsearch nodes must be encrypted. This communication occurs at the transport layer.

```
Transport SSL must be enabled for setups with production licenses. Please set [xpack.security.transport.ssl.enabled] to [true] or disable security by setting [xpack.security.enabled] to [false]
```

<Info>
  If there are multiple nodes, this setting must be configured on all of them.
</Info>

For clusters with multiple nodes, the following settings and other optional settings should be noted in the **config/elasticsearch.yml** file:

```yaml theme={null}
# Nodes must have a unique name to find the cluster.
cluster.name: ApinizerEsCluster

# Since multiple nodes on the same machine may have the same ip/host information, the certificate location can be determined based on this node name.
node.name: <ELASTICSEARCH_IP_ADDRESS>

# If there is a single node, this setting can postpone the TLS error. But if there are multiple nodes, it should be removed.
# If cluster.initial_master_nodes is in the yaml file, do not add discovery.type.
discovery.type: single-node

# If there are multiple master-eligible nodes
cluster.initial_master_nodes: ["<ELASTICSEARCH_IP_ADDRESS>"]
```

### Certificate Creation

<Steps>
  <Step title="Creating CA certificate">
    Use the following command to create a certificate:

    ```bash theme={null}
    ./bin/elasticsearch-certutil ca
    ```

    <Warning>
      This file does not need to be password-protected, but it is not recommended.
    </Warning>
  </Step>

  <Step title="Creating certificate">
    Create a certificate using the CA certificate:

    ```bash theme={null}
    ./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12
    ```
  </Step>

  <Step title="Moving certificates">
    Create the **config/certs** directory and move the certificates there:

    ```bash theme={null}
    mkdir config/certs/
    mv elastic-certificates.p12 config/certs/
    mv elastic-stack-ca.p12 config/certs/
    ```

    <Info>
      Before proceeding, ensure that these certificate files have the same privileges as the Elasticsearch files.
    </Info>
  </Step>
</Steps>

<Warning>
  **If you get the error "could not find java in JAVA\_HOME at /tools/java/home/bin/java"**, use the following two commands to set the environment variables required for Java applications to run correctly.

  ```bash theme={null}
  export JAVA_HOME=/opt/elasticsearch/elasticsearch-7.9.2/jdk
  export PATH=$JAVA_HOME/bin:$PATH
  ```
</Warning>

Then, the following fields must be added to the **/config/elasticsearch.yml** file.

```yaml theme={null}
xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.verification_mode: certificate
xpack.security.transport.ssl.keystore.path: certs/elastic-certificates.p12
xpack.security.transport.ssl.truststore.path: certs/elastic-certificates.p12
```

<Info>
  After this operation, the Elasticsearch application must be restarted.
</Info>

You can check the security activation status with the following request.

```bash theme={null}
curl -X GET -u <USERNAME>:<PASSWORD> "http://<ELASTICSEARCH_IP_ADDRESS>:<PORT>/_xpack?pretty"
```

Example output:

```json theme={null}
...
"security" : {
  "available" : true,
  "enabled" : true
},
...
```

When this field is activated, any request without credentials will be rejected as follows.

```bash theme={null}
curl -X GET "http://<ELASTICSEARCH_IP_ADDRESS>:<PORT>"
```

Example error output:

```json theme={null}
{
  "error": {
    "root_cause": [
      {
        "type": "security_exception",
        "reason": "missing authentication credentials for REST request [/]",
        "header": {
          "WWW-Authenticate": "Basic realm=\"security\" charset=\"UTF-8\""
        }
      }
    ],
    "type": "security_exception",
    "reason": "missing authentication credentials for REST request [/]",
    "header": {
      "WWW-Authenticate": "Basic realm=\"security\" charset=\"UTF-8\""
    }
  },
  "status": 401
}
```

## Creating Built-in User Passwords

Elasticsearch's default built-in username is **elastic**. However, there is no password created for this username.

<Warning>
  When assigning passwords, all built-in users' passwords will be changed.
</Warning>

```bash theme={null}
# To automatically update passwords, run the following command in the Elasticsearch installation directory.
./bin/elasticsearch-setup-passwords auto

# Example output:
# Changed password for user elastic
# PASSWORD elastic = dd6mjMiemZlAKfOXkUAm

# To manually update passwords, run the following command in the Elasticsearch installation directory.
./bin/elasticsearch-setup-passwords interactive
```

<Info>
  This step is necessary to create a new user after enabling Elasticsearch security. These credentials can also be defined in Apinizer API Manager.
</Info>

## Adding Users

To add or update a new user, make the following request. In the request, a new user with username **apinizer\_es\_cluster**, password **apinizer**, and role **superuser** has been added.

<Info>
  If user information is updated, it will return as **"created" : false**.
</Info>

```bash theme={null}
# For Windows;
curl -X POST -u <USERNAME>:<PASSWORD> "http://<ELASTICSEARCH_IP_ADDRESS>:<PORT>/_security/user/apinizer_es_cluster?pretty" -H "Content-Type:application/json" -d "{\"password\":\"apinizer\", \"roles\":[\"superuser\"], \"full_name\":\"Apinizer Elasticsearch Cluster\",\"email\" : \"apinizer@mail.com\"}"

# For Linux;
curl -X POST -u <USERNAME>:<PASSWORD> "http://<ELASTICSEARCH_IP_ADDRESS>:<PORT>/_security/user/apinizer_es_cluster?pretty" -H "Content-Type:application/json" -d '{"password":"apinizer", "roles":["superuser"], "full_name":"Apinizer Elasticsearch Cluster","email" : "apinizer@mail.com"}'
```

Example output:

```json theme={null}
{
  "created" : true
}
```

### Password Reset

To change the password:

```bash theme={null}
bin/elasticsearch-users passwd <USERNAME>
```

If the above command doesn't work and the passwords of users in Elasticsearch are lost, you can recover the cluster by creating a new user from the command line. You can update the password information with the existing username using the credentials of the user you created.

```bash theme={null}
bin/elasticsearch-users useradd <NEW_USERNAME> -p <NEW_PASSWORD> -r superuser

curl -X POST "http://<ELASTICSEARCH_IP_ADDRESS>:<PORT>/_security/user/<OLD_USERNAME>/_password?pretty" -H 'Content-Type: application/json' -d' {
  "password" : "<OLD_USERNAMES_NEW_PASSWORD>"
} '
```

Additionally;

* When sending requests through API testing tools like Postman, **Authorization: Basic \<base64 encoded username:password>** information must be added to the request's header field.

  ```bash theme={null}
  # For example;
  Authorization: Basic YXBpbml6ZXJfZXNfY2x1c3RlcjphcGluaXplcg==
  ```

* To manage users through Kibana, go to **Stack Management > Security > User** from the menu. The following fields must be added to the Kibana configuration file **/config/kibana.yml**.

  ```yaml theme={null}
  elasticsearch.username: "apinizer_es_cluster"
  elasticsearch.password: "apinizer"
  ```

Additional commands;

```bash theme={null}
# Getting information about the authenticated user
curl -X GET -u apinizer_es_cluster:apinizer "http://<ELASTICSEARCH_IP_ADDRESS>:<PORT>/_security/_authenticate?pretty"

# Users can be enabled or disabled.
curl -X PUT -u apinizer_es_cluster:apinizer "http://<ELASTICSEARCH_IP_ADDRESS>:<PORT>/_xpack/security/user/apinizer_es_cluster/_enable"
curl -X PUT -u apinizer_es_cluster:apinizer "http://<ELASTICSEARCH_IP_ADDRESS>:<PORT>/_xpack/security/user/apinizer_es_cluster/_disable"
```

## Apinizer Configuration

The username and password of the defined user are configured from the **Elasticsearch Clusters** page in Apinizer Manager Console.

<Frame caption="Apinizer - Elasticsearch Clusters page - Authentication configuration">
  <img src="https://mintcdn.com/apinizer/rfZaKpIysRC7U9dY/images/setup/elasticsearch/basit-kimlik-dogrulama/01-apinizer-konfigurasyonu.png?fit=max&auto=format&n=rfZaKpIysRC7U9dY&q=85&s=99382c67e81e6aee8d1f9639fe40922d" alt="Elasticsearch Clusters - Authentication" width="1200" height="640" style={{ borderRadius: '0.5rem' }} data-path="images/setup/elasticsearch/basit-kimlik-dogrulama/01-apinizer-konfigurasyonu.png" />
</Frame>

<Steps>
  <Step title="Enabling authentication">
    Enable the authentication switch button.
  </Step>

  <Step title="Entering credentials">
    Enter the username and password information.
  </Step>
</Steps>