Integrating with Microsoft 365

Table 1. Minimal user permissions
Process	Required user role in the Microsoft 365 application	Authentication scopes
Download subscriptions	Application developer	User.Read.All Organization.Read.All
Pull user activity	Power platform administrator Application developer	Reports.Read.All

Register a Microsoft Azure AD application

Register an application through the Microsoft Azure portal.

Before you begin

Microsoft Azure AD Role required: Refer to the Minimal user permissions table.

Procedure

From a web browser, open the App registrations page of the Microsoft Azure portal.
Log in using your global administrator credentials.
On the App registrations page, select New registration.
In the Name section of the Register an application form, enter a name for the application.
In the Supported account types section, select Accounts in any organizational directory (Any Azure AD directory - Multitentant).
Select Register.
The application is registered and you are automatically redirected to the Overview page for the new application.
On the Overview page, copy the values in the Application (client) ID and Directory (tenant) ID fields.
Save them in a secure location for later use.

Generate a client secret for your application.

From the left navigation menu, navigate to Manage > Certificates & secrets.
The Certificates & secrets page opens.
In the Client secrets section, generate a client secret for the application by selecting New client secret.
The Add a client secret dialog box opens.

On the dialog box, fill in the fields.

Table 2. Add a client secret dialog box
Field	Description
Description	Description of the client secret.
Expires	Period of time after which you want the client secret to expire. The options are: In 1 year In 2 years Never

Select Add.
The dialog box closes and you return to the Certificates & secrets page.
In the Client secrets section, copy the value in the VALUE field for the newly generated client secret.
Save this in a secure location for later use.

Specify the level of access that the application has to your protected resources.
1. From the left navigation menu, navigate to Manage > API permissions.
  The API permissions page opens.
2. Select Add a permission.
  The Request API permissions dialog box opens.
3. On the dialog box, select the Microsoft APIs tab.
4. From the list of available Microsoft APIs, select Microsoft Graph.
5. When prompted to select the types of permissions that the application requires, select Application permissions.
6. Under Select permissions, select the check boxes for the following permissions:
  - Reports.Read.All
  - User.Read.All
  - Organization.Read.All
7. Select Add permissions.
  The dialog box closes and you return to the API permissions page.
Grant admin consent for your application.

What to do next

After you successfully register and set up your application, remain in the Microsoft Azure portal if you need to enable your application to access Power BI service content and APIs.

Enable service principal authentication for Power-BI read-only APIs

Grant your application access to Power BI service content and APIs by enabling service principal authentication for Power BI read-only APIs. Power BI service content and APIs help optimize your Microsoft 365 subscriptions, such as by downgrading subscriptions from Office 365 E5 to Office 365 E3.

Before you begin

Microsoft Azure AD Role required: global administrator

Power BI Role required: global administrator or Power BI administrator

Note:

This configuration enables ServiceNow Software Asset Management to get the usage information (Last usage time) for all Power BI Pro deployments across the Web and Desktop. Software Asset Management pulls the last activity date for Power BI deployments that are part of Microsoft 365 subscriptions.

About this task

Service principal is an authentication method that allows your application to access secure Microsoft Azure AD resources, such as Power BI service content and APIs.

Procedure

Create a security group for service principal authentication.

Security groups enable you to manage which users, devices, groups, and service principals can access shared resources. If you want to use an existing security group for service principal authentication, skip to step 2.

On the page header of the Microsoft Azure portal, use the search bar to search for and select the Azure Active Directory service.
The Overview page for the Azure Active Directory service opens.
From the left navigation menu of the Azure Active Directory service, navigate to Manage > Groups.
The Groups > All groups page opens.
On the All groups page, select New group.

On the form, fill in the fields.

Table 3. New Group form
Field	Description
Group type	Group type. Set this field to Security.
Group name	Name of the group.
Group email address	Email address that is shared between all group members.
Group description	Description of the group.
Membership type	Method in which members can be added to or removed from the group. The options are: Assigned: Members must be added or removed manually. Dynamic user: Members are added or removed automatically based on the dynamic group rules that you define. See Create or update a dynamic group in Azure Active Directory for more information on dynamic group rules. Dynamic device: Devices are added or removed automatically based on the dynamic group rules that you define. See Create or update a dynamic group in Azure Active Directory for more information on dynamic group rules.

Select Create.

The security group is created and then you are redirected to the Overview page for the new group.

