diff --git a/docs/plugins/authentication.asciidoc b/docs/plugins/authentication.asciidoc new file mode 100644 index 0000000000000..cf034b8a5cb35 --- /dev/null +++ b/docs/plugins/authentication.asciidoc @@ -0,0 +1,12 @@ +[[authentication]] +== Authentication plugins + +Authentication plugins extend the functionality provided by the built-in {ref}/realms.html[authentication realms]. + +[discrete] +=== Core authentication plugins + +<>:: +The Microsoft Graph Authz plugin uses https://learn.microsoft.com/en-us/graph/api/user-list-memberof/[Microsoft Graph] to look up group membership information from Microsoft Entra ID + +include::ms-graph-authz.asciidoc[] diff --git a/docs/plugins/images/01-create-enterprise-application.png b/docs/plugins/images/01-create-enterprise-application.png new file mode 100644 index 0000000000000..1f7c2feb20693 Binary files /dev/null and b/docs/plugins/images/01-create-enterprise-application.png differ diff --git a/docs/plugins/images/02-find-app-registration.png b/docs/plugins/images/02-find-app-registration.png new file mode 100644 index 0000000000000..fe526d18eb4b1 Binary files /dev/null and b/docs/plugins/images/02-find-app-registration.png differ diff --git a/docs/plugins/images/03-get-application-id.png b/docs/plugins/images/03-get-application-id.png new file mode 100644 index 0000000000000..6ebf1d35f70e2 Binary files /dev/null and b/docs/plugins/images/03-get-application-id.png differ diff --git a/docs/plugins/images/04-create-client-secret.png b/docs/plugins/images/04-create-client-secret.png new file mode 100644 index 0000000000000..db03e475eb2cd Binary files /dev/null and b/docs/plugins/images/04-create-client-secret.png differ diff --git a/docs/plugins/images/05-configure-api-permissions.png b/docs/plugins/images/05-configure-api-permissions.png new file mode 100644 index 0000000000000..e35da930aa9f3 Binary files /dev/null and b/docs/plugins/images/05-configure-api-permissions.png differ diff --git a/docs/plugins/index.asciidoc b/docs/plugins/index.asciidoc index e1b0b171bb1fa..9b8375a1fddf1 100644 --- a/docs/plugins/index.asciidoc +++ b/docs/plugins/index.asciidoc @@ -47,6 +47,8 @@ include::repository.asciidoc[] include::store.asciidoc[] +include::authentication.asciidoc[] + include::integrations.asciidoc[] include::authors.asciidoc[] diff --git a/docs/plugins/ms-graph-authz.asciidoc b/docs/plugins/ms-graph-authz.asciidoc new file mode 100644 index 0000000000000..5b6570733a81f --- /dev/null +++ b/docs/plugins/ms-graph-authz.asciidoc @@ -0,0 +1,155 @@ +[[ms-graph-authz]] +=== Microsoft Graph Authz + +The Microsoft Graph Authz plugin uses https://learn.microsoft.com/en-us/graph/api/user-list-memberof[Microsoft Graph] 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 https://learn.microsoft.com/en-us/security/zero-trust/develop/configure-tokens-group-claims-app-roles#group-overages[Group overages]). + +[discrete] +[id="microsoft-graph-authz-install"] +==== Installation + +ifeval::["{release-state}"=="unreleased"] + +WARNING: Version {version} of the Elastic Stack has not yet been released. + +endif::[] + +If you're using a self-managed Elasticsearch cluster, then this plugin can be installed using the plugin manager: + +["source","sh",subs="attributes,callouts"] +---------------------------------------------------------------- +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 <> from {plugin_url}/microsoft-graph-authz/microsoft-graph-authz-{version}.zip. To verify +the `.zip` file, use the +{plugin_url}/microsoft-graph-authz/microsoft-graph-authz-{version}.zip.sha512[SHA hash] or +{plugin_url}/microsoft-graph-authz/microsoft-graph-authz-{version}.zip.asc[ASC key]. + +For all other deployment types, refer to <>. + +[discrete] +[id="microsoft-graph-authz-remove"] +==== Removal + +The plugin can be removed with the following command: + +["source","sh",subs="attributes,callouts"] +---------------------------------------------------------------- +sudo bin/elasticsearch-plugin remove {plugin_name} +---------------------------------------------------------------- + +The node must be stopped before removing the plugin. + +[discrete] +==== Configuration +To learn how to configure the Microsoft Graph Authz plugin, refer to <>. + +[[configure-azure]] +==== Configure Azure + +To make API calls to Microsoft Graph, Elasticsearch requires Azure credentials with the correct permissions. + +[discrete] +==== Create a custom Azure application + +. Log in to the https://portal.azure.com[Azure portal] and go to Microsoft Entra ID. +. To register a new application, click *Enterprise applications* > *New application*. +. 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/01-create-enterprise-application.png["create your own application" page] + +[discrete] +==== Configure the custom Application + +. In the https://portal.azure.com[Azure portal], go to Microsoft Entra ID. +. Under *App registrations*, select the *All applications* tab, and then find the application created in the previous section. ++ +image::images/02-find-app-registration.png[find your app registration] +. Take note of the *Application (client) ID* and *Tenant ID* shown here. +These will be needed to configure Elasticsearch later. ++ +image::images/03-get-application-id.png[get your application ID] +. Under *Manage* > *Certificates & secrets* +- 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/04-create-client-secret.png[get your client secret] +. Under *Manage* > *API permissions*, do the following: +.. Go to *Add a permission*. +.. Choose *Microsoft Graph*. +.. Choose *Application permissions*. +.. 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/05-configure-api-permissions.png[configure api permissions] + +[[configure-elasticsearch]] +==== 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 https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant[Tenant ID]. +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: + +[source,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: "" +----