Okta

Okta Inc. is an identity and access management company that provides technologies that enable secure user authentication into applications. In this guide, we integrate the Okta IdP to authenticate users into the Wazuh platform.

Learn how to create administrator and read-only roles on Okta and map them with Wazuh in the sections below.

Setup Okta single sign-on with administrator role

Follow these steps to integrate Okta IdP with Wazuh for single sign-on and grant administrator role to the authenticated Okta users on the Wazuh platform:

  1. Okta Configuration

  2. Wazuh indexer configuration

  3. Wazuh dashboard configuration

Okta Configuration

  1. Create an account on Okta. Request a free trial if you don't have a paid license.

  2. Create a new user.

    1. From your okta admin console page, navigate to Directory > People.

    2. From the People section, select Add Person, fill in the details of the new user, and click Save as seen in the following screenshots.

  3. Create a new group. Navigate to Directory > Groups and add a group.

    Create a new group using any name. In our case, we name it wazuh-admins. This name will be used as our backend_roles for Wazuh role mapping.

  4. Add the new user to the new group. Navigate to Directory > Groups and select your group. Click on Assign People and add the user to the group created.

  5. Create a new app. Configure the SAML settings while you create the app.

    1. Navigate to the Applications section in Okta. Select Create App Integration.

    2. In the Create a new application integration window, select SAML 2.0 and click Next.

    3. Assign a name to the application and click on Next. In our case, we assign the name wazuh-sso-app.

    4. In the Configure SAML menu, you’ll find the SAML Settings section, modify the following parameters:

      • Single sign on URL: input https://<WAZUH_DASHBOARD_URL>/_opendistro/_security/saml/acs and replace the <WAZUH_DASHBOARD_URL> field with the corresponding URL.

      • Audience URI (SP Entity ID): input wazuh-saml. This is the SP Entity ID value which will be used later in the config.yml on the Wazuh indexer instance.

      • Other Requestable SSO URLs: click on Show Advanced Settings to access this option. Input https://<WAZUH_DASHBOARD_URL>/_opendistro/_security/saml/acs/idpinitiated and replace the <WAZUH_DASHBOARD_URL> field with the corresponding URL.

      You can leave the rest of the values as default.

    5. In the Group Attribute Statements section put Roles as the name. The value for Roles will be used as the roles_key parameter in the Wazuh indexer configuration. For the filter field, select Matches regex and type .*.

    6. Proceed by clicking next and on the feedback page, select the options seen in the screenshot below. Click on Finish and proceed to the next step.

  6. Add the new app to the new group. Navigate to Directory > Groups and select your group. Click on Applications and select Assign Applications. From here, assign the app created in step 5 and click on Done to save the changes.

  7. Note the necessary parameters from the SAML settings of the new app. The parameters already obtained during the integration are:

    • sp.entity_id: wazuh-saml

    • roles_key: Roles

    • kibana_url: https://<WAZUH_DASHBOARD_URL>

    • backend_roles: wazuh-admins

    To obtain the remaining parameters, navigate to Applications > Applications, select your app and click Sign On.

    Under SAML Signing Certificates, select View IdP metadata of the active certificate. This will open in a new tab. Copy the URL as this will be the idp.metadata_url.

    Now, on the same page, click on View SAML setup instructions. Copy the Identity Provider Issuer URL, it will be the idp.entity_id.

Wazuh indexer configuration

Edit the Wazuh indexer security configuration files. We recommend that you back up these files before you carry out the configuration.

  1. Generate a 64-character long random key using the following command.

    openssl rand -hex 32

    The output will be used as the exchange_key in the /etc/wazuh-indexer/opensearch-security/config.yml file.

  2. Edit the /etc/wazuh-indexer/opensearch-security/config.yml file and change the following values:

    • Set the order in basic_internal_auth_domain to 0 and the challenge flag to false.

    • Include a saml_auth_domain configuration under the authc section similar to the following:

        authc:
...
      basic_internal_auth_domain:
        description: "Authenticate via HTTP Basic against internal users database"
        http_enabled: true
        transport_enabled: true
        order: 0
        http_authenticator:
          type: "basic"
          challenge: false
        authentication_backend:
          type: "intern"
      saml_auth_domain:
        http_enabled: true
        transport_enabled: false
        order: 1
        http_authenticator:
          type: saml
          challenge: true
          config:
            idp:
              metadata_url: 'https://....okta.com/app/..../sso/saml/metadata'
              entity_id: 'http://www.okta.com/....'
            sp:
              entity_id: wazuh-saml
            kibana_url: https://<WAZUH_DASHBOARD_URL>
            roles_key: Roles
            exchange_key: 'b1d6dd32753374557dcf92e241.........'
        authentication_backend:
          type: noop

    Ensure to change the following parameters to their corresponding value:

    • idp.metadata_url

    • idp.entity_id

    • sp.entity_id

    • kibana_url

    • roles_key

    • exchange_key

  3. Run the securityadmin script to load the configuration changes made in the config.yml file.

    # export JAVA_HOME=/usr/share/wazuh-indexer/jdk/ && bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh -f /etc/wazuh-indexer/opensearch-security/config.yml -icl -key /etc/wazuh-indexer/certs/admin-key.pem -cert /etc/wazuh-indexer/certs/admin.pem -cacert /etc/wazuh-indexer/certs/root-ca.pem -h localhost -nhnv

    The -h flag specifies the hostname or the IP address of the Wazuh indexer node. Note that this command uses localhost, set your Wazuh indexer address if necessary.

    The command output must be similar to the following:

    Security Admin v7
Will connect to localhost:9200 ... done
Connected as "CN=admin,OU=Wazuh,O=Wazuh,L=California,C=US"
OpenSearch Version: 2.19.4
Contacting opensearch cluster 'opensearch' and wait for YELLOW clusterstate ...
Clustername: wazuh-cluster
Clusterstate: GREEN
Number of nodes: 1
Number of data nodes: 1
.opendistro_security index already exists, so we do not need to create one.
Populate config from /home/wazuh-user
Will update '/config' with /etc/wazuh-indexer/opensearch-security/config.yml
   SUCC: Configuration for 'config' created or updated
SUCC: Expected 1 config types for node {"updated_config_types":["config"],"updated_config_size":1,"message":null} is 1 (["config"]) due to: null
Done with success

  4. Edit the /etc/wazuh-indexer/opensearch-security/roles_mapping.yml file and change the following values:

    Configure the roles_mapping.yml file to map the Okta group to the appropriate Wazuh indexer role. In our case, we map it to the all_access role:

    all_access:
  reserved: false
  hidden: false
  backend_roles:
  - "admin"
  - "<GROUP_NAME>"

    Replace <GROUP_NAME> with the name you gave to your group in Step 3. In our case, this is wazuh-admins.

  5. Run the securityadmin script to load the configuration changes made in the roles_mapping.yml file.

    # export JAVA_HOME=/usr/share/wazuh-indexer/jdk/ && bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh -f /etc/wazuh-indexer/opensearch-security/roles_mapping.yml -icl -key /etc/wazuh-indexer/certs/admin-key.pem -cert /etc/wazuh-indexer/certs/admin.pem -cacert /etc/wazuh-indexer/certs/root-ca.pem -h localhost -nhnv

    The -h flag specifies the hostname or the IP address of the Wazuh indexer node. Note that this command uses localhost, set your Wazuh indexer address if necessary.

    The command output must be similar to the following:

    Security Admin v7
Will connect to localhost:9200 ... done
Connected as "CN=admin,OU=Wazuh,O=Wazuh,L=California,C=US"
OpenSearch Version: 2.19.4
Contacting opensearch cluster 'opensearch' and wait for YELLOW clusterstate ...
Clustername: wazuh-cluster
Clusterstate: GREEN
Number of nodes: 1
Number of data nodes: 1
.opendistro_security index already exists, so we do not need to create one.
Populate config from /home/wazuh-user
Will update '/rolesmapping' with /etc/wazuh-indexer/opensearch-security/roles_mapping.yml
   SUCC: Configuration for 'rolesmapping' created or updated
SUCC: Expected 1 config types for node {"updated_config_types":["rolesmapping"],"updated_config_size":1,"message":null} is 1 (["rolesmapping"]) due to: null
Done with success

Wazuh dashboard configuration

  1. Verify that run_as is set to true in the /usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml configuration file. This is required to create a role mapping in the Wazuh dashboard, ensuring the backend role provided by the IdP is correctly mapped to the corresponding Wazuh role.

    hosts:
  - default:
      url: https://localhost
      port: 55000
      username: wazuh-wui
      password: "<WAZUH_WUI_PASSWORD>"
      run_as: true

  2. Click ☰ to open the menu on the Wazuh dashboard, go to Server management > Security, and then Roles mapping to open the page.

    Wazuh role mapping

    1. Click Create Role mapping and complete the empty fields with the following parameters:

      • Role mapping name: Assign a name to the role mapping.

      • Roles: Select administrator.

      • Custom rules: Click Add new rule to expand this field.

      • User field: backend_roles

      • Search operation: FIND

      • Value: Assign the name you gave to your group in Step 3 of Okta configuration, in our case, this is wazuh-admins.

      • Click Save role mapping to save and map the backend role with Wazuh as administrator.

      Create Wazuh role mapping

  3. Edit the Wazuh dashboard configuration file. Add these configurations to /etc/wazuh-dashboard/opensearch_dashboards.yml. We recommend that you back up these files before you carry out the configuration.

    opensearch_security.auth.multiple_auth_enabled: true
