So you want to contribute code to this project? Excellent! We're glad you're here. Here's what you need to do.
This project is a plugin of OpenSearch-Dashboards. It requires an OpenSearch server running with the Security plugin installed. At the time of this writing there is a strict version check between these components, so we recommend running all of them from their respective branches with matching versions (this will also ensure they work well together before we cut a new release.)
As a prerequisite, please follow the developer guide of the Security Plugin. This will get a OpenSearch server running with security plugin enabled.
NOTE: If you are following this guide by the dot, please make sure that source code that you compile for OpenSearch project using
./gradlew localDistrois done from 1.x branch.
At present there are following branches available to choose from for the setup:
| OpenSearch branch |
Security Plugin branch |
OpenSearch version |
|---|---|---|
| 1.x | main | v1.3.0 |
| main | (under development) | v2.0.0 |
| OpenSearch Dashboards branch |
Security Dashboards Plugin branch |
OpenSearch Dashboards version |
|---|---|---|
| 1.x | main | v1.3.0 |
| main | (under development) | v2.0.0 |
For the sake of this guide, let's assume that the latest versions (1.3.0-SNAPSHOT for OpenSearch and OpenSearch Dashboards, and 1.3.0.0-SNAPSHOT for the backend and the frontend of this Security plugin).
Next, ensure that the config file (config/opensearch.yml) in the OpenSearch home directory where you copied the source code using the dev-guide (basically cd $OPENSEARCH_HOME) contains this:
######## Start OpenSearch Security Demo Configuration ########
#WARNING: revise all the lines below before you go into production
plugins.security.ssl.transport.pemcert_filepath: esnode.pem
plugins.security.ssl.transport.pemkey_filepath: esnode-key.pem
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
plugins.security.ssl.transport.enforce_hostname_verification: false
plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.pemcert_filepath: esnode.pem
plugins.security.ssl.http.pemkey_filepath: esnode-key.pem
plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem
plugins.security.allow_unsafe_democertificates: true
plugins.security.allow_default_init_securityindex: true
plugins.security.authcz.admin_dn:
- CN=kirk,OU=client,O=client,L=test, C=de
plugins.security.unsupported.restapi.allow_securityconfig_modification: true
plugins.security.audit.type: internal_opensearch
plugins.security.enable_snapshot_restore_privilege: true
plugins.security.check_snapshot_restore_write_privileges: true
plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"]
plugins.security.system_indices.enabled: true
plugins.security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opendistro-notifications-*", ".opendistro-notebooks", ".opensearch-observability", ".opendistro-asynchronous-search-response*", ".replication-metadata-store"]
node.max_local_storage_nodes: 3
######## End OpenSearch Security Demo Configuration ########Please Note : This project runs on node 10.24.1 at the time of writing this guide (refer to the .nvmrc or .node-version file in the base directory for correct version) and so when installing node please ensure that you install this version. You can do so by running
nvm use --install
Next, checkout the 1.x branch from OpenSearch-Dashboards repo. Follow the developer guide and replace the version of opensearch-dashboards.yml there with this:
server.host: "0"
opensearch.hosts: ["https://localhost:9200"]
opensearch.ssl.verificationMode: none
opensearch.username: "kibanaserver"
opensearch.password: "kibanaserver"
opensearch.requestHeadersWhitelist: [ authorization,securitytenant ]
opensearch_security.multitenancy.enabled: true
opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
opensearch_security.readonly_mode.roles: ["kibana_read_only"]
# Use this setting if you are running opensearch-dashboards without https
opensearch_security.cookie.secure: false
Note that at this point yarn start will fail, as we still don't have the security plugin installed in the Dashboards. We are ready to install it now.
Change to the plugins directory of the locally cloned Opensearch Dashboards directory.
cd <your-path-to>/OpenSearch-Dashboards
cd plugins
Create a fork of this repo and clone it locally under the plugins directory, and build the plugin:
cd plugins
git clone [email protected]:<your-git-username>/security-dashboards-plugin.git
cd security-dashboards-plugin
yarn build
Next, go to the base directory and run yarn osd bootstrap to install any additional packages introduced by the security plugin. (If you do not run this, yarn start might fail with an error like Cannot find module xxxxx)
Now, from the base directory and run yarn start. This should start dashboard UI successfully. Cmd+click the url in the console output (It should look something like http://0:5601/omf). Once the page loads, you should be able to log in with user admin and password admin.
To run selenium based integration tests, download and export the firefox web-driver to your PATH. Also, run node scripts/build_opensearch_dashboards_platform_plugins.js or yarn start before running the tests. This is essential to generate the bundles.
See CONTRIBUTING.
The Github workflow in backport.yml creates backport PRs automatically when the
original PR with an appropriate label backport <backport-branch-name> is merged to main with the backport workflow
run successfully on the PR. For example, if a PR on main needs to be backported to 1.x branch, add a label
backport 1.x to the PR and make sure the backport workflow runs on the PR along with other checks. Once this PR is
merged to main, the workflow will create a backport PR to the 1.x branch.