// Copyright (c) 2026 Probo Inc . // // Permission is hereby granted, free of charge, to any person obtaining a copy // of this software and associated documentation files (the "Software"), to deal // in the Software without restriction, including without limitation the rights // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell // copies of the Software, and to permit persons to whom the Software is // furnished to do so, subject to the following conditions: // // The above copyright notice and this permission notice shall be included in // all copies or substantial portions of the Software. // // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. package drivers import ( "context" "encoding/json" "errors" "fmt" "io" "net/http" "net/url" "strconv" "strings" "time" "go.gearno.de/kit/log" "go.probo.inc/probo/pkg/coredata" ) // Microsoft365Driver fetches user accounts from a Microsoft 365 / Microsoft // Entra ID tenant via the Microsoft Graph API using a pre-authenticated // HTTP client (Bearer token). type Microsoft365Driver struct { httpClient *http.Client logger *log.Logger } var _ Driver = (*Microsoft365Driver)(nil) const ( microsoft365GraphBaseURL = "https://graph.microsoft.com/v1.0" microsoft365UsersSelect = "id,userPrincipalName,mail,displayName,givenName,surname,accountEnabled,jobTitle,department,createdDateTime" microsoft365UserTypeMemberFilter = "userType eq 'Member'" microsoft365UsersPageSize = 999 microsoft365MaxPaginationOK = maxPaginationPages ) // adminRoleDisplayNames lists the directory role display names that the // driver treats as administrative. Microsoft splits administration across // many roles; matching by display name keeps the driver readable. var adminRoleDisplayNames = map[string]bool{ "Global Administrator": true, "Company Administrator": true, "Privileged Role Administrator": true, "Privileged Authentication Administrator": true, "Security Administrator": true, "User Administrator": true, "Conditional Access Administrator": true, "Compliance Administrator": true, "Application Administrator": true, "Cloud Application Administrator": true, "Authentication Administrator": true, } func NewMicrosoft365Driver(httpClient *http.Client, logger *log.Logger) *Microsoft365Driver { return &Microsoft365Driver{ httpClient: &http.Client{ Transport: &retryRoundTripper{ next: httpClient.Transport, maxRetries: 3, }, }, logger: logger, } } type microsoft365User struct { ID string `json:"id"` UserPrincipalName string `json:"userPrincipalName"` Mail string `json:"mail"` DisplayName string `json:"displayName"` GivenName string `json:"givenName"` Surname string `json:"surname"` AccountEnabled bool `json:"accountEnabled"` JobTitle string `json:"jobTitle"` Department string `json:"department"` CreatedDateTime string `json:"createdDateTime"` } type microsoft365UsersPage struct { Value []microsoft365User `json:"value"` NextLink string `json:"@odata.nextLink"` } type microsoft365DirectoryRole struct { ID string `json:"id"` DisplayName string `json:"displayName"` } type microsoft365RolesPage struct { Value []microsoft365DirectoryRole `json:"value"` NextLink string `json:"@odata.nextLink"` } type microsoft365RoleMember struct { ID string `json:"id"` ODataType string `json:"@odata.type"` DisplayName string `json:"displayName"` } type microsoft365MembersPage struct { Value []microsoft365RoleMember `json:"value"` NextLink string `json:"@odata.nextLink"` } type microsoft365UserRegistrationDetails struct { ID string `json:"id"` UserPrincipalName string `json:"userPrincipalName"` IsMFARegistered *bool `json:"isMfaRegistered"` } type microsoft365UserRegistrationDetailsPage struct { Value []microsoft365UserRegistrationDetails `json:"value"` NextLink string `json:"@odata.nextLink"` } func (d *Microsoft365Driver) ListAccounts(ctx context.Context) ([]AccountRecord, error) { roles, err := d.listDirectoryRoles(ctx) if err != nil { return nil, fmt.Errorf("cannot list directory roles: %w", err) } rolesByUser := make(map[string][]string) for _, role := range roles { members, err := d.listRoleMembers(ctx, role.ID) if err != nil { return nil, fmt.Errorf("cannot list members of role %q: %w", role.DisplayName, err) } for _, m := range members { if m.ODataType != "" && m.ODataType != "#microsoft.graph.user" { continue } rolesByUser[m.ID] = append(rolesByUser[m.ID], role.DisplayName) } } users, err := d.listUsers(ctx) if err != nil { return nil, fmt.Errorf("cannot list users: %w", err) } // MFA registration details require AuditLog.Read.All. A failure here // must not abort the account fetch — leave MFA unknown so the campaign // can still proceed. Context cancel/deadline still fail the fetch so a // timed-out source does not commit an incomplete result as success. mfaStatuses, err := d.listMFAStatuses(ctx) if err != nil { if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) { return nil, fmt.Errorf("cannot list MFA statuses: %w", err) } d.logger.ErrorCtx(ctx, "cannot list microsoft 365 MFA statuses, reporting MFA unknown", log.Error(err)) mfaStatuses = map[string]coredata.MFAStatus{} } records := make([]AccountRecord, 0, len(users)) for _, u := range users { email := u.Mail if email == "" { email = u.UserPrincipalName } // Skip accounts without any usable identifier so the access // review only lists real members, matching the SCIM bridge. if email == "" { continue } userRoles := rolesByUser[u.ID] isAdmin := false for _, r := range userRoles { if adminRoleDisplayNames[r] { isAdmin = true break } } roles := userRoles if len(roles) == 0 { roles = []string{"User"} } active := u.AccountEnabled rec := AccountRecord{ Email: email, FullName: u.DisplayName, Roles: roles, JobTitle: u.JobTitle, Active: &active, IsAdmin: isAdmin, MFAStatus: microsoft365MFAStatus(u, mfaStatuses), AuthMethod: coredata.AccessReviewEntryAuthMethodSSO, AccountType: coredata.AccessReviewEntryAccountTypeUser, ExternalID: u.ID, } if u.CreatedDateTime != "" { if t, err := time.Parse(time.RFC3339, u.CreatedDateTime); err == nil { rec.CreatedAt = &t } } records = append(records, rec) } return records, nil } func microsoft365MFAStatus(u microsoft365User, statuses map[string]coredata.MFAStatus) coredata.MFAStatus { if status, ok := statuses[u.ID]; ok { return status } if status, ok := statuses[strings.ToLower(u.UserPrincipalName)]; ok { return status } return coredata.MFAStatusUnknown } func microsoft365RegistrationMFAStatus( details microsoft365UserRegistrationDetails, ) coredata.MFAStatus { if details.IsMFARegistered == nil { return coredata.MFAStatusUnknown } if *details.IsMFARegistered { return coredata.MFAStatusEnabled } return coredata.MFAStatusDisabled } func (d *Microsoft365Driver) listUsers(ctx context.Context) ([]microsoft365User, error) { pageURL, err := buildMicrosoft365UsersURL() if err != nil { return nil, err } var all []microsoft365User for range microsoft365MaxPaginationOK { var page microsoft365UsersPage if err := d.fetchJSON(ctx, pageURL, &page); err != nil { return nil, err } all = append(all, page.Value...) if page.NextLink == "" { return all, nil } pageURL = page.NextLink } return nil, fmt.Errorf("cannot list all microsoft 365 users: %w", ErrPaginationLimitReached) } func buildMicrosoft365UsersURL() (string, error) { u, err := url.Parse(microsoft365GraphBaseURL + "/users") if err != nil { return "", fmt.Errorf("cannot parse graph users URL: %w", err) } q := u.Query() q.Set("$select", microsoft365UsersSelect) q.Set("$top", strconv.Itoa(microsoft365UsersPageSize)) q.Set("$filter", microsoft365UserTypeMemberFilter) u.RawQuery = q.Encode() return u.String(), nil } func (d *Microsoft365Driver) listMFAStatuses(ctx context.Context) (map[string]coredata.MFAStatus, error) { pageURL, err := buildMicrosoft365UserRegistrationDetailsURL() if err != nil { return nil, err } statuses := make(map[string]coredata.MFAStatus) for range microsoft365MaxPaginationOK { var page microsoft365UserRegistrationDetailsPage if err := d.fetchJSON(ctx, pageURL, &page); err != nil { return nil, err } for _, details := range page.Value { status := microsoft365RegistrationMFAStatus(details) if details.ID != "" { statuses[details.ID] = status } if details.UserPrincipalName != "" { statuses[strings.ToLower(details.UserPrincipalName)] = status } } if page.NextLink == "" { return statuses, nil } pageURL = page.NextLink } return nil, fmt.Errorf("cannot list all microsoft 365 MFA statuses: %w", ErrPaginationLimitReached) } func buildMicrosoft365UserRegistrationDetailsURL() (string, error) { endpoint, err := url.JoinPath( microsoft365GraphBaseURL, "reports", "authenticationMethods", "userRegistrationDetails", ) if err != nil { return "", fmt.Errorf("cannot build graph user registration details URL: %w", err) } u, err := url.Parse(endpoint) if err != nil { return "", fmt.Errorf("cannot parse graph user registration details URL: %w", err) } return u.String(), nil } func (d *Microsoft365Driver) listDirectoryRoles(ctx context.Context) ([]microsoft365DirectoryRole, error) { endpoint, err := url.JoinPath(microsoft365GraphBaseURL, "directoryRoles") if err != nil { return nil, fmt.Errorf("cannot build graph directory roles URL: %w", err) } var all []microsoft365DirectoryRole for range microsoft365MaxPaginationOK { var page microsoft365RolesPage if err := d.fetchJSON(ctx, endpoint, &page); err != nil { return nil, err } all = append(all, page.Value...) if page.NextLink == "" { return all, nil } endpoint = page.NextLink } return nil, fmt.Errorf("cannot list all microsoft 365 directory roles: %w", ErrPaginationLimitReached) } func (d *Microsoft365Driver) listRoleMembers(ctx context.Context, roleID string) ([]microsoft365RoleMember, error) { endpoint, err := url.JoinPath(microsoft365GraphBaseURL, "directoryRoles", url.PathEscape(roleID), "members") if err != nil { return nil, fmt.Errorf("cannot build graph role members URL: %w", err) } var all []microsoft365RoleMember for range microsoft365MaxPaginationOK { var page microsoft365MembersPage if err := d.fetchJSON(ctx, endpoint, &page); err != nil { return nil, err } all = append(all, page.Value...) if page.NextLink == "" { return all, nil } endpoint = page.NextLink } return nil, fmt.Errorf("cannot list all members of role %q: %w", roleID, ErrPaginationLimitReached) } func (d *Microsoft365Driver) fetchJSON(ctx context.Context, url string, dst any) error { req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) if err != nil { return fmt.Errorf("cannot create graph request: %w", err) } req.Header.Set("Accept", "application/json") resp, err := d.httpClient.Do(req) if err != nil { return fmt.Errorf("cannot execute graph request: %w", err) } defer func() { _ = resp.Body.Close() }() if resp.StatusCode < 200 || resp.StatusCode >= 300 { body, _ := io.ReadAll(resp.Body) return fmt.Errorf("microsoft graph error: status %d, body: %s", resp.StatusCode, string(body)) } if err := json.NewDecoder(resp.Body).Decode(dst); err != nil { return fmt.Errorf("cannot decode graph response: %w", err) } return nil }