diff --git a/docs/reference/elasticsearch-plugins/authentication-plugins.md b/docs/reference/elasticsearch-plugins/authentication-plugins.md new file mode 100644 index 0000000000000..c706070eb1e89 --- /dev/null +++ b/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 diff --git a/docs/reference/elasticsearch-plugins/images/ms-graph-authz/01-create-enterprise-application.png b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/01-create-enterprise-application.png new file mode 100644 index 0000000000000..1f7c2feb20693 Binary files /dev/null and b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/01-create-enterprise-application.png differ diff --git a/docs/reference/elasticsearch-plugins/images/ms-graph-authz/02-find-app-registration.png b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/02-find-app-registration.png new file mode 100644 index 0000000000000..fe526d18eb4b1 Binary files /dev/null and b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/02-find-app-registration.png differ diff --git a/docs/reference/elasticsearch-plugins/images/ms-graph-authz/03-get-application-id.png b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/03-get-application-id.png new file mode 100644 index 0000000000000..6ebf1d35f70e2 Binary files /dev/null and b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/03-get-application-id.png differ diff --git a/docs/reference/elasticsearch-plugins/images/ms-graph-authz/04-create-client-secret.png b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/04-create-client-secret.png new file mode 100644 index 0000000000000..db03e475eb2cd Binary files /dev/null and b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/04-create-client-secret.png differ diff --git a/docs/reference/elasticsearch-plugins/images/ms-graph-authz/05-configure-api-permissions.png b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/05-configure-api-permissions.png new file mode 100644 index 0000000000000..e35da930aa9f3 Binary files /dev/null and b/docs/reference/elasticsearch-plugins/images/ms-graph-authz/05-configure-api-permissions.png differ diff --git a/docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md b/docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md new file mode 100644 index 0000000000000..6a8fe44e94099 --- /dev/null +++ b/docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md @@ -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 + ::: diff --git a/docs/reference/elasticsearch-plugins/ms-graph-authz-configure-elasticsearch.md b/docs/reference/elasticsearch-plugins/ms-graph-authz-configure-elasticsearch.md new file mode 100644 index 0000000000000..77c0951b56761 --- /dev/null +++ b/docs/reference/elasticsearch-plugins/ms-graph-authz-configure-elasticsearch.md @@ -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//federationmetadata/2007-06/federationmetadata.xml?appid=" + idp.entity_id: "https://sts.windows.net//" + sp.entity_id: "" + sp.acs: "/api/security/saml/callback" + sp.logout: "/logout" + authorization_realms: microsoft_graph1 + +xpack.security.authc.realms.microsoft_graph.microsoft_graph1: + order: 3 + tenant_id: "" + client_id: "" +``` diff --git a/docs/reference/elasticsearch-plugins/ms-graph-authz.md b/docs/reference/elasticsearch-plugins/ms-graph-authz.md new file mode 100644 index 0000000000000..aee355321213a --- /dev/null +++ b/docs/reference/elasticsearch-plugins/ms-graph-authz.md @@ -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). diff --git a/docs/reference/elasticsearch-plugins/plugin-management.md b/docs/reference/elasticsearch-plugins/plugin-management.md index fb43f09020951..02ec8a9285b40 100644 --- a/docs/reference/elasticsearch-plugins/plugin-management.md +++ b/docs/reference/elasticsearch-plugins/plugin-management.md @@ -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 ``` diff --git a/docs/reference/elasticsearch-plugins/toc.yml b/docs/reference/elasticsearch-plugins/toc.yml index b75ca32a36876..01e0ce38dd49e 100644 --- a/docs/reference/elasticsearch-plugins/toc.yml +++ b/docs/reference/elasticsearch-plugins/toc.yml @@ -106,4 +106,10 @@ toc: - file: store-smb.md children: - file: store-smb-usage.md - - file: integrations.md \ No newline at end of file + - file: authentication-plugins.md + children: + - file: ms-graph-authz.md + children: + - file: ms-graph-authz-configure-azure.md + - file: ms-graph-authz-configure-elasticsearch.md + - file: integrations.md