Add the application that you created in Register a Microsoft Azure AD application as a member of your security group.
1. If you did not create a security group in step 1 and are using an existing security group instead, open your existing security group.
  If you created a security group in step 1, skip to step b.
  1. On the page header of the Microsoft Azure portal, use the search bar to search for and select the Azure Active Directory service.
    The Overview page for the Azure Active Directory service opens.
  2. From the left navigation menu of the Azure Active Directory service, navigate to Manage > Groups.
    The Groups > All groups page opens.
  3. From the list of available groups, locate and select your existing security group.
    The Overview page for the security group opens.
2. From the left navigation menu of your security group, navigate to Manage > Members.
  The Members page opens.
3. On the Members page, select Add members.
  The Add members dialog box opens.
4. On the dialog box, search for and select the application that you created in Register a Microsoft Azure AD application.
  Important:
  The application must not have any Power BI admin permissions set from the Microsoft Azure portal. You can verify your application permissions using the following steps:
  
  Log in to the Microsoft Azure portal using either your global administrator, application administrator, or cloud application administrator credentials.
  
  On the page header of the Microsoft Azure portal, use the search bar to search for and select the Azure Active Directory service.
  The Overview page for the Azure Active Directory service opens.
  
  From the left navigation menu of the Azure Active Directory service, navigate to Manage > Enterprise applications.
  The Enterprise applications page opens.
  
  From the list of available enterprise applications, locate and select your application.
  
  Select Permissions.
  
  Verify that no Power BI admin-consent-required permissions are set on the application.
5. Select Select.
  The application is added as a member of your security group.
Enable your security group to access read-only Power BI admin APIs.
1. In a new tab or web browser, open Power BI.
2. Log in using either your global administrator or Power BI administrator credentials.
  The Power BI portal opens.
3. On the page header of the Power BI portal, select the Settings icon () and then select Admin portal.
  The Power BI Admin portal opens.
4. From the left navigation menu of the Admin portal, select Tenant settings.
  Your Power BI tenant settings open.
5. In the Admin API settings section, expand the Allow service principals to use read-only Power BI admin APIs setting.
6. Select the toggle button to enable the setting.
7. When prompted, select the option to apply the setting to Specific security groups.
8. In the corresponding text box, enter the name of your security group.
9. Select Apply.
After you enable this setting through the Power BI Admin portal, any application permissions that you set from the Microsoft Azure portal are no longer effective. All application permissions must subsequently be set and managed through the Power BI Admin portal.

Configure updates on Microsoft 365 Admin Center

Prevent anonymous user information in Microsoft 365 reports on activity to be imported to ServiceNow.

Before you begin

Role required: admin

Procedure

Log in to Microsoft 365 admin center by using your admin credentials.
Navigate to Settings > Services > Org settings > Reports.
Deselect the Display concealed user, group, and site names in all reports check box.
For more information about the Microsoft 365 reports showing anonymous user information, see Microsoft 365 reports show anonymous user names instead of actual user names.

Create a Microsoft 365 integration profile

Create an integration profile to track software subscriptions and optimize stale licenses for the Microsoft 365 service.

Before you begin

ServiceNow Role required: sam_integrator or admin

To integrate with Microsoft 365, activate the following plugins:

Software Asset Management Professional for Microsoft plugin (com.snc.samp.microsoft)
Software Asset Management - SaaS License Management (sn_sam_saas_int) plugin from the ServiceNow Store
For more information, see Request SaaS License Management.

About this task

If you’re using Software Asset Workspace, the option to create the direct integration profile in Core UI is inactive.

Procedure

From a web browser, open your ServiceNow instance.

Interface	Action
Core UI	Navigate to All > Software Asset > SaaS License > Direct Integration Profiles
Software Asset Workspace	Navigate to Workspaces > Software Asset Workspace > License operations. Under User subscription, select Direct integration profiles.

Select New.
Select Microsoft 365 Integration Profile.

On the form, fill in the fields.

Table 4. Integration Profile form
Field	Description
Display name	Name of the integration profile. For example, `Microsoft 365 integration for <your-company>`.
Client Id	Client ID of the application that you registered in the Microsoft Azure portal. Enter the application (client) ID that you copied in Register a Microsoft Azure AD application.
Client secret	Client secret of the application that you registered in the Microsoft Azure portal. Enter the client secret that you copied in Register a Microsoft Azure AD application.
Tenant name or Id	Globally unique identifier (GUID) of the application that you registered in the Microsoft Azure portal. Enter the directory (tenant) ID that you copied in Register a Microsoft Azure AD application. Warning: When entering the directory (tenant) ID, do not add any additional extensions to the ID. Enter the ID exactly as it was copied in Register a Microsoft Azure AD application.
REST message	Message that enables you to send requests to a REST web service endpoint.
Profile type	Type of integration profile. This field is automatically set to Microsoft 365.

