add documentation for MS Graph plugin (#130703)

Author: richard-dennehy

docs/reference/elasticsearch-plugins/authentication-plugins.md

@@ -0,0 +1,15 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/plugins/current/authentication.html
+applies_to:
+  stack: ga 9.1
+---
+
+# Authentication plugins [authentication]
+
+Authentication plugins extend the functionality provided by the built-in [authentication realms](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/authentication-realms.md).
+
+## Core authentication plugins
+
+[Microsoft Graph Authz](/reference/elasticsearch-plugins/ms-graph-authz.md)
+:   The Microsoft Graph Authz plugin uses [Microsoft Graph](https://learn.microsoft.com/en-us/graph/api/user-list-memberof) to look up group membership information from Microsoft Entra ID

docs/reference/elasticsearch-plugins/images/ms-graph-authz/01-create-enterprise-application.png

@@ -0,0 +1,60 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz-configure-azure.html
+applies_to:
+  stack: ga 9.1
+---
+
+# Configure Azure [configure-azure]
+
+To make API calls to Microsoft Graph, Elasticsearch requires Azure credentials
+with the correct permissions.
+
+## Create a custom Azure application
+
+1) Log in to the [Azure portal](https://portal.azure.com) and go to Microsoft
+   Entra ID.
+2) To register a new application, click **Enterprise applications** > **New
+   application**.
+3) Click **Create your own application**, provide a name, and select the
+**Integrate any other application you don’t find in the gallery** option.
+
+:::{image} ./images/ms-graph-authz/01-create-enterprise-application.png
+:alt: "create your own application" page
+:::
+
+## Configure the custom application
+
+1) In the [Azure portal](https://portal.azure.com), go to Microsoft Entra ID.
+2) Under **App registrations**, select the **All applications** tab, and then
+   find the application created in the previous section.
+
+   :::{image} ./images/ms-graph-authz/02-find-app-registration.png
+   :alt: find your app registration
+   :::
+3) Take note of the **Application (client) ID** and **Tenant ID** shown here.
+   These will be needed to configure Elasticsearch later.
+
+   :::{image} ./images/ms-graph-authz/03-get-application-id.png
+   :alt: get your application ID
+   :::
+4) Under **Manage** > **Certificates & secrets**, do the following:
+    - Create a new client secret.
+    - Take note of your new client secret's **Value**. This is needed later, and
+      is only displayed once.
+      :::{image} ./images/ms-graph-authz/04-create-client-secret.png
+      :alt: get your client secret
+      :::
+5) Under **Manage** > **API permissions**, do the following:
+    1. Go to **Add a permission**.
+    2. Choose **Microsoft Graph**.
+    3. Choose **Application permissions**.
+    4. Select `Directory.ReadWrite.All`, `Group.ReadWrite.All`, `User.Read.All`.
+
+   :::{note}
+   An Azure Admin must approve these permissions before the credentials can be used.
+   :::
+
+   :::{image} ./images/ms-graph-authz/05-configure-api-permissions.png
+   :alt: configure api permissions
+   :::

docs/reference/elasticsearch-plugins/images/ms-graph-authz/02-find-app-registration.png

