This guide walks you through the steps needed to set up either an API token,a JWT realm, or basic authorization, and gather the configuration needed to create an Elasticsearch SIEM integration.
Before you begin, makes sure you have created the index you would like to integrate with for storing your events. If you are using Elastic Security, this is done for you. Note that you can search multiple indexes at once. Supply the comma separated index value to Elasticsearch if your integration requires this.
Option 1: API Key (Token) Authentication
Configure a new API Key
1. Create a new role and user (Optional)
Adding a new role and user will allow you to narrow the scope of the API key. The creation of a new role and user is optional; however, it is strongly recommended so that you can limit the permissions of the API key.
Use the example in the Kibana documentation to create a new role with the following privileges:
Cluster:
monitormanage_own_api_key
Index:
readview_index_metadatawrite
Lastly, grant read access to the Kibana space.
Navigate to Security > Users and click Create user.
Fill in the user details. Select the role you created to grant the new user access only to the desired index.
Click Create user
Log out of Kibana.
2. Create a new API Key
Log in to Kibana with the user you would like to associate with your token. If you created a user in step 1, log in as this user.
Following the Elasticsearch instructions for creating a new API key. Once the key is created, copy it to a safe location.
Configure the Integration
Create your integration by supplying the following configuration values.
URL This is your base Elasticsearch URL without any path segments. For example, "https://tenant.elastic.com".
Index This is the index you would like to connect to which stores your events. Note that you can search multiple indexes at once. Supply the comma separated index value to Elasticsearch if your integration requires this.
Token This is the API Key created in step 2
Option 2: JWT Realm (Oauth 2.0) Authentication
Configure the Elasticsearch JWT Realm
Using a JWT realm with Elasticsearch enables a third party OAuth 2.0 Identity Provider to issue tokens that are accepted for Elasticsearch API requests. A JWT realm enables the use of the client credentials grant. This does not require an interactive flow, perfect for integration connections.
1. Create a new role (Optional)
Adding a new role will allow you to narrow the scope of the integration's access. The creation of a new role is optional; however, it is strongly recommended so that you can limit the permissions of the JWT realm.
Use the example in the Kibana documentation to create a new role with the following privileges:
Cluster:
monitor
Index:
readview_index_metadatawrite
2. Create a JWT realm to authenticate requests
Update your Elasticsearch installation to authenticate tokens issued by an external OAuth 2.0 identity provider with a JWT realm.
The identity provider is completely separate from your Elasticsearch instance. Configuring a JWT realm allows you to create a client enabling machine-to-machine connections using the Client Credentials OAuth 2.0 flow.
The Client ID, Client Secret, Token URL, and Scopes are available from your Identity Provider. How to configure the provider and the exact values will vary depending on the Identity Provider you use. The values you supply will be used in a standard OAuth 2.0 client credentials flow with your identity provider to get an access token which is sent to Elasticsearch as authentication for each request.
Copy these values from your identity provider to a safe location.
Configure the Integration
Create your integration by supplying the following configuration values.
URL This is your base Elasticsearch URL without any path segments. For example, "https://tenant.elastic.com".
Index This is the index you would like to connect to which stores your events. Note that you can search multiple indexes at once. Supply the comma separated index value to Elasticsearch if your integration requires this.
Token URL This is the fully qualified token URL for your OAuth 2.0 Identity Provider gathered in step 2
Client ID The client ID defined in your OAuth 2.0 Identity Provider, gathered in step 2
Client Secret The client secret defined in your OAuth 2.0 Identity Provider, gathered in step 2
Authentication Scopes This is the space-separated list of scopes to request when issuing a client-credentials grant token from your OAuth 2.0 Identity Provider, gathered in step 2
Elasticsearch Shared Secret (Optional) When you configure your Elasticsearch JWT realm, you can choose to require a shared secret for any request made. This is a special header that is sent with the request. When this configuration is present, this value is sent in the header of all requests.
Elasticsearch RunAs User (Optional) When making API requests to Elasticsearch you can send a special header allowing you to run the request as if it was made by a specific user. Supplying the username in this authentication option will send this header with every request. The role assigned to the JWT realm must have permissions to run as this user.
Option 3: Basic Authentication
If possible, it is highly suggested that you use one of the other options for Elastic authentication as they provide better control over access revocation. Basic auth is tied directly to a user.
Create a new user
1. Create a new role and user (Optional)
Adding a new role and user will allow you to narrow the scope of the user. The creation of a new role and user is optional; however, it is strongly recommended so that you can limit the permissions of the user.
Use the example in the Kibana documentation to create a new role with the following privileges:
Cluster:
monitor
Index:
readview_index_metadatawrite
Navigate to Security > Users and click Create user.
Fill in the user details. Select the role you created to grant the new user access only to the desired index. Copy the username and password for the new user to a safe location.
Click Create user
Configure the Integration
Create your integration by supplying the following configuration values.
URL This is your base Elasticsearch URL without any path segments. For example, "https://tenant.elastic.com".
Index This is the index you would like to connect to which stores your events. Note that you can search multiple indexes at once. Supply the comma separated index value to Elasticsearch if your integration requires this.
Username This is the username for the user that authenticates requests, gathered in step 1 if you created a new user. Creating a new user is optional, but recommended.
Secret This is the password for the user that authenticates requests, gathered in step 1 if you created a new user. Creating a new user is optional, but recommended.