Select Submit.
Optional: Check the status of the user subscription job by navigating to Software Asset > Administration > Job Results.

What to do next

When you create an integration profile, a reclamation rule is automatically created for the software. It's important that you review the reclamation rule to ensure that it meets your specifications. You can view all automatically generated reclamation rules for Office 365 by navigating to Software Asset > Administration > Reclamation Rules. Reclamation rules are applied based on the Microsoft System Center Configuration Management (SCCM) usage data that is pulled through the Microsoft SCCM usage integration. For more information on these reclamation rules, see Create a reclamation rule to import Microsoft SCCM usage data.

Note:

ServiceNow automatically creates one default reclamation rule for Office 365. You can also update the Last activity threshold field under the Subscription Usage Condition tab.

Determine and verify Microsoft 365 subscription information in your ServiceNow instance

Determine the exact software subscription information to be pulled from the Microsoft 365 admin center and verify if complete subscription information is pulled accurately to ServiceNow.

Before you begin

Role required: sam_admin

Procedure

Filter with the Microsoft 365 integration profile you created to determine the exact software subscription information to be pulled from Microsoft 365 admin center to ServiceNow.
This subscription includes all subscriptions available on the Microsoft 365 admin center.
Verify with the Microsoft 365 admin if complete subscription information is pulled accurately to ServiceNow.

Note:
Software Asset Management pulls the last activity date for Microsoft 365 products using a combination of Microsoft System Center Configuration Manager (SCCM) integration and Microsoft 365 integration.
If your Microsoft 365 subscription data isn’t getting pulled into Software Asset Management, verify your integration setup:
1. On the Integration Profile form, open the REST message record by selecting the Preview icon () next to the REST message field.
2. Select Open Record in the record preview.
3. On the Rest Message form, select the Get OAuth Token related link.
4. On the OAuth flow verification dialog box, view the status of the OAuth flow to determine whether your integration is set up correctly.
  - If the OAuth token flow completed successfully message appears, your integration is set up correctly.
  - If the OAuth flow failed message appears, your integration isn’t set up correctly. Use the information in this message to identify the errors in your integration setup.
If your Power BI usage isn’t getting pulled into Software Asset Management, verify the status of your Power BI API connection.
1. On the Integration Profile form, select and hold (or right-click) the form header.
2. Select Show XML.
  
  Note:
  If the Show XML option isn't visible in the default view, you can customize the view. Select and hold (or right-click) the form header and then select View > custom integration.
3. Under <xml> > <samp_sw_subscription_profile> > <custom_properties>, view the powerBIAPIStatus property to determine the status of your Power BI API connection.
  - If the powerBIAPIStatus property is set to success, the Power BI API connection was successful.
  - If the powerBIAPIStatus property is set to failed, the Power BI API connection wasn’t successful. Verify that you’ve followed all the integration setup steps correctly. You can also check your logs for more information about any errors in your integration setup.
Optional: If the User field in the Software Subscription [samp_sw_subscription] table is empty, you can map the field with an associated user.

For more information, see Associate a user with subscription records.

Evaluating software usage activity for Microsoft 365 subscriptions

Evaluate software usage activity to discover active, inactive, and unassigned subscriptions among all subscriptions found on the Microsoft 365 portal.

Software usage activity is the usage of software products and by tracking the software usage activity that you can monitor license usage. This monitoring helps you optimize your existing software subscriptions.

The following table lists the sources for collecting the software usage activity, the associated platform support, and the supported Microsoft 365 products.


Sources of software usage activity collection	Platform support	Supported Microsoft Office 365 products
Microsoft Graph APIs	Desktop, Web, Mobile	Outlook, Word, PowerPoint, Excel, OneNote, Teams, Exchange Online, SharePoint Online, Power BI
Microsoft SCCM or ACC-V	Desktop	Microsoft Office 365 apps for Enterprise
Jamf for macOS devices	Desktop	Microsoft Office 365 apps for Enterprise

Monitoring software usage activity for license optimization

Based on the software usage activity, Software Asset Management generates optimization recommendations for your software subscriptions that include the following:

Downgrades from Microsoft 365 E5 to E3 and E3 to E1
Consolidated Microsoft 365 subscriptions
Double licensed users with both Microsoft 365 and its applications (Office 365, Enterprise Mobility+Security (EMS), Windows) subscriptions
Individual subscriptions for Microsoft Teams, Microsoft Exchange Online, Microsoft SharePoint Online, Microsoft OneDrive, and Power BI
Unassigned user subscriptions