@@ -0,0 +1,68 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz-configure-elastic.html
+applies_to:
+  stack: ga 9.1
+---
+
+# Configuration properties [configuration-properties]
+
+After the plugin is installed, the following configuration settings are
+available:
+
+`xpack.security.authc.realms.microsoft_graph.*.order`
+:   The priority of the realm within the realm chain. Realms with a lower order
+are consulted first. The value must be unique for each realm. This setting is
+required.
+
+`xpack.security.authc.realms.microsoft_graph.*.tenant_id`
+:   Your Microsoft Entra
+ID [Tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant).
+This setting is required.
+
+`xpack.security.authc.realms.microsoft_graph.*.client_id`
+:   The Application ID of the Enterprise Application you registered in the
+previous section. This setting is required.
+
+`xpack.security.authc.realms.microsoft_graph.*.client_secret`
+:   The client secret value for the Application you registered in the previous
+section. This is a sensitive setting, and must be configured in the
+Elasticsearch keystore. This setting is required.
+
+`xpack.security.authc.realms.microsoft_graph.*.access_token_host`
+:   A Microsoft login URL. Defaults to `https://login.microsoftonline.com`.
+
+`xpack.security.authc.realms.microsoft_graph.*.graph_host`
+:   The Microsoft Graph base address. Defaults to
+`https://graph.microsoft.com/v1.0`.
+
+`xpack.security.authc.realms.microsoft_graph.*.http_request_timeout`
+:   The timeout for individual Graph HTTP requests. Defaults to `10s`.
+
+`xpack.security.authc.realms.microsoft_graph.*.execution_timeout`
+:   The overall timeout for authorization requests to this plugin. Defaults to
+`30s`.
+
+Create a Microsoft Graph realm, following the above settings, then configure an
+existing realm to delegate to it using `authorization_realms`.
+
+For example, the following configuration authenticates via Microsoft Entra with
+SAML, and uses the Microsoft Graph plugin to look up group membership:
+
+```yaml
+xpack.security.authc.realms.saml.kibana-realm:
+  order: 2
+  attributes.principal: nameid
+  attributes.groups: "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
+  idp.metadata.path: "https://login.microsoftonline.com/<Tenant_ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<Application_ID>"
+  idp.entity_id: "https://sts.windows.net/<Tenant_ID>/"
+  sp.entity_id: "<Kibana_Endpoint_URL>"
+  sp.acs: "<Kibana_Endpoint_URL>/api/security/saml/callback"
+  sp.logout: "<Kibana_Endpoint_URL>/logout"
+  authorization_realms: microsoft_graph1
+
+xpack.security.authc.realms.microsoft_graph.microsoft_graph1:
+  order: 3
+  tenant_id: "<Tenant_ID>"
+  client_id: "<Graph_Application_ID>"
+```

docs/reference/elasticsearch-plugins/images/ms-graph-authz/03-get-application-id.png

@@ -0,0 +1,48 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz.html
+applies_to:
+  stack: ga 9.1
+---
+
+# Microsoft Graph Authz [ms-graph-authz]
+
+The Microsoft Graph Authz plugin uses [Microsoft Graph](https://learn.microsoft.com/en-us/graph/api/user-list-memberof)
+to look up group membership information from Microsoft Entra ID.
+
+This is primarily intended to work around the Microsoft Entra ID maximum group
+size limit (see [Group overages](https://learn.microsoft.com/en-us/security/zero-trust/develop/configure-tokens-group-claims-app-roles#group-overages)).
+
+## Installation [ms-graph-authz-install]
+
+If you're using a [self-managed Elasticsearch cluster](docs-content:///deploy-manage/deploy/self-managed.md), then this plugin can be installed using the plugin manager:
+
+```sh
+sudo bin/elasticsearch-plugin install microsoft-graph-authz
+```
+
+The plugin must be installed on every node in the cluster, and each node must be
+restarted after installation.
+
+You can download this plugin
+for [offline install](/reference/elasticsearch-plugins/plugin-management-custom-url.md)
+from [https://artifacts.elastic.co/downloads/elasticsearch-plugins/microsoft-graph-authz/microsoft-graph-authz-{{version.stack}}.zip](https://artifacts.elastic.co/downloads/elasticsearch-plugins/microsoft-graph-authz/microsoft-graph-authz-{{version.stack}}.zip).
+To verify the `.zip` file, use
+the [SHA hash](https://artifacts.elastic.co/downloads/elasticsearch-plugins/microsoft-graph-authz/microsoft-graph-authz-{{version.stack}}.zip.sha512)
+or [ASC key](https://artifacts.elastic.co/downloads/elasticsearch-plugins/microsoft-graph-authz/microsoft-graph-authz-{{version.stack}}.zip.asc).
+
+For all other deployment types, refer to [plugin management](/reference/elasticsearch-plugins/plugin-management.md).
+
+## Removal [ms-graph-authz-remove]
+
+The plugin can be removed with the following command:
+
+```sh
+sudo bin/elasticsearch-plugin remove microsoft-graph-authz
+```
+
+The node must be stopped before removing the plugin.
+
+## Configuration
+
+To learn how to configure the Microsoft Graph Authz plugin, refer to [configuration properties](/reference/elasticsearch-plugins/ms-graph-authz-configure-elasticsearch.md).

docs/reference/elasticsearch-plugins/images/ms-graph-authz/04-create-client-secret.png

@@ -106,7 +106,7 @@ Use the `elasticsearch-plugin` command line tool to install, list, and remove pl
 
 Run the following command to get usage instructions:
 
-``` 
+```
 sudo bin/elasticsearch-plugin -h
 ```