[SSO] Considering adding a new section for the configuration of ODFE and different SAML providers

[MiguelCasaresRobles]

Hello team,

Opendistro has many security features that we may consider to add as a guide in our documentation.

Introduction

In this guide, you can find some instructions to configure Single Sign On in Kibana using several Identity Providers (IdP) and the Open Distro for Elasticsearch Security plugin.

The guide assumes you already have an Open Distro installation. You can find instructions to install Open Distro for Elasticsearch in the Open Distro documentation: https://opendistro.github.io/for-elasticsearch-docs/docs/install/

The IdP covered are:

• Okta
• Azure Active Directory
• PingOne
• Google
• Jumpcloud

Required parameters

We will need to know some parameters to make the configurations:

• idp.metadata_url: URL to a XML file that contains metadata information about the application configured on the IdP side. It's used instead of idp.metadata_file
• idp.metadata_file: XML File that contains the Metadata information about the application configured on the IdP side. It's used instead of idp.metadata_url
• idp.entity_id: Entity ID of the Identity Provider.
• sp.entity_id: Entity ID of the Service Provider.
• kibana_url: URL to access Kibana.
• roles_key: The attribute in the SAML assertion where the roles/groups are sent.
• exchange_key: The key that will be used to sign the assertions.

Identity Providers

Okta

# Okta Web: https://www.okta.com/ ## Steps list: **1- Create an account in Okta. Request a free trial if you don't have a paid license.** **2- Create a new user. This step can be skipped if you are just testing, you can use your Okta admin user for the example.** **3- Create a new group.** **4- Add the new user to the new group.** **5- Create a new app. Configure the SAML settings while you create the app.** **6- Add the new app to the new group.** **7- Note the necessary parameters from the new app's SAML settings.** **8- Configure Open Distro security configuration files.** **9- Run the Open Distro security admin script to apply the changes made to the configuration files.** **10- Configure the Kibana configuration file.** **11- Restart Kibana.** **12- Test the configuration.** ## Detailed steps: **1- Create an account in Okta. Request a free trial if you don't have a paid license.** **2- Create a new user. This step can be skipped if you are just testing, you can use your Okta admin user for the example.** Go to Directory → People   **3- Create a new group.** Go to Directory → Groups and add a group.   The name you give to your group will be used in the configuration. It will be our `backend_roles` in `roles_mapping.yml`. **4- Add the new user to the new group.** Go to Directory → Groups → **your group**. Click on `Manage People`. Add your user and save the changes.  **5- Create a new app. Configure the SAML settings while you create the app.** Go to Applications → Applications and click on `Add Aplication` and then `Create New App`.   In the `Create a New Application Integration` window, select `Web` platform and `SAML 2.0` sign-on method:  We will be sent to the application configuration. The name of the example application is `wazuh-odfe-app`:  As `Single sign on URL`, write `/_opendistro/_security/saml/acs` (put the correct values in your case). As `Audience URI (SP Entity ID)` write `wazuh-saml`. This `wazuh-saml` will be the `sp.entity_id` in our Open Distro configuration.  In the Group Attribute Statements section, we will put `Roles` as the name. `Roles` will be our `roles_key` parameter in the Open Distro configuration. In value, select `Matches regex` and type `.*`:   **6- Add the new app to the new group.** Go to Directory → Groups → **your group**. Click on `Manage Apps`. Add your app and save the changes. **7- Note the necessary parameters from the new app's SAML settings.** The parameters we already have are: - `sp.entity_id` - `roles_key` - `kibana_url` To have the remaining parameters we need to go to Applications → Applications → **your app** → Sign On. Copy the `Identity Provider metadata` URL. It will be the `idp.metadata_url`:  Now, in the same page, click on `View Setup Instructions`. Copy the `Identity Provider Issuer` URL, it will be our `idp.entity_id`. The X.509 Certificate will be our `exchange_key`:  This information can also be found in the metadata XML file. **8- Configure Open Distro security configuration files.** We will need to configure some files in `/usr/share/elasticsearch/plugins/opendistro_security/securityconfig/`. The files we will configure are `config.yml`, `roles_mapping.yml`, `roles.yml` and `internal_users.yml` - **config.yml** Under the `authc` section, we have to include a `saml_auth_domain` configuration similar to the following: ```yml saml_auth_domain: http_enabled: true transport_enabled: true 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:// roles_key: Roles exchange_key: '...' authentication_backend: type: noop ``` The `order` should be lower than the one in `basic_internal_auth_domain`. - **internal_users.yml** We will create a user: ```yml wazuh_admin: hash: $2y$12$gddqUUijvzAx/QFunvdNzeu3gN/VU7hwtz.QL4Rywwg9crog1wAvG reserved: no backend_roles: - "admin" description: "Wazuh admin user" ``` - **roles.yml** We will create a role for our user. In my case, the role is `service_wazuh_admin_role` and has full privileges: ```yml service_wazuh_admin_role: reserved: true index_permissions: - index_patterns: - "*" allowed_actions: - "*" tenant_permissions: - tenant_patterns: - "*" allowed_actions: - kibana_all_write cluster_permissions: - "*" ``` - **roles_mapping.yml** We will map our user to the role that we created and the role that we have in Okta: ```yml service_wazuh_admin_role: reserved: true users: - "wazuh_admin" backend_roles: - "" ``` Replace `` with the name you gave to your group in Step 3. **9- Run the Open Distro security admin script to apply the changes made to the configuration files.** If we want these configuration files to take effect, we have to run the security admin script. This configuration will be stored in an internal index. ```bash bash /usr/share/elasticsearch/plugins/opendistro_security/tools/securityadmin.sh -f /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/.yml -icl -key /usr/share/elasticsearch/config/.pem -cert /usr/share/elasticsearch/config/.pem -cacert /usr/share/elasticsearch/config/.pem -h -nhnv ``` We have to run the previous command (modifying the values in brackets) for all the configuration files. **10- Configure the Kibana configuration file.** We have to add these two lines in `kibana.yml`: ```yml opendistro_security.auth.type: "saml" server.xsrf.whitelist: ["/_opendistro/_security/saml/acs/idpinitiated", "/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"] ``` **11- Restart Kibana.** **12- Test the configuration.** Go to your Kibana URL and log in with your Okta account.

