Skip to content

add documentation for MS Graph plugin #130703

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/reference/elasticsearch-plugins/authentication-plugins.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/plugins/current/authentication.html
---

# Authentication Plugins [authentication]

Authentication plugins extend the functionality provided by the built-in [authentication realms](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/authentication-realms)

## 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
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz-configure-azure.html
---

# 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) Click "Enterprise applications" and then "New application" to register a 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”, then the “All applications” tab, 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
- Create a new client secret
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Create a new client secret
- Create a new client secret.

- Take note of the Value - this is needed later, and is only shown once
:::{image} ./images/ms-graph-authz/04-create-client-secret.png
:alt: get your client secret
:::
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
:::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
:::

Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz-configure-elastic.html
---

# Configuration properties [configuration-properties]

Once 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, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:


```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>"
```
35 changes: 35 additions & 0 deletions docs/reference/elasticsearch-plugins/ms-graph-authz.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz.html
---

# 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
```
Comment on lines +16 to +20
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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).
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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



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


4 changes: 2 additions & 2 deletions docs/reference/elasticsearch-plugins/plugin-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand All @@ -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)
Expand Down
8 changes: 7 additions & 1 deletion docs/reference/elasticsearch-plugins/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -106,4 +106,10 @@ toc:
- file: store-smb.md
children:
- file: store-smb-usage.md
- file: integrations.md
- 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
Loading