Skip to content

Commit 1a01d28

Browse files
richard-dennehyrichard-dennehy
committed
add documentation for MS Graph plugin
1 parent 1126129 commit 1a01d28

File tree

5 files changed

+138
-1
lines changed

5 files changed

+138
-1
lines changed

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/plugins/current/authentication.html
4+
---
5+
6+
# Authentication Plugins [authentication]
7+
8+
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)
9+
10+
# Core authentication plugins
11+
12+
[Microsoft Graph Authz](/reference/elasticsearch-plugins/ms-graph-authz.md)
13+
: 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

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz-configure-azure.html
4+
---
5+
6+
# Configure Azure [configure-azure]
7+
8+
To make API calls to Microsoft Graph, Elasticsearch requires Azure credentials with the correct permissions.
9+
10+
## Create a custom Azure Application
11+
12+
1) Log in to the [Azure portal](https://portal.azure.com) and go to Microsoft Entra ID
13+
2) Click "Enterprise applications" and then "New application" to register a new application.
14+
3) Click "Create your own application", provide a name, and select the "Integrate any other application you don’t find in the gallery" option.
15+
16+
## Configure the custom Application
17+
18+
1) In the [Azure portal](https://portal.azure.com), go to Microsoft Entra ID.
19+
2) Under “App registrations”, then the “All applications” tab, find the application created in the previous section.
20+
3) Take note of the Application (client) ID and Tenant ID shown here - these will be needed to configure Elasticsearch later.
21+
4) Under Manage > Certificates & secrets
22+
- Create a new client secret
23+
- Take note of the Value - this is needed later, and is only shown once
24+
5) Under Manage > API permissions
25+
- Go to “Add a permission”
26+
- Choose “Microsoft Graph”
27+
- Choose “Application permissions”
28+
- Select “Directory.ReadWrite.All, Group.ReadWrite.All, User.Read.All”
29+
- Note that an Azure Admin will need to approve these permissions before the credentials can be used

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz-configure-elastic.html
4+
---
5+
6+
# Configuration properties [configuration-properties]
7+
8+
Once the plugin is installed, the following configuration settings are available:
9+
10+
`xpack.security.authc.realms.microsoft_graph.*.order`
11+
: 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.
12+
13+
`xpack.security.authc.realms.microsoft_graph.*.tenant_id`
14+
: Your Microsoft Entra ID [Tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant). This setting is required.
15+
16+
`xpack.security.authc.realms.microsoft_graph.*.client_id`
17+
: The Application ID of the Enterprise Application you registered in the previous section. This setting is required.
18+
19+
`xpack.security.authc.realms.microsoft_graph.*.client_secret`
20+
: 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.
21+
22+
`xpack.security.authc.realms.microsoft_graph.*.access_token_host`
23+
: A Microsoft login URL. This is optional, and defaults to `https://login.microsoftonline.com`.
24+
25+
`xpack.security.authc.realms.microsoft_graph.*.graph_host`
26+
: The Microsoft Graph base address. This is optional, and defaults to `https://graph.microsoft.com/v1.0`.
27+
28+
`xpack.security.authc.realms.microsoft_graph.*.http_request_timeout`
29+
: The timeout for individual Graph HTTP requests. This setting is optional, and defaults to `10s`.
30+
31+
`xpack.security.authc.realms.microsoft_graph.*.execution_timeout`
32+
: The overall timeout for authorization requests to this plugin. This setting is optional, and defaults to `30s`.
33+
34+
Create a Microsoft Graph realm, following the above settings, then configure an existing realm to delegate to it using `authorization_realms`.
35+
36+
For example, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:
37+
38+
```yaml
39+
xpack.security.authc.realms.saml.kibana-realm:
40+
order: 2
41+
attributes.principal: nameid
42+
attributes.groups: "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
43+
idp.metadata.path: "https://login.microsoftonline.com/<Tenant ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<Application_ID>"
44+
idp.entity_id: "https://sts.windows.net/<Tenant_ID>/"
45+
sp.entity_id: "<Kibana_Endpoint_URL>"
46+
sp.acs: "<Kibana_Endpoint_URL>/api/security/saml/callback"
47+
sp.logout: "<Kibana_Endpoint_URL>/logout"
48+
authorization_realms: microsoft_graph1
49+
50+
xpack.security.authc.realms.microsoft_graph.microsoft_graph1:
51+
order: 3
52+
tenant_id: "<Tenant_ID>"
53+
client_id: "<Graph_Application_ID>"
54+
```

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

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/elasticsearch/plugins/current/ms-graph-authz.html
4+
---
5+
6+
# Microsoft Graph Authz [ms-graph-authz]
7+
8+
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.
9+
10+
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)).
11+
12+
## Installation [ms-graph-authz-install]
13+
14+
This plugin can be installed using the plugin manager:
15+
16+
```sh
17+
sudo bin/elasticsearch-plugin install microsoft-graph-authz
18+
```
19+
20+
The plugin must be installed on every node in the cluster, and each node must be restarted after installation.
21+
22+
You can download this plugin for [offline install](/reference/elasticsearch-plugins/plugin-management-custom-url.md) from [https://artifacts.elastic.co/downloads/elasticsearch-plugins/ms-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).
23+
24+
25+
## Removal [ms-graph-authz-remove]
26+
27+
The plugin can be removed with the following command:
28+
29+
```sh
30+
sudo bin/elasticsearch-plugin remove microsoft-graph-authz
31+
```
32+
33+
The node must be stopped before removing the plugin.
34+
35+

‎docs/reference/elasticsearch-plugins/toc.yml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,4 +106,10 @@ toc:
106106
- file: store-smb.md
107107
children:
108108
- file: store-smb-usage.md
109-
- file: integrations.md
109+
- file: authentication-plugins.md
110+
children:
111+
- file: ms-graph-authz.md
112+
children:
113+
- file: ms-graph-authz-configure-azure.md
114+
- file: ms-graph-authz-configure-elasticsearch.md
115+
- file: integrations.md

0 commit comments

Comments
 (0)