Azure Active Directory

# Azure Active Directory Web: https://portal.azure.com/ Note that you will have to request a free trial at least to make the configuration. You can do it in the process. ## Steps list: **1- Create a Microsoft account or use your own one if you already have one.** **2- Go to https://portal.azure.com/ and sign in with your Microsoft account.** **3- Create an app in `Azure Active Directory`:** **4- Create a role for your application.** **5- Assign a user to the app.** **6- Configure Single sign-on.** **7- Note the necessary parameters.** **8- Configure Open Distro security configuration files.** **9- Run the Open Distro security admin script to apply the changes made to the configuration files.** **10- Configure the Kibana configuration file.** **11- Restart Kibana.** **12- Test the configuration.** ## Detailed steps: **1- Create a Microsoft account or use your own one if you already have one.** **2- Go to https://portal.azure.com/ and sign in with your Microsoft account.** **3- Create an app in `Azure Active Directory`:** Go to `Azure Active Directory` → `Enterprise applications` and create a new application:   Select `Integrate any other application you don't find in the gallery`. Give a name to your application and click `Add`. I named my application `wazuh-sso`, but the name will not be used in the configuration. **4- Create a role for your application.** Go back to `Azure Active Directory` and click on `App registrations`:  Select your new app and click `Manifest`.  Add a new role to your application's `Manifest`: ```json { "allowedMemberTypes": [ "User" ], "description": "Wazuh role", "displayName": "Wazuh_role", "id": "", "isEnabled": true, "lang": null, "origin": "Application", "value": "Wazuh_role" }, ``` - `description`: can be any value that you want. - `id` should be your application's ID. You can find it in the application's overview menu or at the top of the Manifest in the field `appId`. - `value` will define the name of the role. In this case, `Wazuh_role` will be our value for the role to be mapped on the roles_mapping.yml file. - `displayName` should be the same as `value`.  Don't forget to save the changes. **5- Assign a user to the app.** In `Azure Active Directory`, go to `Enterprise applications` → your application → `Assign users and groups` (or `Users and Groups` in the pannel to the left):  Assign your user and select the role we created in `Manifest`.  **6- Configure Single sign-on.** Go to `Enterprise applications` → your application → `Set up single sign on` -> `SAML`   - In Step 1 `Basic SAML Configuration`, set `wazuh-saml` as `Identifier (Entity ID)` and `https:///_opendistro/_security/saml/acs` as `Reply URL (Assertion Consumer Service URL)`.  - In Step 2 `User Attributes & Claims`, click `Add new claim`. Select `Roles` as the name and `user.assignedroles` as `Source attribute`. This claim will be mapped with `roles_key` on the Open Distro configuration.  **7- Note the necessary parameters.** Still in the same menu `Enterprise applications` → your application → `Single sign-on`, let's note some parameters we will need in the Open Distro configuration. - In Step 3 `SAML Signing Certificate`, `App Federation Metadata Url` will be our `idp.metadata_url`. Go to the metadata URL using your web browser and note the `X509Certificate`. It will be our `exchange_key`:  - In Step 4 `Set up `, the `Azure AD Identifier` will be our `idp.entity_id`. **8- Configure Open Distro security configuration files.** We will need to configure some files in `/usr/share/elasticsearch/plugins/opendistro_security/securityconfig/`. The files we will configure are `config.yml`, `roles_mapping.yml`. - **config.yml** Under the `authc` section, we have to include a `saml_auth_domain` configuration similar to the following: ```yml saml_auth_domain: http_enabled: true transport_enabled: false order: 1 http_authenticator: type: saml challenge: true config: idp: metadata_url: https://login.microsoftonline.com/... entity_id: https://sts.windows.net/... sp: entity_id: wazuh-saml kibana_url: https:// roles_key: Roles exchange_key: '...' authentication_backend: type: noop ``` In order for this to work we should also change the `challenge: true` of the basic_internal_auth_domain to `challenge: false`. The `roles_key` should be the same value that we used on step 6.2. - **roles_mapping.yml** We will map the role that we have in Azure AD to the admin role on Elasticsearch. In my case, `Wazuh_role`: ```yml all_access: reserved: false backend_roles: - "admin" - "Wazuh_role" description: "Maps admin to all_access" ``` **9- Run the Open Distro security admin script to apply the changes made to the configuration files.** If we want these configuration files to take effect, we have to run the security admin script. This configuration will be stored in an internal index. ```bash bash /usr/share/elasticsearch/plugins/opendistro_security/tools/securityadmin.sh -f /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/.yml -icl -key /usr/share/elasticsearch/config/.pem -cert /usr/share/elasticsearch/config/.pem -cacert /usr/share/elasticsearch/config/.pem -h -nhnv ``` We have to run the previous command (modifying the values in brackets) for all the configuration files. **10- Configure the Kibana configuration file.** We have to add these two lines in `kibana.yml`: ```yml opendistro_security.auth.type: "saml" server.xsrf.whitelist: ["/_opendistro/_security/saml/acs/idpinitiated", "/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"] ``` **11- Restart Kibana.** **12- Test the configuration.**