You can view the optimization recommendations on the Optimization and savings dashboard in workspace.

After completing the Microsoft 365 integration, you can view the usage activity information using any of the following tables:

Software Usages [samp_sw_usage]
View the usage data for individual software products within the subscription in the Software Usages table. This table stores total usage and last activity retrieved from Microsoft APIs and other discovery solutions such as SCCM, Jamf, and ACC-V. The  SAM - Collect Microsoft 365 Usage  scheduled job collects the usage data daily and the  SAM - Create New Reclamation Candidates for Office 365 Integration  generates the removal candidates weekly. For more details on software usage fields and their descriptions, see View or create software usage in workspace.
The Software Usages table includes the date when the software was last used and the type of the activities performed on the Desktop, Web, Mobile, or cumulative across platforms. The last activity data helps you select an optimized plan for individual products within your Microsoft 365 subscriptions. Software Asset Management generates a removal candidate for the current subscription by showing an optimized recommendation on the License workbench.
Microsoft 365 Apps Usage Reports [samp_m365_apps_usage_report]
View the last activity date for the Microsoft 365 products in the Microsoft 365 Apps Usage Reports table for each user. This table stores usage data for Microsoft 365 products in True or False retrieved from Microsoft APIs only. The last activity date helps you determine reclamation candidates more accurately for Microsoft 365 products, including Microsoft Outlook, Microsoft Word, Excel, Microsoft PowerPoint, and OneNote. For more details on Microsoft 365 apps usage fields and their descriptions, see Microsoft 365 Apps Usage Reports.

License optimization for Microsoft subscriptions

Software usage activity helps you with license optimization by discovering reclamation candidates from both the individual Microsoft products and the Microsoft 365 suite subscriptions. You can determine the reclamation candidates both using APIs and discovery solutions.

Downgrades from Microsoft 365 E5 to E3 and E3 to E1: Determine the number of licenses per month that can be downgraded or reclaimed based on generated downgrade candidates.
Note:
You can also determine usage for Microsoft Access and Publisher from additional discovery solutions, such as Microsoft SCCM or ACC-V for E3 to E1 optimization.
Consolidated Microsoft 365 subscriptions: Find Microsoft 365 consolidate subscriptions reclamation candidates.
Double licensed users: Determine the number of licenses per month that can be downgraded or reclaimed based on recommended candidates with both Microsoft 365 and its applications (Office 365, Enterprise Mobility+Security (EMS), Windows) subscriptions.
Individual subscriptions: Reclamation rules are automatically created for individual subscriptions when the SAM - Import user subscription scheduled job runs. These individual subscriptions include Microsoft Teams, Microsoft Exchange Online, Microsoft SharePoint Online, Microsoft OneDrive, and Power BI. You can review the reclamation rules for individual subscriptions to fit your requirements. For more details, see Review a software reclamation rule.

Additionally, the subscription assignment date that is automatically populated from the Microsoft 365 portal helps in generating the reclamation candidates for individual subscriptions. The use of subscription assignment date instead of the record creation date on the ServiceNow AI Platform helps to create correct reclamation candidates based on the actual use from the Microsoft 365 portal.

Evaluate Microsoft 365 compliance and optimization results

Evaluate Microsoft 365 compliance and optimization results to find actual and potential cost savings and recommended licensing optimizations.

Before you begin

Role required: sam_admin or sam_user

The discovery of Microsoft 365 must be complete to evaluate the software compliance. For more information about using Discovery and Microsoft SCCM together, see Discovery and SCCM together.

The usage of Microsoft 365 plans must be available from both Microsoft certified APIs and Microsoft SCCM to evaluate the software optimization.

Procedure

Navigate to Software Asset Workspace > License operations.
In the left pane, select Licensing > Software entitlements.
Select New.
Create entitlements for Microsoft 365 by selecting the correct Publisher Part Number (PPN) to verify compliance.
For more information about creating entitlements, see Create entitlements in workspace.
Note:
Ensure that the License metric value is User Subscription.
Navigate to License usage in the left pane.
Select the Reconciliation tab.
Select Run reconciliation.
View compliance analysis results in Office 365 & Adobe Cloud dashboard in Software Asset Management classic and SaaS overview dashboard in workspace.
For more information about running software reconciliation, see Run software reconciliation and Run Software Asset Management Foundation plugin software reconciliation in classic.
View all optimized plans for Microsoft 365 subscription on the Optimization and savings dashboard in workspace.

Update REST and OAuth endpoints for Microsoft Office 365 Government plans

