OIDC clarifications and tip for Azure added (elastic#3498)

A user shared some interesting suggestions in
elastic/platform-docs-team#553 (internal
issue)

I've addressed two of them in this PR:
- Added extra details of the usefulness of `claims.name` and
`claims.mail`.
- Added a tip for companies with large group memberships in Azure.

Closes elastic/platform-docs-team#553
(internal issue)

---------

Co-authored-by: shainaraskas <[email protected]>

Author: 2 people

deploy-manage/users-roles/cluster-or-deployment-auth/oidc-examples.md

@@ -99,6 +99,15 @@ For more information about OpenID connect in Azure, refer to [Azure OAuth 2.0 an
     * `KIBANA_ENDPOINT_URL` is your {{kib}} endpoint.
     * `YOUR_DOMAIN` and `TLD` in the `claim_patterns.principal` regular expression are your organization email domain and top level domain.
 
+    :::{admonition} For organizations with many group memberships
+    If you configure [`claims.groups`](/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md#oidc-user-properties) to read the list of Azure AD groups from the ID token, be aware that users who belong to many groups may exceed Azure AD’s token size limit. In that case, the `groups` claim will be omitted.
+
+    To avoid this, enable the **Groups assigned to the application** option in Azure Entra (**App registrations > Token configuration > Edit groups claim**). This setting limits the `groups` claim to only those assigned to the application.
+
+    **Alternative:** If you can’t restrict groups to app-assigned ones, use the [Microsoft Graph Authz plugin for Elasticsearch](elasticsearch://reference/elasticsearch-plugins/ms-graph-authz.md). It looks up group memberships through Microsoft Graph during authorization, so it continues to work even when the `groups` claim is omitted due to overage.
+
+    Refer to [Group overages](https://learn.microsoft.com/en-us/security/zero-trust/develop/configure-tokens-group-claims-app-roles#group-overages) in the Microsoft Security documentation for more information.
+    :::
 
     If you're using {{ece}} or {{ech}}, and you're using machine learning or a deployment with hot-warm architecture, you must include this configuration in the user settings section for each node type.
 

deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md

@@ -254,10 +254,10 @@ groups
 :   *(Recommended)* If you want to use your OP’s concept of groups or roles as the basis for a user’s {{es}} privileges, you should map them with this property. The `groups` are passed directly to your [role mapping rules](/deploy-manage/users-roles/cluster-or-deployment-auth/openid-connect.md#oidc-role-mappings).
 
 name
-:   *(Optional)* The user’s full name.
+:   *(Optional)* The user’s full name. It will be used in {{kib}}'s profile page to display user details. Use the payload key of your ID token that fits best here.
 
 mail
-:   *(Optional)* The user’s email address.
+:   *(Optional)* The user’s email address. It will be used in {{kib}}'s profile page to display user details. Use the payload key of your ID token that fits best here.
 
 dn
 :   *(Optional)* The user’s X.500 Distinguished Name.

deploy-manage/users-roles/cluster-or-deployment-auth/saml-entra.md

@@ -89,9 +89,19 @@ Follow these steps to configure SAML with Microsoft Entra ID as an identity prov
         * `<Tenant_ID>` is your Tenant ID, available in the tenant overview page in Azure.
         * `<Kibana_Endpoint_URL>` is your {{kib}} endpoint, available from the {{ech}} console. Ensure this is the same value that you set for `Identifier (Entity ID)` in the earlier Microsoft Entra ID configuration step.
 
-            For `idp.metadata.path`, we’ve shown the format to construct the URL. This value should be identical to the `App Federation Metadata URL` setting that you made a note of in the previous step.
+        * For `idp.metadata.path`, we’ve shown the format to construct the URL. This value should be identical to the `App Federation Metadata URL` setting that you made a note of in the previous step.
 
-            If you're using {{ece}} or {{ech}}, and you're using machine learning or a deployment with hot-warm architecture, you must include this configuration in the user settings section for each node type.
+        :::{admonition} For organizations with many group memberships
+        If you configure [`attributes.groups`](/deploy-manage/users-roles/cluster-or-deployment-auth/saml.md#saml-es-user-properties) to read the list of Azure AD groups from the SAML assertion, be aware that users who belong to many groups may exceed Azure AD’s size limit for SAML tokens. In that case, the `groups` attribute will be omitted.
+
+        To avoid this, enable the **Groups assigned to the application** option in Azure Entra (**App registrations > Token configuration > Edit groups claim**). This setting limits the `groups` attribute in the SAML assertion to only those groups assigned to the application.
+
+        **Alternative:** If you can’t restrict groups to app-assigned ones, use the [Microsoft Graph Authz plugin for Elasticsearch](elasticsearch://reference/elasticsearch-plugins/ms-graph-authz.md). It looks up group memberships through Microsoft Graph during authorization, so it continues to work even when the `groups` attribute is omitted due to overage.
+
+        Refer to [Group overages](https://learn.microsoft.com/en-us/security/zero-trust/develop/configure-tokens-group-claims-app-roles#group-overages) in the Microsoft Security documentation for more information.
+        :::
+
+        If you're using {{ece}} or {{ech}}, and you're using machine learning or a deployment with hot-warm architecture, you must include this configuration in the user settings section for each node type.
 
     2. Next, configure {{kib}} to enable SAML authentication:
         1. [Update your {{kib}} user settings](/deploy-manage/deploy/elastic-cloud/edit-stack-settings.md) with the following configuration:

deploy-manage/users-roles/cluster-or-deployment-auth/saml.md

@@ -269,10 +269,10 @@ groups
     ::::
 
 name
-:   *(Optional)* The user’s full name.
+:   *(Optional)* The user’s full name. It will be used in {{kib}}'s profile page to display user details.
 
 mail
-:   *(Optional)* The user’s email address.
+:   *(Optional)* The user’s email address. It will be used in {{kib}}'s profile page to display user details.
 
 dn
 :   *(Optional)* The user’s X.500 *Distinguished Name*.