PingOne

# PingOne Web: https://www.pingidentity.com/ ## Steps list: **1- Create an account in Ping Identity. Request a free trial if you don't have a paid license.** **2- Go to https://console.pingone.com/ and sign in with your Ping Identity account.** **3- Create an app in `Connections`** **4- Create a group and assign users** **5- Activate application and note the necessary parameters.** **6- Configure Open Distro security configuration files.** **7- Run the Open Distro security admin script to apply the changes made to the configuration files.** **8- Configure the Kibana configuration file.** **9- Restart Kibana.** **10- Test the configuration.** ## Detailed steps: **1- Create an account in Ping Identity. Request a free trial if you don't have a paid license.** **2- Go to https://console.pingone.com/ and sign in with your Ping Identity account.** **3- Create an app in `Connections`** Go to `Connections` -> `Applications` -> `Add Application`. Select `Web App` and then `SAML` -> `Configure`   Give a name to your application and click Next. I named my application `wazuh-sso`, but the name will not be used in the configuration. Select `Manually Enter` on the `Provide App Metadata`  Add the proper configuration: ACS URLS: `https:///_opendistro/_security/saml/acs` ENTITY ID: `wazuh-saml` SLO ENDPOINT: `https:///` SLO BINDING: `HTTP Redirect` ASSERTION VALIDITY DURATION: `3600` (for 1 hour token validity) VERIFICATION CERTIFICATE (OPTIONAL): Load a PUBLIC CERTIFICATE that corresponds to the PRIVATE KEY that is going to be used on the `sp.signature_private_key_filepath` of the `config.yml` ODFE configuration file. **This is necessary as all the logout requests must be signed** On the Next configuration page `Attribute Mapping` select `ADD ATTRIBUTE` with the following configuration: `Group Names` = `Roles`  Save & Close **4- Create a group and assign users** Go to `Identities` -> `Groups` -> `+`  Select the name of the Group, in this case `Role` (this corresponds with the value that we are going to use on the `roles_mapping.yml` ODFE configuration file).  Finish & Save Now open the created Group and go to `Members` -> `Add Members Manually`  Add all the members that you want to use to login to Kibana. **5- Activate application and note the necessary parameters. Go to `Connections` -> `Applications` and click on the enablement control for the application.  Now we should take note of the following parameters to use on the next step: `ISSUER ID` : it'll be on the form `https://auth.pingone.com/....` `IDP METADATA URL` If you open IDP METADATA URL you'll find the `X509Certificate` section will be our `exchange_key`: **6- Configure Open Distro security configuration files.** We will need to configure some files in `/usr/share/elasticsearch/plugins/opendistro_security/securityconfig/`. The files we will configure are `config.yml`, `roles_mapping.yml`. - **config.yml** Under the `authc` section, we have to include a `saml_auth_domain` configuration similar to the following: ```yml saml_auth_domain: http_enabled: true transport_enabled: false order: 1 http_authenticator: type: saml challenge: true config: idp: metadata_url: IDP METADATA URL entity_id: ISSUER ID sp: entity_id: wazuh-saml signature_private_key_filepath: PRIVATE_KEY forceAuthn: true kibana_url: https:// roles_key: Roles exchange_key: 'X509Certificate' authentication_backend: type: noop ``` In order for this to work we should also change the `challenge: true` of the basic_internal_auth_domain to `challenge: false` - **roles_mapping.yml** We will map the Group that we have in PingOne to the admin role on Elasticsearch. In my case, `Role`: ```yml all_access: reserved: false backend_roles: - "admin" - "Role" description: "Maps admin to all_access" ``` **7- Run the Open Distro security admin script to apply the changes made to the configuration files.** If we want these configuration files to take effect, we have to run the security admin script. This configuration will be stored in an internal index. ```bash bash /usr/share/elasticsearch/plugins/opendistro_security/tools/securityadmin.sh -f /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/.yml -icl -key /usr/share/elasticsearch/config/.pem -cert /usr/share/elasticsearch/config/.pem -cacert /usr/share/elasticsearch/config/.pem -h -nhnv ``` We have to run the previous command (modifying the values in brackets) for all the configuration files. **8- Configure the Kibana configuration file.** We have to add these two lines in `kibana.yml`: ```yml opendistro_security.auth.type: "saml" server.xsrf.whitelist: ["/_opendistro/_security/saml/acs/idpinitiated", "/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"] ``` **9- Restart Kibana.** **10- Test the configuration.**

