diff --git a/docs/reference/elasticsearch-plugins/authentication-plugins.md b/docs/reference/elasticsearch-plugins/authentication-plugins.md new file mode 100644 index 0000000000000..1c2bba73d14e6 --- /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..7baa1ab4a8c89 --- /dev/null +++ b/docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md @@ -0,0 +1,58 @@ +--- +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 that an Azure Admin will need to 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..803954bd9d776 --- /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..80e1cb2b94df9 --- /dev/null +++ b/docs/reference/elasticsearch-plugins/ms-graph-authz.md @@ -0,0 +1,37 @@ +--- +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] + +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}}.zip](https://artifacts.elastic.co/downloads/elasticsearch-plugins/microsoft-graph-authz/microsoft-graph-authz-{{version}}.zip). To verify the `.zip` file, use the [SHA hash](https://artifacts.elastic.co/downloads/elasticsearch-plugins/microsoft-graph-authz/microsoft-graph-authz-{{version}}.zip.sha512) or [ASC key](https://artifacts.elastic.co/downloads/elasticsearch-plugins/microsoft-graph-authz/microsoft-graph-authz-{{version}}.zip.asc). + + +## 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. + + diff --git a/docs/reference/elasticsearch-plugins/plugin-management.md b/docs/reference/elasticsearch-plugins/plugin-management.md index 939362c1f5dc7..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 ``` @@ -116,7 +116,7 @@ If Elasticsearch was installed using the deb or rpm package then run `/usr/share For detailed instructions on installing, managing, and configuring plugins, see the following: -* [Intalling Plugings](./installation.md) +* [Installing Plugins](./installation.md) * [Custom URL or file system](./plugin-management-custom-url.md) * [Installing multiple plugins](./installing-multiple-plugins.md) * [Mandatory plugins](./mandatory-plugins.md) 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