add documentation for MS Graph plugin #130703

richard-dennehy · 2025-07-07T09:49:46Z

Add documentation for the plugin introduced in #128396

This will need a manual backport to 8.19

github-actions · 2025-07-07T09:49:54Z

🔍 Preview links for changed docs:

🔔 The preview site may take up to 3 minutes to finish building. These links will become live once it completes.

github-actions · 2025-07-07T09:58:24Z

🔍 Preview links for changed docs

elasticsearchmachine · 2025-07-08T08:33:03Z

Pinging @elastic/es-docs (Team:Docs)

elasticsearchmachine · 2025-07-08T08:33:03Z

Pinging @elastic/es-security (Team:Security)

richard-dennehy · 2025-07-08T09:50:08Z

docs/reference/elasticsearch-plugins/ms-graph-authz.md

+
+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).


it's difficult for me to verify this link as I don't think we've published any artifacts yet 🤔

shainaraskas

a few suggestions

shainaraskas · 2025-07-08T16:14:22Z

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

@@ -0,0 +1,13 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/plugins/current/authentication.html


if these plugins are only available as of 9.1, we should state that. this docs set is only applicable to a 9+ context which is why we wouldn't have 8.19 listed as well

Suggested change

- https://www.elastic.co/guide/en/elasticsearch/plugins/current/authentication.html

- https://www.elastic.co/guide/en/elasticsearch/plugins/current/authentication.html

applies_to:

stack: ga 9.1

shainaraskas · 2025-07-08T16:15:51Z

docs/reference/elasticsearch-plugins/ms-graph-authz.md

@@ -0,0 +1,35 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz.html


Suggested change

- https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz.html

- https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz.html

applies_to:

stack: ga 9.1

shainaraskas · 2025-07-08T16:16:52Z

docs/reference/elasticsearch-plugins/ms-graph-authz.md

+This plugin can be installed using the plugin manager:
+
+```sh
+sudo bin/elasticsearch-plugin install microsoft-graph-authz
+```


does this plugin work for all deployment types, or just self-managed vanilla elasticsearch?

I've been testing with Elastic Cloud, but it should work with any other deployment type

shainaraskas · 2025-07-08T16:17:45Z

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

+
+# 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)


Suggested change

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)

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).

shainaraskas · 2025-07-08T16:18:48Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

+
+## Create a custom Azure Application
+
+1) Log in to the [Azure portal](https://portal.azure.com) and go to Microsoft Entra ID


Suggested change

1) Log in to the [Azure portal](https://portal.azure.com) and go to Microsoft Entra ID

1) Log in to the [Azure portal](https://portal.azure.com) and go to Microsoft Entra ID.

shainaraskas · 2025-07-08T16:21:55Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

+    :::
+4) Under Manage > Certificates & secrets
+   - Create a new client secret
+   - Take note of the Value - this is needed later, and is only shown once


Suggested change

- Take note of the Value - this is needed later, and is only shown once

- Take note of you new client secret's **Value**. This is needed later, and is only displayed once.

shainaraskas · 2025-07-08T16:21:59Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

+    :alt: get your application ID
+    :::
+4) Under Manage > Certificates & secrets
+   - Create a new client secret


Suggested change

- Create a new client secret

- Create a new client secret.

shainaraskas · 2025-07-08T16:26:24Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

+5) Under Manage > API permissions
+   - Go to “Add a permission”
+   - Choose “Microsoft Graph”
+   - Choose “Application permissions”
+   - 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
+     :::


ordered procedures of more than two items need a numbered list

Suggested change

5) Under Manage > API permissions

- Go to “Add a permission”

- Choose “Microsoft Graph”

- Choose “Application permissions”

- 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

:::

5) Under **Manage** > **API permissions**, do the following:

1. Go to **Add a permission**.

2. Choose **Microsoft Graph**.

3. Choose **Application permissions**.

