[Doc] Add architecture document (opensearch-project#2869)

* Add initial architecture document

Signed-off-by: Peter Nied <[email protected]>

ARCHITECTURE.md

@@ -0,0 +1,131 @@
+# OpenSearch Security Plugin Architecture
+
+OpenSearch’s 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.
+
+## Components
+
+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.
+
+```mermaid
+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
+```
+
+### Security Plugin
+
+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.
+
+### Security Configuration
+
+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.
+
+#### Configuration Files
+
+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.
+
+### 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.
+
+## Flows
+
+### Authentication / Authorization
+
+The Security Plugin supports multiple authentication backends including an internal identity provider which works with HTTP basic authentication as well as support [external providers](https://opensearch.org/docs/latest/security/authentication-backends/authc-index/) 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.
+
+```mermaid
+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
+```
+
+#### Multiple Authorization Provider flow
+
+Based on the order within the Security Plugin's configuration authentication providers are iterated through to discover which provider can authenticate the user.
+
+```mermaid
+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
+```
+
+#### Rest vs Transport flow
+
+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.
+
+```mermaid
+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
+```