Add 'additionalFields' Field to extract additional data from MSGraph

Signed-off-by: Yevhen Artemenko <eartemenko@playtika.com>

Author: Yevhen Artemenko

README.md

@@ -197,6 +197,46 @@ confirmed, `activeAccount: true` excludes the user.
 > (rather than `x-kubernetes-preserve-unknown-fields`) need to add
 > `accountEnabled` to that schema, otherwise the API server silently prunes it.
 
+### Additional Fields
+
+Use `additionalFields` to include extra Microsoft Graph attributes beyond the default set. Supported for all query types.
+
+| queryType | Default fields | Valid additional fields (examples) |
+|---|---|---|
+| `UserValidation` | `id`, `displayName`, `userPrincipalName`, `mail` | `city`, `country`, `department`, `jobTitle`, `officeLocation`, `employeeType`, `usageLocation` |
+| `GroupObjectIDs` | `id`, `displayName`, `description` | `mailNickname`,  `securityEnabled` |
+| `ServicePrincipalDetails` | `id`, `appId`, `displayName`, `description` | `servicePrincipalType`, `homepage` |
+| `GroupMembership` | `id`, `displayName`, `type`, `mail`, `userPrincipalName`, `appId` | `department`, `jobTitle` (user members only) |
+
+> **Note:** Field names must match the Microsoft Graph API property name exactly (camelCase). Unknown field names are skipped with an `Info` log entry in the function pod. Fields that exist in Graph API but have no value for a given object are silently skipped (visible at `Debug` log level).
+
+```yaml
+apiVersion: msgraph.fn.crossplane.io/v1alpha1
+kind: Input
+queryType: UserValidation
+usersRef: "spec.owners"
+target: "status.validatedUsers"
+additionalFields:
+  - city
+  - department
+  - jobTitle
+```
+
+Result:
+
+```yaml
+status:
+  validatedUsers:
+    - id: 1bbbbbbb-...
+      displayName: Some Name
+      userPrincipalName: someName@example.com
+      mail: someName@example.com
+      city: Kyiv
+      department: Ops
+      jobTitle: Staff Engineer
+```
+>>>>>>> 75824b3 (Add 'additionalFields' Field to extract additional data from MSGraph)
+
 ### Get Group Membership
 
 ```yaml
@@ -312,6 +352,7 @@ spec:
 | `queryInterval` | string | Optional. Minimum interval between queries as a Go duration string (e.g. `10m`, `1h`, `90s`). Skips querying Microsoft Graph until the interval has elapsed since the last successful query, independent of reconcile frequency. Only effective in Composition mode with a `status.` target. |
 | `failOnEmpty` | bool | Optional. When true, the function will fail if the `users`, `groups`, or `servicePrincipals` lists are empty, or if their respective reference fields are empty lists. |
 | `activeAccount` | bool | Optional. `UserValidation` only. When true, only users whose Entra ID `accountEnabled` attribute is true are stored at the target; disabled users, and users whose account state Graph does not report, are omitted. |
+| `additionalFields` | []string | Optional. Extra Microsoft Graph fields to include in results. Supported for all query types. Appended to the default field set for each type (see [Additional Fields](#additional-fields) section). |
 | `identity.type` | string | Optional. Type of identity credentials to use. Valid values: `AzureServicePrincipalCredentials`, `AzureWorkloadIdentityCredentials`. Default is `AzureServicePrincipalCredentials` |
 
 ## Result Targets

example/user-validation-additional-fields-example.yaml

@@ -0,0 +1,49 @@
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+metadata:
+  name: user-validation-additional-fields-example
+# Demonstrates the additionalFields feature for UserValidation.
+# The extra fields are appended to the default set (id, displayName,
+# userPrincipalName, mail) and returned in status.validatedUsers.
+#
+# Required Azure AD app registration permissions:
+#   - User.Read.All
+#   - Directory.Read.All
+spec:
+  compositeTypeRef:
+    apiVersion: example.crossplane.io/v1
+    kind: XR
+  mode: Pipeline
+  pipeline:
+    - step: validate-user-with-extra-fields
+      functionRef:
+        name: function-msgraph
+      input:
+        apiVersion: msgraph.fn.crossplane.io/v1alpha1
+        kind: Input
+        queryType: UserValidation
+        # Replace with actual user principal names from your directory
+        users:
+          - "user@example.onmicrosoft.com"
+        target: "status.validatedUsers"
+        skipQueryWhenTargetHasData: true
+        # Extra Microsoft Graph user properties to include in the result.
+        # These are appended to the default fields: id, displayName,
+        # userPrincipalName, mail.
+        # Supported values: any standard Graph user property (camelCase)
+        # or OData extension attribute (e.g. extension_<appId>_<name>).
+        # If a field has no value set in Entra ID it is silently omitted
+        # from the result (Debug log emitted). If the field name is wrong
+        # an Info log is emitted and the field is omitted.
+        additionalFields:
+          - city
+          - country
+          - department
+          - jobTitle
+          - usageLocation
+      credentials:
+        - name: azure-creds
+          source: Secret
+          secretRef:
+            namespace: crossplane-system
+            name: azure-account-creds

fn.go

@@ -82,6 +82,90 @@ const (
 	unknownType          = "unknown"
 )
 
+// callTypedGetter invokes a no-argument getter method on obj by reflection.
+// Returns (value, found, hasGetter):
+//   - hasGetter=false: no method with the expected name/signature exists.
+//   - hasGetter=true, found=false: method exists but returned nil/zero (field not set).
+//   - hasGetter=true, found=true: method returned a non-nil/non-zero value.
+func callTypedGetter(obj interface{}, methodName string) (interface{}, bool, bool) {
+	m := reflect.ValueOf(obj).MethodByName(methodName)
+	if !m.IsValid() || m.Type().NumIn() != 0 || m.Type().NumOut() != 1 {
+		return nil, false, false
+	}
+	rv := m.Call(nil)[0]
+	if rv.Kind() == reflect.Pointer && !rv.IsNil() {
+		return rv.Elem().Interface(), true, true
+	}
+	if rv.IsValid() && !rv.IsZero() {
+		return rv.Interface(), true, true
+	}
+	return nil, false, true
+}
+
+// lookupAdditionalData checks whether field is present in the object's OData
+// additional data bag (used for extension attributes not modelled as typed fields).
+func lookupAdditionalData(obj interface{}, field string) (interface{}, bool) {
+	type additionalDataProvider interface {
+		GetAdditionalData() map[string]interface{}
+	}
+	if adder, ok := obj.(additionalDataProvider); ok {
+		val, exists := adder.GetAdditionalData()[field]
+		return val, exists
+	}
+	return nil, false
+}
+
+// applyAdditionalFields extracts each requested field from obj and stores
+// found values in m. It is a convenience wrapper around extractTypedOrAdditionalField.
+func (g *GraphQuery) applyAdditionalFields(m map[string]interface{}, obj interface{}, objectID string, fields []string) {
+	for _, field := range fields {
+		if val, ok := g.extractTypedOrAdditionalField(obj, field, objectID); ok {
+			m[field] = val
+		}
+	}
+}
+
+// extractTypedOrAdditionalField resolves a field value from a Microsoft Graph
+// SDK model object. It first attempts to call the typed getter derived from
+// the field name (e.g. "city" → GetCity(), "jobTitle" → GetJobTitle()) using
+// reflection. This is necessary because the kiota-generated SDK deserializes
+// known properties into typed struct fields, not into GetAdditionalData().
+// If no typed getter exists (e.g. for OData extension attributes), the
+// method falls back to GetAdditionalData().
+//
+// Logging behaviour:
+//   - Debug: field is a known SDK property but has no value set for this object
+//     (e.g. user.city is empty in Entra ID) — expected, no action needed.
+//   - Info:  field is not found via typed getter OR additionalData — likely a
+//     typo or unsupported field name in additionalFields config.
+func (g *GraphQuery) extractTypedOrAdditionalField(obj interface{}, field, objectID string) (interface{}, bool) {
+	if len(field) == 0 {
+		return nil, false
+	}
+	// Build the expected getter name: "city" → "GetCity", "jobTitle" → "GetJobTitle"
+	methodName := "Get" + strings.ToUpper(field[:1]) + field[1:]
+	if val, found, hasGetter := callTypedGetter(obj, methodName); hasGetter {
+		if found {
+			return val, true
+		}
+		// Typed getter exists but returned nil/zero — field is known but not set.
+		if g.log != nil {
+			g.log.Debug("additionalFields: field is a valid Graph property but has no value for this object",
+				"field", field, "objectID", objectID)
+		}
+		return nil, false
+	}
+	if val, found := lookupAdditionalData(obj, field); found {
+		return val, true
+	}
+	// Field not found anywhere — likely a typo or unsupported field name.
+	if g.log != nil {
+		g.log.Info("additionalFields: field not found in Graph SDK model or additionalData — verify the field name in additionalFields config",
+			"field", field, "objectID", objectID)
+	}
+	return nil, false
+}
+
 // GraphQueryInterface defines the methods required for querying Microsoft Graph API.
 type GraphQueryInterface interface {
 	graphQuery(ctx context.Context, azureCreds map[string]string, in *v1beta1.Input) (interface{}, error)
@@ -545,9 +629,12 @@ func (g *GraphQuery) validateUsers(ctx context.Context, client *msgraphsdk.Graph
 		filterValue := fmt.Sprintf("userPrincipalName eq '%s'", *userPrincipalName)
 		requestConfig.QueryParameters.Filter = &filterValue
 
-		// Use standard fields for user validation. accountEnabled is returned by
-		// Microsoft Graph only when it is explicitly selected.
-		requestConfig.QueryParameters.Select = []string{"id", fieldDisplayName, fieldUserPrincipalName, fieldMail, fieldAccountEnabled}
+		// Use standard fields for user validation, appending any extra fields requested.
+		// accountEnabled is returned by Microsoft Graph only when explicitly selected.
+		selectFields := make([]string, 0, 5+len(in.AdditionalFields))
+		selectFields = append(selectFields, "id", fieldDisplayName, fieldUserPrincipalName, fieldMail, fieldAccountEnabled)
+		selectFields = append(selectFields, in.AdditionalFields...)
+		requestConfig.QueryParameters.Select = selectFields
 
 		// Execute the query
 		result, err := client.Users().Get(ctx, requestConfig)
@@ -556,7 +643,7 @@ func (g *GraphQuery) validateUsers(ctx context.Context, client *msgraphsdk.Graph
 		}
 
 		// Process results
-		results = append(results, g.buildUserResults(result.GetValue(), requireActiveAccount)...)
+		results = append(results, g.buildUserResults(result.GetValue(), requireActiveAccount, in.AdditionalFields)...)
 	}
 
 	return results, nil
@@ -567,7 +654,7 @@ func (g *GraphQuery) validateUsers(ctx context.Context, client *msgraphsdk.Graph
 // attribute is not true are omitted. A nil attribute is treated as disabled,
 // because Microsoft Graph returns accountEnabled only when it is explicitly
 // selected, so an absent value means the account state is unconfirmed.
-func (g *GraphQuery) buildUserResults(graphUsers []models.Userable, requireActiveAccount bool) []interface{} {
+func (g *GraphQuery) buildUserResults(graphUsers []models.Userable, requireActiveAccount bool, additionalFields []string) []interface{} {
 	results := make([]interface{}, 0, len(graphUsers))
 
 	for _, user := range graphUsers {
@@ -582,13 +669,15 @@ func (g *GraphQuery) buildUserResults(graphUsers []models.Userable, requireActiv
 			continue
 		}
 
-		results = append(results, map[string]interface{}{
+		userMap := map[string]interface{}{
 			"id":                   ptr.Deref(user.GetId(), ""),
 			fieldDisplayName:       ptr.Deref(user.GetDisplayName(), ""),
 			fieldUserPrincipalName: ptr.Deref(user.GetUserPrincipalName(), ""),
 			fieldMail:              ptr.Deref(user.GetMail(), ""),
 			fieldAccountEnabled:    accountEnabled,
-		})
+		}
+		g.applyAdditionalFields(userMap, user, ptr.Deref(user.GetId(), "unknown"), additionalFields)
+		results = append(results, userMap)
 	}
 
 	return results
@@ -619,18 +708,23 @@ func (g *GraphQuery) findGroupByName(ctx context.Context, client *msgraphsdk.Gra
 	return groupResult.GetValue()[0].GetId(), nil
 }
 
-// fetchGroupMembers fetches all members of a group by group ID
-func (g *GraphQuery) fetchGroupMembers(ctx context.Context, client *msgraphsdk.GraphServiceClient, groupID string, groupName string) ([]models.DirectoryObjectable, error) {
-	// Create a request configuration that expands members
-	// This is the workaround for the known issue where service principals
-	// are not listed as group members in v1.0
+// fetchGroupMembers fetches all members of a group by group ID.
+// additionalFields extends the nested $select inside the $expand expression.
+func (g *GraphQuery) fetchGroupMembers(ctx context.Context, client *msgraphsdk.GraphServiceClient, groupID string, groupName string, additionalFields []string) ([]models.DirectoryObjectable, error) {
+	// Build the nested $select list for the $expand workaround.
+	// The workaround is required because service principals are not listed as
+	// group members via the standard /members endpoint in v1.0.
 	// See: https://developer.microsoft.com/en-us/graph/known-issues/?search=25984
+	memberSelectFields := append(
+		[]string{"id", "displayName", "mail", "userPrincipalName", "appId"},
+		additionalFields...,
+	)
 	requestConfig := &groups.GroupItemRequestBuilderGetRequestConfiguration{
 		QueryParameters: &groups.GroupItemRequestBuilderGetQueryParameters{
-			// Explicitly select the standard member fields via a nested $select so
-			// that user properties such as mail and userPrincipalName are returned
-			// for the expanded members (see issue #115).
-			Expand: []string{"members($select=id,displayName,mail,userPrincipalName,appId)"},
+			// Explicitly select member fields via a nested $select so that user
+			// properties such as mail and userPrincipalName are returned for the
+			// expanded members (see issue #115).
+			Expand: []string{fmt.Sprintf("members($select=%s)", strings.Join(memberSelectFields, ","))},
 		},
 	}
 
@@ -806,16 +900,17 @@ func (g *GraphQuery) getGroupMembers(ctx context.Context, client *msgraphsdk.Gra
 		return nil, err
 	}
 
-	// Fetch the members
-	memberObjects, err := g.fetchGroupMembers(ctx, client, *groupID, groupName)
+	// Fetch the members, forwarding any extra fields for the nested $select
+	memberObjects, err := g.fetchGroupMembers(ctx, client, *groupID, groupName, in.AdditionalFields)
 	if err != nil {
 		return nil, err
 	}
 
-	// Process the members
+	// Process the members and attach any additional fields from additionalData
 	members := make([]interface{}, 0, len(memberObjects))
 	for _, member := range memberObjects {
 		memberMap := g.processMember(member)
+		g.applyAdditionalFields(memberMap, member, ptr.Deref(member.GetId(), "unknown"), in.AdditionalFields)
 		members = append(members, memberMap)
 	}
 
@@ -844,8 +939,11 @@ func (g *GraphQuery) getGroupObjectIDs(ctx context.Context, client *msgraphsdk.G
 		filterValue := fmt.Sprintf("displayName eq '%s'", *groupName)
 		requestConfig.QueryParameters.Filter = &filterValue
 
-		// Use standard fields for group object IDs
-		requestConfig.QueryParameters.Select = []string{"id", fieldDisplayName, fieldDescription}
+		// Use standard fields for group object IDs, appending any extra fields requested
+		selectFields := make([]string, 0, 3+len(in.AdditionalFields))
+		selectFields = append(selectFields, "id", fieldDisplayName, fieldDescription)
+		selectFields = append(selectFields, in.AdditionalFields...)
+		requestConfig.QueryParameters.Select = selectFields
 
 		groupResult, err := client.Groups().Get(ctx, requestConfig)
 		if err != nil {
@@ -859,6 +957,7 @@ func (g *GraphQuery) getGroupObjectIDs(ctx context.Context, client *msgraphsdk.G
 					fieldDisplayName: ptr.Deref(group.GetDisplayName(), ""),
 					fieldDescription: ptr.Deref(group.GetDescription(), ""),
 				}
+				g.applyAdditionalFields(groupMap, group, ptr.Deref(group.GetId(), "unknown"), in.AdditionalFields)
 				results = append(results, groupMap)
 			}
 		}
@@ -889,8 +988,11 @@ func (g *GraphQuery) getServicePrincipalDetails(ctx context.Context, client *msg
 		filterValue := fmt.Sprintf("displayName eq '%s'", *spName)
 		requestConfig.QueryParameters.Filter = &filterValue
 
-		// Use standard fields for service principals
-		requestConfig.QueryParameters.Select = []string{"id", fieldAppID, fieldDisplayName, fieldDescription}
+		// Use standard fields for service principals, appending any extra fields requested
+		selectFields := make([]string, 0, 4+len(in.AdditionalFields))
+		selectFields = append(selectFields, "id", fieldAppID, fieldDisplayName, fieldDescription)
+		selectFields = append(selectFields, in.AdditionalFields...)
+		requestConfig.QueryParameters.Select = selectFields
 
 		spResult, err := client.ServicePrincipals().Get(ctx, requestConfig)
 		if err != nil {
@@ -905,6 +1007,7 @@ func (g *GraphQuery) getServicePrincipalDetails(ctx context.Context, client *msg
 					fieldDisplayName: ptr.Deref(sp.GetDisplayName(), ""),
 					fieldDescription: ptr.Deref(sp.GetDescription(), ""),
 				}
+				g.applyAdditionalFields(spMap, sp, ptr.Deref(sp.GetId(), "unknown"), in.AdditionalFields)
 				results = append(results, spMap)
 			}
 		}