opensearch_security.auth.type: ["basicauth","saml"]
server.xsrf.allowlist: ["/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout", "/_opendistro/_security/saml/acs/idpinitiated"]

  4. Restart the Wazuh dashboard service using this command:

    # systemctl restart wazuh-dashboard

  5. Test the configuration, go to your Wazuh dashboard URL and log in with your Okta account.

Setup Okta single sign-on with read-only role

Follow these steps to integrate Okta IdP with Wazuh for single sign-on and grant read-only role to the authenticated Okta users on the Wazuh platform:

  1. Okta configuration

  2. Wazuh indexer configuration

  3. Wazuh dashboard configuration

Okta configuration

  1. Create an account on Okta. Request a free trial if you don't have a paid license.

  2. Create a new user.

    1. From your okta admin console page, navigate to Directory > People.

    2. From the People section, select Add Person, fill in the details of the new user, and click Save as seen in the following screenshots.

  3. Create a new group. Navigate to Directory > Groups and add a group.

    Create a new group using any name. In our case, we name it wazuh-readonly. This name will be used as our backend_roles for Wazuh role mapping.

  4. Add the new user to the new group. Navigate to Directory > Groups and select your group. Click on Assign People and add the user to the group created.

  5. Create a new app. Configure the SAML settings while you create the app.

    1. Navigate to the Applications section in Okta. Select Create App Integration.

    2. In the Create a new application integration window, select SAML 2.0 and click Next.

    3. Assign a name to the application, in our case, we assign the name wazuh-sso-app.

    4. In the Configure SAML menu, you’ll find the SAML Settings section, modify the following parameters:

      • Single sign on URL: input https://<WAZUH_DASHBOARD_URL>/_opendistro/_security/saml/acs and replace the <WAZUH_DASHBOARD_URL> field with the corresponding URL.

      • Audience URI (SP Entity ID): input wazuh-saml. This is the SP Entity ID value which will be used later in the config.yml on the Wazuh indexer instance.

      • Other Requestable SSO URLs: click on Show Advanced Settings to access this option. Input https://<WAZUH_DASHBOARD_URL>/_opendistro/_security/saml/acs/idpinitiated and replace the <WAZUH_DASHBOARD_URL> field with the corresponding URL.

      You can leave the rest of the values as default.

    5. In the Group Attribute Statements section, put Roles as the name. The value for Roles will be used as the roles_key parameter in the Wazuh indexer configuration. For the filter field, select Matches regex and type .*.

    6. Proceed by clicking next and on the feedback page, select the options seen in the screenshot below. Click on Finish and proceed to the next step.

  6. Add the new app to the new group. Navigate to Directory > Groups and select your group. Click on Applications and select Assign Applications. From here, assign the app created in step 5 and click on Done to save the changes.

  7. Note the necessary parameters from the SAML settings of the new app. The parameters already obtained during the integration are:

    • sp.entity_id: wazuh-saml

    • roles_key: Roles

    • kibana_url: https://<WAZUH_DASHBOARD_URL>

    • backend_roles: wazuh-readonly

    To obtain the remaining parameters, navigate to Applications > Applications, select your app and click Sign On.

    Under SAML Signing Certificates, select View IdP metadata of the active certificate. This will open in a new tab. Copy the URL as this will be the idp.metadata_url.

    Now, on the same page, click on View SAML setup instructions. Copy the Identity Provider Issuer URL, it will be the idp.entity_id.

Wazuh indexer configuration

Edit the Wazuh indexer security configuration files. We recommend that you back up these files before you carry out the configuration.

  1. Generate a 64-character long random key using the following command.

    openssl rand -hex 32

    The output will be used as the exchange_key in the /etc/wazuh-indexer/opensearch-security/config.yml file.

  2. Edit the /etc/wazuh-indexer/opensearch-security/config.yml file and change the following values:

    • Set the order in basic_internal_auth_domain to 0 and the challenge flag to false.

    • Include a saml_auth_domain configuration under the authc section similar to the following:

        authc:
...
      basic_internal_auth_domain:
        description: "Authenticate via HTTP Basic against internal users database"
        http_enabled: true
        transport_enabled: true
        order: 0
        http_authenticator:
          type: "basic"
          challenge: false
        authentication_backend:
          type: "intern"
      saml_auth_domain:
        http_enabled: true
        transport_enabled: false
        order: 1
        http_authenticator:
          type: saml
          challenge: true
          config:
            idp:
              metadata_url: 'https://....okta.com/app/..../sso/saml/metadata'
              entity_id: "http://www.okta.com/...."
            sp:
              entity_id: wazuh-saml
            kibana_url: https://<WAZUH_DASHBOARD_URL>
            roles_key: Roles
            exchange_key: 'b1d6dd32753374557dcf92e241.........'
        authentication_backend:
          type: noop

    Ensure to change the following parameters to their corresponding value:

    • idp.metadata_url

    • idp.entity_id

    • sp.entity_id

    • kibana_url

    • roles_key

    • exchange_key

  3. Run the securityadmin script to load the configuration changes made in the config.yml file.

    # export JAVA_HOME=/usr/share/wazuh-indexer/jdk/ && bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh -f /etc/wazuh-indexer/opensearch-security/config.yml -icl -key /etc/wazuh-indexer/certs/admin-key.pem -cert /etc/wazuh-indexer/certs/admin.pem -cacert /etc/wazuh-indexer/certs/root-ca.pem -h localhost -nhnv

    The -h flag specifies the hostname or the IP address of the Wazuh indexer node. Note that this command uses localhost, set your Wazuh indexer address if necessary.

    The command output must be similar to the following:

    Security Admin v7
Will connect to localhost:9200 ... done
Connected as "CN=admin,OU=Wazuh,O=Wazuh,L=California,C=US"
OpenSearch Version: 2.19.4
Contacting opensearch cluster 'opensearch' and wait for YELLOW clusterstate ...
Clustername: wazuh-cluster
Clusterstate: GREEN
Number of nodes: 1
Number of data nodes: 1
.opendistro_security index already exists, so we do not need to create one.
Populate config from /home/wazuh-user
Will update '/config' with /etc/wazuh-indexer/opensearch-security/config.yml
   SUCC: Configuration for 'config' created or updated
SUCC: Expected 1 config types for node {"updated_config_types":["config"],"updated_config_size":1,"message":null} is 1 (["config"]) due to: null
Done with success

Wazuh dashboard configuration

  1. Create a new role mapping for the backend role. Follow these steps to create a new role mapping, and grant read-only permissions to the backend role.

    1. Log into the Wazuh dashboard as administrator.

    2. Click the upper-left menu icon ☰ to open the options, go to Indexer management > Security, and then Roles to open the roles page.

    3. Click Create role, complete the empty fields with the following parameters, and then click Create to complete the task.

      • Name: Assign a name to the role.

      • Cluster permissions: cluster_composite_ops_ro

      • Index: *

      • Index permissions: read

      • Tenant permissions: global_tenant and select the Read only option.

    4. Select the newly created role.

    5. Select the Mapped users tab and click Manage mapping.

    6. Under Backend roles, add the name of the read-only group you created in Okta and click Map to confirm the action. In our case, the backend role is wazuh-readonly.

  2. Verify that run_as is set to true in the /usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml configuration file. This is required to create a role mapping in the Wazuh dashboard, ensuring the backend role provided by the IdP is correctly mapped to the corresponding Wazuh role.

    hosts:
  - default:
      url: https://localhost
      port: 55000
      username: wazuh-wui
      password: "<WAZUH_WUI_PASSWORD>"
      run_as: true

  3. Click ☰ to open the menu on the Wazuh dashboard, go to Server management > Security, and then Roles mapping to open the page.

    Wazuh role mapping

    1. Click Create Role mapping and complete the empty fields with the following parameters:

      • Role mapping name: Assign a name to the role mapping.

      • Roles: Select readonly.

      • Custom rules: Click Add new rule to expand this field.

      • User field: backend_roles

      • Search operation: FIND

      • Value: Assign the name you gave to your group in Step 3 of Okta configuration, in our case, this is wazuh-readonly.

      • Click Save role mapping to save and map the backend role with Wazuh as read-only.

      Create Wazuh role mapping

  4. Edit the Wazuh dashboard configuration file. Add these configurations to /etc/wazuh-dashboard/opensearch_dashboards.yml. We recommend that you back up these files before you carry out the configuration.

    opensearch_security.auth.multiple_auth_enabled: true
opensearch_security.auth.type: ["basicauth","saml"]
server.xsrf.allowlist: ["/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout", "/_opendistro/_security/saml/acs/idpinitiated"]

  5. Restart the Wazuh dashboard service.

    # systemctl restart wazuh-dashboard

  6. Test the configuration. Go to your Wazuh dashboard URL and log in with your Okta account.