Google

# Google Web: https://workspace.google.com/ ## Steps list: **1- Create an account in Google Workspace. Request a free trial if you don't have a paid license.** **2- Go to https://admin.google.com/ac/apps/unified and sign in with your Google Admin account.** **3- Create and app with `Add custom SAML app`** **4- Turn ON acces for everyone** **5- Define attribute for users** **6- Configure Open Distro security configuration files.** **7- Run the Open Distro security admin script to apply the changes made to the configuration files.** **8- Configure the Kibana configuration file.** **9- Restart Kibana.** **10- Test the configuration.** ## Detailed steps: **1- Create an account in Google Workspace. Request a free trial if you don't have a paid license.** **2- Go to https://admin.google.com/ac/apps/unified and sign in with your Google Admin account.** **3- Create and app with `Add custom SAML app`** Go to `Add App` -> `Add custom SAML app`. Enter an `App name` and Continue  We should take note of the following parameters to use on the ODFE configuration: `Entity ID` Select `DOWNLOAD METADATA` and keep this file. It will need to be uploaded to some web server (or store it on a specific folder to access it locally by the server) in order to use it on the ODFE configuration file  After this, select Continue. Add the proper configuration: ACS URL: `https:///_opendistro/_security/saml/acs` ENTITY ID: `wazuh-saml`  The rest remains as default, select CONTINUE Google doesn't support sending the Group membership attribute as part of the SAML Assertion (as the other Identity Providers do) so in this example we are going to use `Department` as the attribute that will matched against the Elasticsearch role. In this case the `Department`attribute will be stored as `Roles`:  Select FINISH. **4- Turn ON acces for everyone** Select you recently create app and go into `User access`  Select `ON for everyone` and Save  You can also control the App access through Groups (not covered on this guide). **5- Define attribute for users** Go to `Directory` -> `Users`  Select a user and go to `User information` then edit `Employee information`  Add a value on `Department` in this example `Wazuh_access` and Save  **6- Configure Open Distro security configuration files.** We will need to configure some files in `/usr/share/elasticsearch/plugins/opendistro_security/securityconfig/`. The files we will configure are `config.yml`, `roles_mapping.yml`. - **config.yml** Under the `authc` section, we have to include a `saml_auth_domain` configuration similar to the following: ```yml saml_auth_domain: http_enabled: true transport_enabled: false order: 1 http_authenticator: type: saml challenge: true config: idp: metadata_url: DOWNLOADED METADATA URL entity_id: ENTITY ID sp: entity_id: wazuh-saml kibana_url: https:// roles_key: Roles exchange_key: 'X509Certificate' authentication_backend: type: noop ``` _Note: the parameter `metadata_url` can be changed by `metadata_file` and use a local path where the downloaded metadata files is going to be stored._ In order for this to work we should also change the `challenge: true` of the basic_internal_auth_domain to `challenge: false` - **roles_mapping.yml** We will map the `Department` attribute value that we have in Google to the admin role on Elasticsearch. In my case, `Wazuh_access`: ```yml all_access: reserved: false backend_roles: - "admin" - "Wazuh_access" description: "Maps admin to all_access" ``` **7- Run the Open Distro security admin script to apply the changes made to the configuration files.** If we want these configuration files to take effect, we have to run the security admin script. This configuration will be stored in an internal index. ```bash bash /usr/share/elasticsearch/plugins/opendistro_security/tools/securityadmin.sh -f /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/.yml -icl -key /usr/share/elasticsearch/config/.pem -cert /usr/share/elasticsearch/config/.pem -cacert /usr/share/elasticsearch/config/.pem -h -nhnv ``` We have to run the previous command (modifying the values in brackets) for all the configuration files. **8- Configure the Kibana configuration file.** We have to add these two lines in `kibana.yml`: ```yml opendistro_security.auth.type: "saml" server.xsrf.whitelist: ["/_opendistro/_security/saml/acs/idpinitiated", "/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"] ``` **9- Restart Kibana.** **10- Test the configuration.**

