OpenSearch鈥檚 core systems do not include security features, these features are added by installing the Security Plugin. The Security Plugin extends OpenSearch to provide authentication, authorization, end to end Encryption, audit logging, and management interfaces.
The Security Plugin is packaged into a standard plugin zip file used by OpenSearch which can be installed by using the plugin tool. The security configuration is accessible on disk for modification before the node has been turned on. After node startup, the admin tools or API endpoints can be used for dynamic changes.
graph TD
subgraph OpenSearch Node
subgraph File System
cfg[Security Configuration files]
adm[Admin Tools]
end
subgraph Indices
idx(Index 1..n)
secIdx[Security Index]
end
subgraph Plugins
pgns(Plugins 1..n)
sec[Security Plugin]
end
sec -- bootstrap security config --> cfg
sec -- refresh security config from cluster --> secIdx
adm -- backup/restore security config --> sec
end
The runtime of the Security Plugin uses extension points to insert itself into the path actions. Several security management actions are registered in OpenSearch so they can be changed through REST API actions.
The security configuration is stored in an system index that is replicated to all nodes. When a change has been made to the configuration, the Security Plugin is reloaded to cleanly initialize its components with the new settings.
When starting up with no security index detected in the cluster, the Security Plugin will attempt to load configuration files from disk into a new security index. The configuration files can be manually modified or sourced from a backup of a security index created using the admin tools.
For OpenSearch nodes to join a cluster, they need to have the same security configuration. Complete security configurations will include SSL settings and certificate files. The admin tools allow users to manage these settings and other features.
The Security Plugin supports multiple authentication backends including an internal identity provider which works with HTTP basic authentication as well as support external providers such as OpenId Connect (OIDC) and SAML.
Authorization is governed by roles declared in the security configuration. Roles control resource access by referencing the transport action name and/or index names in combination with OpenSearch action names.
Users are assigned roles via the role mappings. These mappings include backend role assignments from authentication providers as well as internal roles defined in the Security Plugin.
sequenceDiagram
title Basic Authorization flow
autonumber
participant C as Client
participant O as OpenSearch
participant SP as Security Plugin
participant RH as Request Handler
participant AL as Audit Log
C->>O: Request
O->>SP: Request Received
activate SP
SP->>SP: Authenticate user via internal/external auth providers
SP->>SP: Resolve Authorization for user
SP-->>O: Allow/Deny request
SP->>AL: Update Audit Log asynchronously
deactivate SP
O->>RH: Request continues to request handler
RH-->>O: Result
O->>C: Response
Based on the order within the Security Plugin's configuration authentication providers are iterated through to discover which provider can authenticate the user.
sequenceDiagram
title Multiple Authorization Provider flow
autonumber
participant C as Client
participant SP as Security Plugin
participant IAP as Internal Auth Provider
participant EAP as External Auth Provider*
participant SC as Security Configuration
C->>SP: Incoming request
SP->>IAP: Attempt to authenticate internally
IAP-->>SP: Internal user result
loop for each External Auth Provider
SP->>EAP: Attempt to authenticate
EAP-->>SP: External user result
end
SP->>SC: Check Authorization rules
SC->>SC: Match user roles & permissions
SC-->>SP: Authorization result
SP-->>C: Response
OpenSearch treats external REST requests differently than internal transport requests. While REST requests allow for client-to-node communication and make use of API routes, transport requests are more structured and are used to communicate between nodes.
sequenceDiagram
title Rest vs Transport Flow
autonumber
participant C as Client
participant O as OpenSearch
participant SP as Security Plugin (Rest Filter & Security Interceptor)
participant AH as Action Handler
C->>O: Request
O->>SP: REST Request Received
SP->>SP: If using client cert, Authenticate
SP-->>O: Continue request
O->>SP: Transport Request Received
SP->>SP: Authenticate user via internal/external auth providers
SP->>SP: Resolve Authorization for user
SP-->>O: Allow/Deny request
O->>AH: Send transport request to action handler
AH-->>O: Result
O->>C: Response
Plugins that implement ActionPlugin can register REST and Transport layer handlers which can receive requests from the user and other nodes in the cluster, respectively. During the lifecycle of an incoming requests there are two standard ways to handle authorized actions in these flows. One us to use the authenticated user, the other is to run outside the user context.
As in the normal authorization flow into the service the user is authenticated, then the action is determined, and finally an authorization check for the user is performed, and they are allowed or denied. This can be thought of as running on behalf of the user.
There are some actions run by plugins that do not reuse the authentication or authorization of the current user, such as to make changes to internal cluster state for cross cluster replication. When requests come in for these actions they are run outside the user context.
Operating outside the user context means that no authorization checks are performed. This is used to elevate plugin activities such as modifications to system indices, operations on the cluster configuration, and to ensure actions on the cluster are not associated with a singular user.
sequenceDiagram
title Authorization during action flow for Plugins
autonumber
participant C as Client
participant OS as OpenSearch
participant SP as SecurityPlugin
participant P as Plugin
C->>OS: Request
OS->>SP: Request
SP->>SP: Add Auth information to request context
OS->>P: Client Request
P->>SP: Execute transport layer action
SP->>SP: Check if action is allowed
alt Allowed
SP->>OS: Continue request
OS-->>P: Transport layer action result
else Denied
SP-->>OS: Return 403 Forbidden
OS-->>C: 403 Forbidden
end
alt Plugin run outside user context
P->>P: Stash context
P->>SP: Execute transport layer action outside user context
SP-->>SP: Check if action is allowed
SP->>OS: Continue request
OS-->>P: Transport layer action result
P->>P: Restore user context
end
P-->>SP: Result
SP-->>OS: Result
OS-->>C: Result
Extensions will be able to operate in similar flows as Plugins to ensure authorization is correctly handled. Registration of REST handlers is allowed and transport layer actions are not permitted. After the request has been authorized for the user to be transmitted to the extension the token generator will create a just in time token for use with that request on behalf of the user.
On Behalf Of tokens are an optional feature, while supported through the extensions API it needs to be enabled on an individual extension basis. Issuing On Behalf Of tokens can be disabled which will alter request forward to the extension not to include the On Behalf Of token.
sequenceDiagram
title Authorization during action flow for Extension
autonumber
participant C as Client
participant OS as OpenSearch
participant SP as SecurityPlugin
participant E as Extension
C->>OS: Request
OS->>SP: Request
SP->>SP: Add Auth information from request context
alt Allowed
SP->>OS: Continue request
OS-->>SP: Generate OnBehalfOf token for extension
SP->>OS: Return OnBehalfOf token
OS-->>E: Forward client Request with OnBehalfOf token
else Denied
note over E: Extension does not know<br>about denied requests
SP-->>OS: Access denied
OS-->>C: 403 Forbidden
end
E->>OS: Call OpenSearch REST API<br>with OnBehalfOf token
OS->>SP: Request
SP->>SP: Add Auth information from OnBehalfOf token
alt Allowed
SP->>OS: Continue request
OS-->>E: Return REST API Action
E->>OS: Return extension response
OS->>C: Result
else Denied
SP-->>OS: Access denied
OS-->>E: 403 Forbidden
note over E: Extension responsible to understand<br>communicate failure response(s)
E->>OS: Return extension response
OS->>C: Result
end
Service account information is provided to the extension on initialization. This allows extension to make requests against the OpenSearch Cluster without needing an incoming request. Since this request is down in the context of a different identity it can have different permissions from that of an On Behalf Of user such as modification to a persistent data store used by the extension.
sequenceDiagram
title Authorization with Service Account
autonumber
participant C as Client
participant E as Extension
participant OS as OpenSearch
participant SP as SecurityPlugin
OS->>OS: Initialize Extensions
OS->>SP: Register extension service account
SP->>OS: Service account token
OS->>E: Initialization extension<br>include Service account token
Note over E: Extension is initalized
C->>E: Request
E->>OS: Check extension data store<br>include Service account token
OS->>SP: Request
SP->>SP: Add Auth information from request context
alt Allowed
SP->>OS: Continue request
OS->>E: REST API Result
else Denied
SP->>OS: Access denied
OS->>E: 403 Forbidden
end
E->>C: Return extension response