Change the endpoints of the REST message and OAuth application on your ServiceNow subscription profile so that you can use your subscriptions.

Before you begin

Role required: sam_admin

About this task

The ServiceNow AI Platform® supports Microsoft Office 365 Government plans, which provide all the features and capabilities of Microsoft 365 services in a segmented government cloud community that enables organizations to meet U.S. compliance and security standards.

For more information on Microsoft Office 365 Government plans, see Office 365 Government.

Procedure

From your ServiceNow instance, navigate to All > Software Asset > SaaS License > Direct Integration Profiles.
Select the Microsoft 365 integration profile that you want to update.
On the Integration Profile record, select the Preview this record icon () next to the REST message field.
On the record preview, select Open Record.
The REST Message record opens.
Update the REST message endpoints on your Microsoft 365 integration profile.

REST message endpoints enable you to retrieve usage data from your Microsoft 365 applications and services.
1. In the HTTP Methods related list, update the REST message endpoints based on your needs.
  
  Microsoft provides various endpoints for Microsoft Office 365 Government plans. For more information on the available endpoints, see Office 365 U.S. Government GCC High endpoints.
  
  Important:
  You must change the .com to .us in the URL of each endpoint. For example, you must change https://graph.microsoft.com/v1.0/reports to https://graph.microsoft.us/v1.0/reports.
2. Select Save.
3. Update the OAuth entity scope for the GET PowerBI Usage endpoint.
  The OAuth entity scope specifies the level of access that users have to your protected resources.
  1. Select the GET PowerBI Usage endpoint.
    
    The HTTP Method record opens.
  2. In the Authentication section of the HTTP Method record, select the Preview this record icon () next to the OAuth profile field.
  3. On the record preview, select Open Record.
    
    The OAuth Entity Profile record opens.
  4. In the OAuth Entity Profile Scopes list, update the OAuth scope field of the PowerBIPermissions OAuth entity scope with the backend API URL that you are using for Microsoft Power BI.
    Note:
    Microsoft supports various backend API URLs for Power BI. For more information on the available URLs, see Power BI for US Government.
  5. Select Update.
    
    The OAuth Entity Profile record closes and you automatically return to the REST Message record.
Update the OAuth application endpoint on your Microsoft 365 integration profile.
The OAuth application endpoint enables your ServiceNow instance to access your Microsoft 365 subscription data.
1. In the Authentication section of the REST Message record, select the Preview this record icon () next to the OAuth profile field.
2. On the record preview, select Open Record.
  The OAuth Entity Profile record opens.
3. In the OAuth Entity Profile Scopes list, change the .com to .us in the URL that is listed in the OAuth scope field of the Permissions OAuth entity scope.
4. Select the Preview this record icon () next to the OAuth provider field.
5. On the record preview, select Open Record.
  The Application Registries record opens.
6. Select the Edit URL icon () next to the Token URL field.
7. In the URL, change the .com to .us.
  For example, change https://login.microsoftonline.com to https://login.microsoftonline.us.
8. Select the Lock URL icon ().
9. Select Update.

Associate a user with subscription records

If the User field in the Software Subscription [samp_sw_subscription] table is empty, map the field with an associated user.

Before you begin

ServiceNow Role required: admin

About this task

SaaS integrations create subscription records in the Subscriptions [samp_sw_subscription] table. The fields on this table are populated by automated jobs and integrations. The User field is resolved based on the User principal name column value and verified against the email and user_name fields of the User [sys_user] table by default.

Procedure

To map the user data effectively, perform one of the following steps:

Update the User field on subscriptions manually.
By default, the integration overwrites the User field even if you set a value.
1. Update the User field of the subscription record manually to overwrite the User column value that is automatically set by the integration.
  After you update the value, the integration doesn't reset the value.
2. If you want to switch back to the user logic of the integration, clear the User field value.
  After you clear the value, the next integration execution repopulates the User field automatically.

Modify the user lookup logic for SaaS subscriptions.

If you have a different column for the user lookup, you might want to use it for lookup instead of the base system lookup.

Open the Script include SAMSaasIntegrationUtils.

Replace the getSysUser method call with the following script and your field name in the sys_user table to replace the <replace_field_name>.

getSysUser: function (upn) { 
if (upn) { 
            var userGr = new GlideRecord('sys_user');
            userGr.addActiveQuery(); 
            userGr.addNotNullQuery('<replace_field_name>');
            userGr.addQuery('<replace_field_name>', upn);
            userGr.setLimit(1); 
            userGr.query(); 
            if (userGr.next()) { 
                        return userGr;
             } 
               }
                 }