Jumpcloud

# Jumpcloud Web: https://jumpcloud.com/ ## Steps list: **1- Create an account in Jumpcloud. Request a free trial if you don't have a paid license.** **2- Create a new user. This step can be skipped if you are just testing, you can use your Jumpcloud admin user for the example.** **3- Create a new group and assign the user** **4- Create a new app. Configure the SAML settings while you create the app.** **5- Note the necessary parameters from the new app's SAML settings.** **6- Configure Open Distro security configuration files.** **7- Run the Open Distro security admin script to apply the changes made to the configuration files.** **8- Configure the Kibana configuration file.** **9- Restart Kibana.** **10- Test the configuration.** ## Detailed steps: **1- Create an account in Jumpcloud. Request a free trial if you don't have a paid license.** **2- Create a new user. This step can be skipped if you are just testing, you can use your Jumpcloud admin user for the example.** Go to User Management -> Users -> (+) -> Manual user entry  **3- Create a new group and assign the user** Go to User Management -> User Groups -> (+)  The name you give to your group will be used in the configuration. It will be our backend_roles in roles_mapping.yml. Then go to the Users tab and select the newly created user.  Save the changes. **4- Create a new app. Configure the SAML settings while you create the app.** Go to SSO -> (+) -> Custom SAML App  Complete the SSO tab with the appropriate information    IdP Entity ID: `wazuh` (this will be the idp.entity_id in our Open Distro configuration) SP Entity ID: `wazuh-saml` (this will be the sp.entity_id in our Open Distro configuration) ACS URL: `https:///_opendistro/_security/saml/acs` Check Sign Assertion Check Declare Redirect Endpoint Check include group attribute and add `Roles` as the attribute The rest of the options have the default values. On the User Groups tab select the Group created previously  Click Activate **5- Note the necessary parameters from the new app's SAML settings.** Open the recently created application and go to the SSO tab, select Export Metadata  **6- Configure Open Distro security configuration files.** We will need to configure some files in `/usr/share/elasticsearch/plugins/opendistro_security/securityconfig/`. The files we will configure are `config.yml` and `roles_mapping.yml` - **config.yml** Under the `authc` section, we have to include a `saml_auth_domain` configuration similar to the following: ```yml saml_auth_domain: http_enabled: true transport_enabled: true order: 1 http_authenticator: type: saml challenge: true config: idp: metadata_file: entity_id: wazuh sp: entity_id: wazuh-saml kibana_url: https:// roles_key: Roles exchange_key: '...' authentication_backend: type: noop ``` The `order` should be lower than the one in `basic_internal_auth_domain`. - **roles_mapping.yml** We will map our user to the role that we created and the role that we have in Jumpcloud: ```yml all_access: reserved: false backend_roles: - "admin" - "Wazuh admins" description: "Maps admin to all_access" ``` **7- Run the Open Distro security admin script to apply the changes made to the configuration files.** If we want these configuration files to take effect, we have to run the security admin script. This configuration will be stored in an internal index. ```bash bash /usr/share/elasticsearch/plugins/opendistro_security/tools/securityadmin.sh -f /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/.yml -icl -key /usr/share/elasticsearch/config/.pem -cert /usr/share/elasticsearch/config/.pem -cacert /usr/share/elasticsearch/config/.pem -h -nhnv ``` We have to run the previous command (modifying the values in brackets) for all the configuration files. **8- Configure the Kibana configuration file.** We have to add these two lines in `kibana.yml`: ```yml opendistro_security.auth.type: "saml" server.xsrf.whitelist: ["/_opendistro/_security/saml/acs/idpinitiated", "/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"] ``` **9- Restart Kibana.** **10- Test the configuration.** # Troubleshooting - If something is wrong, you will get an error, commonly `samlAuthError` or `samlConfigError`. The best way to troubleshoot this is to look at the SAML response. Open the web browser's Dev Tools (F12), go to the `Network` menu and try to log in Kibana. Just before the error, you will probably see a POST request that contains the SAML response. It is in base64, so you will need to decode it and beautify the resultant XML. Base64 decoder: https://www.base64decode.org/ XML formatter: https://www.freeformatter.com/xml-formatter.html You can check the SAML response and see if something like the `Roles` configuration is missing. SAML Tracer is a browser extension that can also be used in order to obtain the SAML assertion already decoded: * For Chrome: https://chrome.google.com/webstore/detail/saml-tracer/mpdajninpobndbfcldcmbpnnbhibjmch?hl=en * For Firefox: https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/ - Enable debug logs. Open the file /etc/elasticsearch/log4j2.properties and add the following lines: ```java logger.token.name = com.amazon.dlic.auth.http.saml.Token logger.token.level = debug ``` - Run Elasticsearch or Kibana in debug mode. # More information https://opendistro.github.io/for-elasticsearch-docs/docs/security/configuration/saml/