4. Select the following permissions: `Directory.ReadWrite.All`, `Group.ReadWrite.All`, and `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

:::

shainaraskas · 2025-07-08T16:27:32Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-elasticsearch.md

+
+# Configuration properties [configuration-properties]
+
+Once the plugin is installed, the following configuration settings are available:


Suggested change

Once the plugin is installed, the following configuration settings are available:

After the plugin is installed, the following configuration settings are available:

shainaraskas · 2025-07-08T16:28:24Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-elasticsearch.md

+
+Create a Microsoft Graph realm, following the above settings, then configure an existing realm to delegate to it using `authorization_realms`.
+
+For example, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:


Suggested change

For example, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:

For example, the following configuration authenticates using Microsoft Entra with SAML, and uses the Microsoft Graph plugin to look up group membership:

richard-dennehy added >docs General docs changes :Security/Authentication Logging in, Usernames/passwords, Realms (Native/LDAP/AD/SAML/PKI/etc) Team:Security Meta label for security team labels Jul 7, 2025

elasticsearchmachine added the v9.2.0 label Jul 7, 2025

github-actions bot deployed to docs-preview July 7, 2025 09:50 View deployment

richard-dennehy force-pushed the ms-graph-docs branch from 8836670 to e884907 Compare July 7, 2025 09:53

github-actions bot deployed to docs-preview July 7, 2025 09:54 View deployment

add documentation for MS Graph plugin

1a01d28

richard-dennehy force-pushed the ms-graph-docs branch from e884907 to 1a01d28 Compare July 7, 2025 09:57

github-actions bot deployed to docs-preview July 7, 2025 09:57 View deployment

github-actions bot deployed to docs-preview July 7, 2025 12:03 View deployment

richard-dennehy force-pushed the ms-graph-docs branch from 88a84df to 81cf4ca Compare July 7, 2025 12:06

github-actions bot deployed to docs-preview July 7, 2025 12:07 View deployment

richard-dennehy force-pushed the ms-graph-docs branch from 81cf4ca to a8599c7 Compare July 7, 2025 12:46

github-actions bot deployed to docs-preview July 7, 2025 12:47 View deployment

richard-dennehy force-pushed the ms-graph-docs branch from a8599c7 to c26b3c1 Compare July 7, 2025 13:59

github-actions bot deployed to docs-preview July 7, 2025 14:00 View deployment

add clarifying screenshots

425099e

richard-dennehy force-pushed the ms-graph-docs branch from c26b3c1 to 425099e Compare July 7, 2025 14:51

github-actions bot deployed to docs-preview July 7, 2025 14:52 View deployment

richard-dennehy added the v9.1.1 label Jul 8, 2025

richard-dennehy marked this pull request as ready for review July 8, 2025 08:32

elasticsearchmachine added the Team:Docs Meta label for docs team label Jul 8, 2025

richard-dennehy commented Jul 8, 2025

View reviewed changes

github-actions bot deployed to docs-preview July 8, 2025 10:12 View deployment

use docs-content link for internal docs reference

243e5a1

richard-dennehy force-pushed the ms-graph-docs branch from 88b47fd to 243e5a1 Compare July 8, 2025 10:15

github-actions bot deployed to docs-preview July 8, 2025 10:15 View deployment

richard-dennehy mentioned this pull request Jul 8, 2025

backport ms graph plugin docs to 8.19 #130823

Draft

shainaraskas reviewed Jul 8, 2025

View reviewed changes

address review comments

d7d6a90

github-actions bot deployed to docs-preview July 9, 2025 09:47 View deployment

Merge branch 'main' into ms-graph-docs

40645be

github-actions bot deployed to docs-preview July 9, 2025 09:49 View deployment

fix formatting issue

a6abff1

github-actions bot deployed to docs-preview July 9, 2025 10:06 View deployment


		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).


		# 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)


		## Create a custom Azure Application

		1) Log in to the [Azure portal](https://portal.azure.com) and go to Microsoft Entra ID

	- Take note of the Value - this is needed later, and is only shown once
	- Take note of you new client secret's Value. This is needed later, and is only displayed once.


		# Configuration properties [configuration-properties]

		Once the plugin is installed, the following configuration settings are available:

	Once the plugin is installed, the following configuration settings are available:
	After the plugin is installed, the following configuration settings are available:


		Create a Microsoft Graph realm, following the above settings, then configure an existing realm to delegate to it using `authorization_realms`.

		For example, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:

	For example, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:
	For example, the following configuration authenticates using Microsoft Entra with SAML, and uses the Microsoft Graph plugin to look up group membership:

add documentation for MS Graph plugin #130703

Are you sure you want to change the base?

add documentation for MS Graph plugin #130703

Conversation

richard-dennehy commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

elasticsearchmachine commented Jul 8, 2025

Uh oh!

elasticsearchmachine commented Jul 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

richard-dennehy commented Jul 7, 2025 •

edited

Loading

github-actions bot commented Jul 7, 2025 •

edited

Loading

github-actions bot commented Jul 7, 2025 •

edited

Loading