Microsoft 365 integration¶

This documentation describes how to connect OctoSAM to Microsoft Graph.

Basic operation¶

The Microsoft 365 integration is built into the OctoSAM import service. The service uses Microsoft Graph to connect to Entra ID (formerly Azure Active Directory) and Microsoft 365 (formerly Office 365). OctoSAM reads information about registered users, devices, licensing and application usage data and maps it to the OctoSAM data model.

Your network infrastructure needs to allow Microsoft Graph API calls from the OctoSAM server to the Microsoft 365 Graph API endpoint.

Microsoft app usage reports requirements¶

The integration of Microsoft 365 app usage reports requires user names in the reports that can be mapped to OctoSAM user entities. Usage reports cannot be imported if Microsoft 365 is configured to obfuscate user information in the usage reports (which is the default setting).

The import of user sign-in activity requires an Entra ID P1 or P2 license.

Register OctoSAM import service as an Entra ID app¶

Essentials¶

Register an application OctoSAM Import Service for your organization only. The OctoSAM import service will log on to Entra ID with the information returned by this registration. As there is no interactive UI for this app, you do not have to configure a redirect URL.

Microsoft Documentation

Currently, only password-based authentication (application secret) is supported. Support for certificate-based authentication is planned for a future release.

Copy the following information from the registration page:

Application (client) ID
Directory (tenant) ID
The secret

Required API permissions¶

AuditLog.Read.All (Application)
Reports.Read.All (Application)
Directory.Read.All (Application)
UserAuthenticationMethod.Read.All (Application)
User.Read.All (Application)
User.Read (Delegated)

Configure the OctoSAM import service to connect to Microsoft Graph¶

Storing secrets in Windows Credential Manager¶

Open Windows Credential Manager
Select Windows Credentials
Add a new generic credential
Enter the target name that matches SecretCredentialManagerTarget in your configuration
Enter the secret from your Entra ID app registration as the password

Configuration¶

See the sample configuration file appsettings.json:

  //
  // Integrated Microsoft 365 / Entra ID Graph Scan
  // ----------------------------------------------
  //
  // Name:     A user defined name to identify the configuration in log an error messages
  //
  // ApplicationId:                  ApplicationId from Entra ID registration
  // TenantId:                       Entra ID tenant information
  // Secret:                         Secret from Entra ID App registration 
  //                                 (prefer SecretCredentialManagerTarget and store the secret in the Windows Credential Manager)
  // SecretCredentialManagerTarget:  Target name to load secret from the Windows Credential Manager.
  //                                 If this setting is set, the setting for Secret is ignored.
  //
  // ImportSignInActivity            Can be set to false if either the AuditLog.Read.All permission is not given or the tenant does not have a license that allows SignInActivity logging.
  //                                 SignInActivity import requires an Entra ID P1 or P2 license.
  //
  // ImportUsageReports              Can be set to false if the Reports.Read.All permission is not given or if the reports are anonymized in Graph.
  //

  "MicrosoftGraph": {
    "Scans": [
      {
        "ApplicationId" : "2855c234-88bf-49a5-89ce-2c950715e6b3",
        "TenantId": "a07c4b22-98eb-4586-a599-fa3616d0afbb",
        "SecretCredentialManagerTarget": "msgraph",
        // "ImportSignInActivity": true,
        // "ImportUsageReports": true
      }
    ]
  }

Info

We recommend that you store the secret in the Windows Credential Manager.

Configure Entra ID group scans¶

Entra ID groups can be imported in addition to Active Directory groups. To configure group scanning:

Ensure you have the Directory.Read.All permission
Configure the groups to scan in your appsettings.json
Groups will be synchronized during the next RBAC import cycle

See the sample appsettings.json file provided with your installation for detailed configuration options.