Configure your Elasticsearch search engine to use API key for authentication

You can configure your Elasticsearch search engine to use an API key for authentication. To do so, you must complete the following:

  1. Enable security in Elasticsearch

  2. Set passwords for built-in users

  3. Generate an API Key

  4. Configure the API Key in SmartHub

Enable security in Elasticsearch

  1. Open your elasticsearch.yml file in a text editor.

  2. Set the xpack.security.enabled and xpack.security.authc.api_key.enabled parameters to true.

    xpack.security.enabled: true
    xpack.security.authc.api_key.enabled: true

  3. For single-node developer set-ups, add the following line to the file.

    discovery.type: single-node

  4. Restart your Elastic server.

Set passwords for built-in users

After enabling security, you will be locked out from Elastic until you set passwords. For more information, see elasticsearch-setup-passwords in the Elastic documentation.

  1. In the Elastic CLI, run the following one-time setup command:

    ./bin/elasticsearch-setup-passwords interactive

  2. When prompted, set the password for the elastic superuser and other users. Ensure that you note the password for later use in authentication.

    If you have not explicitly also set the elastic username, the default username is elastic.

Generate an API Key

After setting your passwords, you can use the Elastic user credentials that you set previously to create an API key.

  1. Using an API platform, such as Postman, make a post request to the following:

    http://<elastic webserver address>/_security/api_key

  2. If you are using Postman, you can click the Authorization tab > Basic Auth > and add the username and password that you configured in Set passwords for built-in users. For more information, see API authentication and authorization in Postman in the Postman documentation.

  3. Provide the request body for your request. The following example provides a super admin API key. You can adjust this request body to fit your needs. For more information, see Create an API key in the Elastic documentation. 

    {
      "name": "admin-api-key",
      "expiration": "365d",
      "role_descriptors": {
        "admin_role": {
          "cluster": ["all"],
          "index": [
            {
              "names": ["*"],  // Wildcard for all indices
              "privileges": ["all"]
            }
          ]
        }
      }
    }

  4. Verify that you are receiving your API key in the response. For example, the sample code above produces the following response:

    {
        "id": "-YgrFZYB6OjK-FcX6Tan",
        "name": "admin-api-key",
        "expiration": 1775647921575,
        "api_key": "rqtDE3W6RwqPFYybuSUb-w",
        "encoded": "LVlnckZaWUI2T2pLLUZjWDZUYW46cnF0REUzVzZSd3FQRll5YnVTVWItdw=="
    }

Configure the API Key in SmartHub

After creating your API key, you can configure SmartHub to use it for your Elasticsearch Search Engine and storage settings configurations:

  1. In your Elasticsearch Search Engine configuration, select ApiKey from the Authentication Mode drop-down list.

  2. In the API Key field, enter your API key in the following format: id:api_key. For example, using the sample response above, the value of this field is -YgrFZYB6OjK-FcX6Tan:rqtDE3W6RwqPFYybuSUb-w.

  3. In your storage settings configuration, select ApiKey from the Elastic Authentication drop-down list.

  4. In the API Key field, enter your API key in the following format: id:api_key. For example, using the sample response above, the value of this field is -YgrFZYB6OjK-FcX6Tan:rqtDE3W6RwqPFYybuSUb-w.