[8.19](backport #44761) x-pack/filebeat/input/entityanalytic/provider/azuread/fetcher/graph: add support for expand (#45016)

* x-pack/filebeat/input/entityanalytic/provider/azuread/fetcher/graph: add support for expand (#44761)

(cherry picked from commit 3ca2970)

# Conflicts:
#	docs/reference/filebeat/filebeat-input-entity-analytics.md

* remove incorrectly back-ported markdown
* add asciidoc

---------

Co-authored-by: Dan Kortschak <dan.kortschak@elastic.co>

Author: mergify[bot]

CHANGELOG.next.asciidoc

@@ -416,6 +416,7 @@ otherwise no tag is added. {issue}42208[42208] {pull}42403[42403]
 - Filestream now logs at level warn the number of files that are too small to be ingested {pull}44751[44751]
 - Add Fleet status updating to HTTP JSON input. {issue}44282[44282] {pull}44365[44365]
 - Add proxy support to GCP Pub/Sub input. {pull}44892[44892]
+- Add support for relationship expansion to EntraID entity analytics provider. {issue}43324[43324] {pull}44761[44761]
 
 *Auditbeat*
 

x-pack/filebeat/docs/inputs/input-entity-analytics.asciidoc

@@ -455,6 +455,13 @@ Example configuration:
   client_id: "CLIENT_ID"
   tenant_id: "TENANT_ID"
   secret: "SECRET"
+  expand:
+    users:
+      manager:
+        - displayName
+        - id
+      directReports:
+        - id
 ----
 
 The `azure-ad` provider supports the following configuration:
@@ -529,6 +536,27 @@ This is a list of optional query parameters. The default is `["accountEnabled",
 "displayName", "operatingSystem", "operatingSystemVersion", "physicalIds", "extensionAttributes",
 "alternativeSecurityIds"]`.
 
+[float]
+===== `expand.users`
+
+Add https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#relationships[user query relationship expansions].
+This is a map of relationship names to attribute lists. By default this is not set. If an empty
+relationship list is given, the relationship expansion is the same as the users query.
+
+[float]
+===== `expand.groups`
+
+Add https://learn.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0#relationships[group query relationship expansions].
+This is a map of relationship names to attribute lists. By default this is not set. If an empty
+relationship list is given, the relationship expansion is the same as the groups query.
+
+[float]
+===== `expand.devices`
+
+Add https://learn.microsoft.com/en-us/graph/api/resources/device?view=graph-rest-1.0#relationships[device query relationship expansions].
+This is a map of relationship names to attribute lists. By default this is not set. If an empty
+relationship list is given, the relationship expansion is the same as the devices query.
+
 [float]
 ==== `tracer.enabled`
 

x-pack/filebeat/input/entityanalytics/provider/azuread/fetcher/graph/graph.go

@@ -18,6 +18,7 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 
 	"github.com/gofrs/uuid/v5"
@@ -43,6 +44,7 @@ const (
 	defaultGroupsQuery  = "displayName,members"
 	defaultUsersQuery   = "accountEnabled,userPrincipalName,mail,displayName,givenName,surname,jobTitle,officeLocation,mobilePhone,businessPhones"
 	defaultDevicesQuery = "accountEnabled,deviceId,displayName,operatingSystem,operatingSystemVersion,physicalIds,extensionAttributes,alternativeSecurityIds"
+	expandName          = "$expand"
 
 	apiGroupType  = "#microsoft.graph.group"
 	apiUserType   = "#microsoft.graph.user"
@@ -110,6 +112,7 @@ type removed struct {
 type graphConf struct {
 	APIEndpoint string    `config:"api_endpoint"`
 	Select      selection `config:"select"`
+	Expand      expansion `config:"expand"`
 
 	Transport httpcommon.HTTPTransportSettings `config:",inline"`
 
@@ -132,6 +135,12 @@ type selection struct {
 	DeviceQuery []string `config:"devices"`
 }
 
+type expansion struct {
+	UserExpansion   map[string][]string `config:"users"`
+	GroupExpansion  map[string][]string `config:"groups"`
+	DeviceExpansion map[string][]string `config:"devices"`
+}
+
 // graph implements the fetcher.Fetcher interface.
 type graph struct {
 	conf   graphConf
@@ -380,21 +389,30 @@ func New(ctx context.Context, id string, cfg *config.C, logger *logp.Logger, aut
 	if err != nil {
 		return nil, fmt.Errorf("invalid groups URL endpoint: %w", err)
 	}
-	groupsURL.RawQuery = formatQuery(queryName, c.Select.GroupQuery, defaultGroupsQuery)
+	groupsURL.RawQuery, err = formatQuery(queryName, c.Select.GroupQuery, defaultGroupsQuery, c.Expand.GroupExpansion)
+	if err != nil {
+		return nil, fmt.Errorf("failed to format group query: %w", err)
+	}
 	f.groupsURL = groupsURL.String()
 
 	usersURL, err := url.Parse(f.conf.APIEndpoint + "/users/delta")
 	if err != nil {
 		return nil, fmt.Errorf("invalid users URL endpoint: %w", err)
 	}
-	usersURL.RawQuery = formatQuery(queryName, c.Select.UserQuery, defaultUsersQuery)
+	usersURL.RawQuery, err = formatQuery(queryName, c.Select.UserQuery, defaultUsersQuery, c.Expand.UserExpansion)
+	if err != nil {
+		return nil, fmt.Errorf("failed to format user query: %w", err)
+	}
 	f.usersURL = usersURL.String()
 
 	devicesURL, err := url.Parse(f.conf.APIEndpoint + "/devices/delta")
 	if err != nil {
 		return nil, fmt.Errorf("invalid devices URL endpoint: %w", err)
 	}
-	devicesURL.RawQuery = formatQuery(queryName, c.Select.DeviceQuery, defaultDevicesQuery)
+	devicesURL.RawQuery, err = formatQuery(queryName, c.Select.DeviceQuery, defaultDevicesQuery, c.Expand.DeviceExpansion)
+	if err != nil {
+		return nil, fmt.Errorf("failed to format device query: %w", err)
+	}
 	f.devicesURL = devicesURL.String()
 
 	// The API takes a departure from the query approach here, so we
@@ -470,12 +488,28 @@ func sanitizeFileName(name string) string {
 	return strings.ReplaceAll(name, string(filepath.Separator), "_")
 }
 
-func formatQuery(name string, query []string, dflt string) string {
+func formatQuery(name string, query []string, dflt string, expand map[string][]string) (string, error) {
 	q := dflt
 	if len(query) != 0 {
 		q = strings.Join(query, ",")
 	}
-	return url.Values{name: []string{q}}.Encode()
+	vals := url.Values{name: []string{q}}
+	if len(expand) != 0 {
+		exp := make([]string, 0, len(expand))
+		for k := range expand {
+			exp = append(exp, k)
+		}
+		sort.Strings(exp)
+		for i, k := range exp {
+			v, err := formatQuery(name, expand[k], q, nil)
+			if err != nil {
+				return "", err
+			}
+			exp[i] = fmt.Sprintf("%s(%s)", k, v)
+		}
+		vals.Add(expandName, strings.Join(exp, ","))
+	}
+	return url.QueryUnescape(vals.Encode())
 }
 
 // newUserFromAPI translates an API-representation of a user to a fetcher.User.

x-pack/filebeat/input/entityanalytics/provider/azuread/fetcher/graph/graph_test.go

@@ -521,3 +521,82 @@ func TestGraph_Devices(t *testing.T) {
 		})
 	}
 }
+
+var formatQueryTests = []struct {
+	name   string
+	query  []string
+	deflt  string
+	expand map[string][]string
+	want   string
+}{
+	{
+		name:   "default",
+		query:  nil,
+		deflt:  defaultUsersQuery,
+		expand: nil,
+		want:   "$select=accountEnabled,userPrincipalName,mail,displayName,givenName,surname,jobTitle,officeLocation,mobilePhone,businessPhones",
+	},
+	{
+		name:   "defined_query_no_expand",
+		query:  []string{"id", "displayName"},
+		deflt:  defaultUsersQuery,
+		expand: nil,
+		want:   "$select=id,displayName",
+	},
+	{
+		name:   "defined_query_empty_expand",
+		query:  []string{"id", "displayName"},
+		deflt:  defaultUsersQuery,
+		expand: map[string][]string{},
+		want:   "$select=id,displayName",
+	},
+	{
+		name:   "default_manager_default",
+		query:  nil,
+		deflt:  defaultUsersQuery,
+		expand: map[string][]string{"manager": {}},
+		want:   "$expand=manager($select=accountEnabled,userPrincipalName,mail,displayName,givenName,surname,jobTitle,officeLocation,mobilePhone,businessPhones)&$select=accountEnabled,userPrincipalName,mail,displayName,givenName,surname,jobTitle,officeLocation,mobilePhone,businessPhones",
+	},
+	{
+		name:   "default_manager_id",
+		query:  nil,
+		deflt:  defaultUsersQuery,
+		expand: map[string][]string{"manager": {"id"}},
+		want:   "$expand=manager($select=id)&$select=accountEnabled,userPrincipalName,mail,displayName,givenName,surname,jobTitle,officeLocation,mobilePhone,businessPhones",
+	},
+	{
+		name:   "defined_manager_id",
+		query:  []string{"id", "displayName"},
+		deflt:  defaultUsersQuery,
+		expand: map[string][]string{"manager": {"id"}},
+		want:   "$expand=manager($select=id)&$select=id,displayName",
+	},
+	{
+		name:   "defined_manager_default",
+		query:  []string{"id", "displayName"},
+		deflt:  defaultUsersQuery,
+		expand: map[string][]string{"manager": {}},
+		want:   "$expand=manager($select=id,displayName)&$select=id,displayName",
+	},
+	{
+		name:   "expand_two",
+		query:  []string{"id", "displayName"},
+		deflt:  defaultUsersQuery,
+		expand: map[string][]string{"manager": {}, "directReports": {}},
+		want:   "$expand=directReports($select=id,displayName),manager($select=id,displayName)&$select=id,displayName",
+	},
+}
+
+func TestFormatQuery(t *testing.T) {
+	for _, test := range formatQueryTests {
+		t.Run(test.name, func(t *testing.T) {
+			got, err := formatQuery(queryName, test.query, test.deflt, test.expand)
+			if err != nil {
+				t.Fatalf("unexpected error from formatQuery: %v", err)
+			}
+			if got != test.want {
+				t.Errorf("unexpected query string: got=%q want=%q", got, test.want)
+			}
+		})
+	}
+}