Announcement: The Slack workspace is live! Please join the conversation.

OpenSearch Security Plugin

OpenSearch Security is a plugin for OpenSearch that offers encryption, authentication and authorization. When combined with OpenSearch Security-Advanced Modules, it supports authentication via Active Directory, LDAP, Kerberos, JSON web tokens, SAML, OpenID and more. It includes fine grained role-based access control to indices, documents and fields. It also provides multi-tenancy support in OpenSearch Dashboards.

OpenSearch Security Plugin

Features

Encryption

Full data in transit encryption
Node-to-node encryption
Certificate revocation lists
Hot Certificate renewal

Authentication

Internal user database
HTTP basic authentication
PKI authentication
Proxy authentication
User Impersonation
Active Directory / LDAP
Kerberos / SPNEGO
JSON web token (JWT)
OpenID Connect (OIDC)
SAML

Access control

Role-based cluster level access control
Role-based index level access control
User-, role- and permission management
Document-level security
Field-level security
REST management API

Audit/Compliance logging

Audit logging
Compliance logging for GDPR, HIPAA, PCI, SOX and ISO compliance

OpenSearch Dashboards multi-tenancy

True OpenSearch Dashboards multi-tenancy

Installation

OpenSearch Security Plugin comes bundled by default as part of the OpenSearch distribution. Please refer to the installation guide and technical documentation for detailed information on installing and configuring the OpenSearch Security Plugin.

You can also see the developer guide which walks through the installation of the plugin for an OpenSearch server that doesn't initially have it.

Test and Build

Run all tests:

./gradlew clean test

Run tests against local cluster:

./gradlew integTestRemote -Dtests.rest.cluster=localhost:9200 -Dtests.cluster=localhost:9200 -Dtests.clustername=docker-cluster -Dsecurity=true -Dhttps=true -Duser=admin -Dpassword=admin -Dcommon_utils.version="2.2.0.0"

./scripts/integtest.sh

Note: To run against a remote cluster replace cluster-name and localhost:9200 with the IPAddress:Port of that cluster.

Build artifacts (zip, deb, rpm):

./gradlew clean assemble
artifact_zip=`ls $(pwd)/build/distributions/opensearch-security-*.zip | grep -v admin-standalone`
./gradlew buildDeb buildRpm -ParchivePath=$artifact_zip

This produces:

build/releases/opensearch-security-<VERSION>.zip
build/distributions/opensearch-security-<VERSION>.deb
build/distributions/opensearch-security-<VERSION>.rpm

Config hot reloading

The Security Plugin configuration is stored in a dedicated index in OpenSearch itself. Changes to the configuration are pushed to this index via the command line tool. This triggers a reload of the configuration on all nodes automatically. This has several advantages over configuration via opensearch.yml:

Configuration is stored in a central place
No configuration files on the nodes necessary
Configuration changes do not require a restart
Configuration changes take effect immediately

Onboarding new APIs

It is common practice to create new transport actions to perform different tasks between nodes when developing new APIs. For any new or existing plugins that want to onboard & integrate these actions with security, they should follow the steps below:

Name your action (example), and register it (example) in your plugin. Best practice is to follow existing naming conventions, which follow a hierarchical pattern to keep the action names organized between different plugins.
Register the action in the OpenSearch Security plugin. Each new action is registered in the plugin as a new permission. Usually, plugins will define different roles for their plugin (e.g., read-only access, write access). Each role will contain a set of permissions. An example of adding a new permission to the anomaly_read_access role for the Anomaly Detection plugin can be found in this PR.
Register the action in the OpenSearch Dashboards Security plugin. This plugin maintains the full list of possible permissions, so users can see all of them when creating new roles or searching permissions via Dashboards. An example of adding different permissions can be found in this PR.

sequenceDiagram
    participant Client
    participant OpenSearch
    participant SecurityPlugin
    participant Cluster as Plugin

    Client->>OpenSearch: Request
    OpenSearch->>SecurityPlugin: Request
    SecurityPlugin->>SecurityPlugin: Add Auth information to request context
    OpenSearch->>Cluster: Client Request
    Cluster->>SecurityPlugin: Execute transport layer action
    SecurityPlugin->>SecurityPlugin: Check if action is allowed
    alt Allowed
        SecurityPlugin->>OpenSearch: Continue request
        OpenSearch-->>Cluster: Transport layer action result
    else Denied
        SecurityPlugin-->>OpenSearch: Return 403 Forbidden
        OpenSearch-->>Client: 403 Forbidden
    end
    alt Plugin run outside user context
    Cluster->>Cluster: Stash context
    Cluster->>SecurityPlugin: Execute transport layer action outside user context
    SecurityPlugin-->>SecurityPlugin: Check if action is allowed
    SecurityPlugin->>OpenSearch: Continue request
    OpenSearch-->>Cluster: Transport layer action result
    Cluster->>Cluster: Restore user context
    end
    Cluster-->>SecurityPlugin: Result
    SecurityPlugin-->>OpenSearch: Result
    OpenSearch-->>Client: Result

System Index Protection

The Security Plugin provides protection to system indices used by plugins. The system index names must be explicitly registered in opensearch.yml under the plugins.security.system_indices.indices setting. See below for an example setup of system index protection from the demo configuration:

plugins.security.system_indices.enabled: true
plugins.security.system_indices.indices: [".plugins-ml-model", ".plugins-ml-task", ".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opensearch-notifications-*", ".opensearch-notebooks", ".opensearch-observability", ".opendistro-asynchronous-search-response*", ".replication-metadata-store"]

The demo configuration can be modified in the following files to add a new system index to the demo configuration:

Contributing

See developer guide and how to contribute to this project.

Getting Help

If you find a bug, or have a feature request, please don't hesitate to open an issue in this repository.

For more information, see project website and documentation. If you need help and are unsure where to open an issue, try forums.

Code of Conduct

This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ, or contact [email protected] with any additional questions or comments.

Security

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public GitHub issue.

License

This code is licensed under the Apache 2.0 License.

opensearch-project/security

opensearch-project

Reviews

Repository Details