[ar0dd]

Can someone elaborate under "details" for 9- Run the Open Distro security admin script to apply the changes made to the configuration files.

[dami-nicastro]

Hi team!

We will add instructions for SSO login using "onelogin" IDP application Website: [https://www.onelogin.com]

Steps list:

1- Create an account in onelogin. Request a free trial if you don't have a paid license. 2-Add the onelogin extension in your browser 3- Create a new user. This step can be skipped if you are just testing, you can use your onelogin admin user for the example. 4- Create a new app using the "SAML Custom Connector (Advanced)" template. Configure the SAML settings while you create the app. 5- Add the created user to the new app. 6-Get the metada.xml file and X.509 certificate from the application 7- Configure Open Distro security configuration files. 8- Run the Open Distro security admin script to apply the changes made to the configuration files. 9- Configure the Kibana configuration file. 10- Change the logout configuration in Kibana 11- Restart Kibana. 12- Test the configuration.

Detailed steps:

**1- Create an account in onelogin. Request a free trial if you don't have a paid license.

**2-Add the onelogin extension in your browser

**3- Create a new user. This step can be skipped if you are just testing, you can use your onelogin admin user for the example. Login to onelogin web console, select "Administration" >> "Users" >>"New User"

On the created user complete the mandatory fields and include also the field that we will use to send to Kibana as external role (Backend role) and map to Kibana roles. In this example, we use the field "Department":

**4- Create a new app using the "SAML Custom Connector (Advanced)" template. Configure the SAML settings while you create the app. Go to "Applications" tab >> "Applications" and the click on "Add app"

Select the "SAML Custom Connector (Advanced)" application. In "Info" we selected the name "Wazuh" Go to "Configuration" tab and fill the information in red rectangles:

Go to "Parameters" tab and click on "+" to add a new parameter to the app:

In our example, we named the new parameter as "Roles", the we have to select the value "Department" and "Include in SAML assertion"

The rest of the app configuration is left as default.

**5- Add the created user to the new app Go to "Users" and select the created user. Go to "Applications" and click on "+" to add a new application:

**6-Get the metada_onelogin.xml file and X.509 certificate from the application Go to "Applications" tab >> "Applications" and then select the "Wazuh" app. Click on "More Actions" and then select "SAML Metadata"

Save the file as XML or open it, select all and save it in XMLformat. This will be our idp.metadata_file in Opendistro_security configuration. The idp.entity_id will be value of Issuer URL in SSO tab of the "Wazuh" app:

The sp.entity_id is the Audience (EntityID) in the "Configuration" tab of the "Wazuh" app:

The roles_key is the name of the parameter added in the "Wazuh" app. In our example is "Roles" Finally, to obtain the exchange_key go to SSO tab of the "Wazuh" app and select "View Details" in "X.509 Certificate". Copy the blob of the certificate excluding the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines:

**7- Configure Open Distro security configuration files. We will need to configure some files in /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/. The files we will configure are config.yml and roles_mapping.yml

- config.yml:

...
saml_auth_domain2:
         http_enabled: true
         transport_enabled: true
         order: 1
         http_authenticator:
           type: saml
           challenge: true
           config:
             idp:
               metadata_file: "/usr/share/elasticsearch/plugins/opendistro_security/securityconfig/metadata_onelogin.xml"
               entity_id: "https://app.onelogin.com/saml/metadata/xxxxxxx"
             sp:
               entity_id: wazuh-saml
             kibana_url: https://<kibana_ip>
             roles_key: Roles
             exchange_key: 'X.509 Certificate'
        authentication_backend:
           type: noop
...

- roles_mapping.yml:

---
# In this file users, backendroles and hosts can be mapped to Open Distro Security roles.
# Permissions for Opendistro roles are configured in roles.yml

_meta:
  type: "rolesmapping"
  config_version: 2

# Define your roles mapping here

## Demo roles mapping

all_access:
  reserved: false
  backend_roles:
  - "admin"
  - "wazuh"
  - "wazuh-admin"
  description: "Maps admin to all_access"
...

**8- Run the Open Distro security admin script to apply the changes made to the configuration files.

/usr/share/elasticsearch/plugins/opendistro_security/tools/securityadmin.sh -cd /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/ -nhnv -cacert /etc/elasticsearch/certs/root-ca.pem -cert /etc/elasticsearch/certs/admin.pem -key /etc/elasticsearch/certs/admin-key.pem -h localhost -icl

**9- Configure the Kibana configuration file. We have to add these two lines in kibana.yml:

opendistro_security.auth.type: "saml"
server.xsrf.whitelist: ["/_opendistro/_security/saml/acs/idpinitiated", "/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"]

10- Change the logout configuration in Kibana - /usr/share/kibana/plugins/opendistroSecurityKibana/server/auth/types/saml/routes.js**

...
    this.router.get({
      path: `/logout`,
      validate: false
...

**11- Restart Kibana.

# systemtl restart kibana

**12- Test the configuration. Go to your Kibana URL and log in with your onelogin account. Test also the logout.

[ryangniadek]

Hi - not all the filepaths line up in the instructions above as they are for an outdated version of Wazuh but for the most part I was able to figure it out (ex. /usr/share/elasticsearch/plugins/opendistro_security/securityconfig/ became /usr/share/wazuh-indexer/plugins/opensearch-security/securityconfig).

However, I am not able to figure out the equivalent file to kibana.yml in step 10 of the Okta instructions, can someone point me in the right direction? Thanks!

[ace-109]

Hi @ryangniadek, the document is currently being reworked and it will be updated to match the new version of wazuh very soon. Kibana.yml is now opensearch_dashboards.yml, you can find this in this path /etc/wazuh-dashboard/opensearch_dashboards.yml . Step 10 should look like this

opensearch_security.auth.type: "saml"
server.xsrf.whitelist: ["/_plugins/_security/saml/acs", "/_plugins/_security/saml/logout", "/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout", "/_opendistro/_security/saml/acs/idpinitiated"]

[ryangniadek]

In step 9, what is the updated paths for the following certs:

/usr/share/elasticsearch/config/<cert_key>.pem /usr/share/elasticsearch/config/<cert>.pem /usr/share/elasticsearch/config/<ca_cert>.pem

[ace-109]

@ryangniadek

/etc/wazuh-indexer/certs/admin-key.pem /etc/wazuh-indexer/certs/admin.pem /etc/wazuh-indexer/certs/root-ca.pem

There's an updated guide here that will be of help

[automate-this]

Is it possible to get the default login form with a "Login with SAML" button?