-
Notifications
You must be signed in to change notification settings - Fork 25.3k
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
base: main
Are you sure you want to change the base?
Changes from 2 commits
1a01d28
425099e
243e5a1
d7d6a90
40645be
a6abff1
3583699
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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 |
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 | ||||||||||||||||||||||||||||||||||||||||
richard-dennehy marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||||||||||||||
richard-dennehy marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||
:::{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. | ||||||||||||||||||||||||||||||||||||||||
richard-dennehy marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||
:::{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. | ||||||||||||||||||||||||||||||||||||||||
richard-dennehy marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||
:::{image} ./images/ms-graph-authz/03-get-application-id.png | ||||||||||||||||||||||||||||||||||||||||
:alt: get your application ID | ||||||||||||||||||||||||||||||||||||||||
::: | ||||||||||||||||||||||||||||||||||||||||
4) Under Manage > Certificates & secrets | ||||||||||||||||||||||||||||||||||||||||
richard-dennehy marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||||||||
- Create a new client secret | ||||||||||||||||||||||||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||||||||||||||||||||||||||||
- Take note of the Value - this is needed later, and is only shown once | ||||||||||||||||||||||||||||||||||||||||
richard-dennehy marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||||||||||||||||||||||||
:::{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 | ||||||||||||||||||||||||||||||||||||||||
::: | ||||||||||||||||||||||||||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
|
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: | ||||||
richard-dennehy marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
`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: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
```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>" | ||||||
``` |
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 | ||
richard-dennehy marked this conversation as resolved.
Show resolved
Hide resolved
|
||
--- | ||
|
||
# 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
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
|
||
|
Uh oh!
There was an error while loading. Please reload this page.