Getting started with Microsoft Defender for Endpoint for Android

Microsoft recently declared Microsoft Defender for Endpoint (MDE) for Android – previously known as Microsoft Defender ATP for Android – general available. That’s really good news and also a really good trigger for a new blog post. MDE for Android provides protection against phishing, unsafe network connections, and malicious apps. All events and alerts around those subjects will be available in the Microsoft Defender Security Center and will be used to determine the risk level of the device. To add-on to that, through the connection with Microsoft Intune that risk information can be used to determine the compliance of the device with the company policies and to determine the eventual access of the device to company data.

In this post I want to start with a short introduction about MDE for Android, followed by the required configurations. I’ll end this post by having a look at the experience. That means that the following will be addressed.

Note: At this moment many configurations still refer to Microsoft Defender ATP. This will change over time.

Introduction to Microsoft Defender for Endpoint for Android

Let’s start with a short introduction about MDE for Android. At this moment MDE for Android contains two key capabilities: 1) Web protection and 2) Malware scanning.

The Web protection capability relies on a local/self-looping VPN that does not take traffic outside of the device. That capability helps with addressing the challenge of phishing, by instantly blocking access to unsafe websites (coming from SMS, email, browsers and other apps). It also helps with addressing the challenge of unsafe network connections that some apps automatically make, by immediately blocking access to unsafe network connections. The key service that is leveraged for providing this functionality is Microsoft Defender SmartScreen. Besides that default functionality, an administrator can also configure custom indicators for allowing or blocking access to specific URLs and domains.

The Malware scanning capability fortifies the existing functionality of Google Play Protect and the ability to limit the installation of apps to trusted sources. That’s achieved by using cloud protection for apps and data on the device. When apps are downloaded, scans are instantly performed to detect malware of potentially unwanted applications (PUA).

In addition to those capabilities, MDE can also integrate with Microsoft Intune. That integration can provide information about the device risk to Microsoft Intune. That information about the risk level of the device can be used in a compliance policy in Microsoft Intune, to determine if a device is compliant with the company policies. That compliance state can be used in Conditional Access to determine the access of a device to company apps and data.

Integration of Microsoft Defender for Endpoint with Microsoft Intune

One of the main benefits of using MDE, is the integration with Microsoft Intune. That integration makes sure that the information about the risk level of a device, of any supported platform, can be provided to Microsoft Intune for usage in compliance policies. To achieve that integration, the following two configurations are required.

Enable Microsoft Intune connection in Microsoft Defender Security Center

The connection with Microsoft Intune should be enabled in Microsoft Defender Security Center. This is a generic configuration that is applicable to any supported platform. When this connection is already used for another platform, these actions can be ignored. To enable the Microsoft Intune connection, follow the two steps below.

  1. Open the Microsoft Defender Security Center portal and navigate to Settings Advanced features to open the Settings page for the advanced features
  2. On the Settings page, scroll down to Microsoft Intune connection (as shown in Figure 1) and switch the slider to On

Enable Android devices in Microsoft Endpoint Manager admin center

When the connection between MDE and Microsoft Intune is established, a configuration can be done per platform to use risk information that is provided via the connection. To enable that for Android, follow the two steps below.

  1. Open the Microsoft Endpoint Manager admin center portal and navigate to Endpoint security > Microsoft Defender for ATP to open the Endpoint security | Microsoft Defender ATP blade
  2. On the Endpoint security | Microsoft Defender ATP blade, navigate to the setting Connect Android devices of version 6.0.0 and above to Microsoft Defender ATP (as shown in Figure 2) and switch the slider to On

Distribution of the Microsoft Defender for Endpoint for Android app

The MDE for Android app can be distributed by using Microsoft Intune. That will help with a smoother adoption of MDE on Android devices. Distribution of that app can be achieved by following the seven steps below.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Apps > All apps > Android to open the Android | Android apps blade
  2. On the Android | Android apps blade, click Add to open the Select app type page
  3. On the Select app type page, select Managed Google Play app as App type and click Select to open the Managed Google Play page
  1. On the Managed Google Play page, search for the Microsoft Defender ATP (Enterprise) app, select the app and click Approve to open the Permissions dialog
  2. On the Permissions dialog, click Approve to open the Approval settings dialog
  3. On the Approval settings dialog, select Keep approved when app requests new permissions click Done
  4. Click Sync (as shown in Figure 3) to synchronize the approved app to Microsoft Intune

After successfully synchronizing the MDE for Android app to Microsoft Intune, assign the app to the required group of users or devices to distribute the app.

Configuration of the Microsoft Defender for Endpoint for Android app

The MDE for Android app can also be configured with a few properties to enabled or disable features and to take away some end-user interaction. The latter, however, can’t be taken away completely, which means that there is still a user interaction required. The configurations that can be achieved are enabling and disabling (a part of) the Web protection capability of MDE for Android. The permissions that can be useful are providing access to the external storage. If needed, those configurations can be achieved by following the seven steps below.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Apps App configuration profiles to open the Apps | App configuration policies blade
  2. On the Apps | App configuration policies blade, click Add > Managed devices to open the Create app configuration policy wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the app configuration policy
  • Description: (Optional) Provide a valid name for the app configuration policy
  • Device enrollment type: (Grayed out) Managed devices
  • Platform: Select Android Enterprise
  • Profile Type: Select All Profile Types, Fully Managed, Dedicated, and Corporate-Owned Work Profile Only or Personally-Owned Work Profile Only depending on the devices that should get this policy assigned
  • Targeted app: Select Microsoft Defender ATP (Enterprise)
  1. On the Settings page, (if needed) provide the following information (as shown in Figure 4) and click Next
  • Permissions
    • Click Add to add External storage (read) and External storage (write) permissions and select Auto grant with the Permission state

Note: These permissions will save the users from manually approving these permissions on their device

  • Configuration Settings
    • Configuration settings format: Select Use configuration designer
    • Click Add to add the Anti-Phishing or VPN configuration key and set the configuration value to 1 (enable) or to 0 (disable).

Note: The Anti-Phishing configuration key only works for fully managed and dedicated devices and both configuration keys influence the Web protection capability.

  1. On the Scope tags page, configure the applicable scope tags and click Next
  2. On the Assignments page, configure the assignment by selecting the applicable group and click Next
  3. On the Review + create page, review the configuration and click Create

Configuration of the device risk compliance policy for Android Enterprise devices

The device compliance policy can be used to actively take advantage of the integration between MDE and Microsoft Intune. That policy can mark a device as noncompliant when the device risk is above the configured score. Eventually, that compliance state can be used with conditional access to determine the access of a device to company apps and data. Creation of such a device compliance policy can be achieved by following the nine steps below.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices Device compliance policies to open the Compliance policies | Policies blade
  2. On the Compliance policies | Policies blade, click Create Policy to open the Create a policy page
  3. On the Create a policy page, provide the following information and click Create
  • Platform: Select Android Enterprise
  • Policy type: Select Fully managed, dedicated, and corporate-owned work profile or Personally-owned with work profile depending on the devices that should get this policy assigned
  1. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the device compliance policy
  • Description: (Optional) Provide a valid name for the device compliance policy
  1. On the Compliance settings page, navigate to the Microsoft Defender ATP section, select the risk score with Require the device to be at or under the machine risk score (see also Figure 5) and click Next
  1. On the Actions for noncompliance page, leave the default configuration of Action on Mark device noncompliant with Schedule (days after noncompliance) on Immediately and click Next
  2. On the Scope tags page, configure the applicable scope tags and click Next
  3. On the Assignments page, configure the assignment by selecting the applicable group and click Next
  4. On the Review + create page, review the configuration and click Create

Note: Configure a conditional access policy that requires a compliant device to use this compliance state for verifying access to company apps and data.

Experience with Microsoft Defender for Endpoint for Android

When the integration is configured between MDE and Microsoft Intune, the MDE for Android apps is configured and distributed and the compliance policy is in place, it’s time to look at the experience. Both, from an end-user perspective and from an administrator perspective.

End-user experience with the Microsoft Defender for Endpoint for Android app

When looking at the end-user experience, it starts with the initial start of the MDE for Android app. After the MDE for Android app is installed, users should start it the first time to get it up-and-running. This does require the user to have the correct license (Windows 10 E5/A5, Microsoft 365 E5/A5, or Microsoft 365 E5 Security). When initially starting the MDE for Android app, the user needs to agree with the license agreement and privacy statement, by clicking Get started (as shown in Figure 6). That will bring users to the the wizard that will provide the MDE for Android app with the required permissions locally on the device (see Figure 7). When using the mentioned permissions in the app configuration, the storage permissions will already be in place. Once all the permissions are provided, the MDE for Android app is up-and-running.

For testing the Web protection capability, Microsoft provides the smartscreentestratings2.net site. When navigating to that site, or any other phishing site, the user receives the “Connection blocked” message (as shown in Figure 8). That will be logged in the Microsoft Defender Security Center portal as “Informational“. Once the user ignores the message and continue to the site by clicking on Allow, the action will be logged as “Low“.

For testing the Malware scanning capability, Microsoft refers to the existing test apps in the Google Play store. Those apps simply contain an EICAR test file that should be captured by any antimalware app. For testing purposes my test user installed the first hit in the Google Play store, which is the Test Virus app. That app will immediately be caught by MDE for Android (as shown in Figure 9). When the user now checks the MDE for Android app, the device will be marked as unsafe (see Figure 10). When the user clicks on the notifications, or on the app security, they will be brought to the remediation action to uninstall the app. When the user wants to ignore that, the device will also be marked as noncompliant in Microsoft Intune (as shown in Figure 11). That will eventually block the access for the user to company data and apps. Assuming that conditional access is in place and requires a compliant device.

Note: When using MDE for Android on a device with a Work Profile (personally-owned or corporate-owned), it will only protect everything within the Work Profile.

Administrator experience

When looking at the administrator experience, I want to focus on the information that’s generated by the user. For an overview of the alerts, I’ve opened the Microsoft Defender Security Center portal and navigated to the Alerts of the device of the user. That provides the suspicious activity of visiting the test site and the malware of the test virus app. It also shows the earlier mentioned severity of the different actions.

As the user ignored the information that was provided by MDE for Android, the device will also be marked as noncompliant. For an overview of that message, I’ve opened the Microsoft Endpoint Manager admin center portal and navigate to device compliance policy settings of the compliance policy that was assigned to the user. That provides the current status of the device, based on the device risk.

More information

For more information about MDE for Android, the naming, the availability and the configuration, refer to the following docs.

Getting started with Android Enterprise Corporate-Owned devices with Work Profile

Microsoft has recently declared the Android Enterprise Corporate-Owned devices with Work Profile deployment scenario (sometimes also referred to as management scenario) feature complete. That’s really good news and also a really good trigger for a new blog post. This time I’ll skip the different deployment scenarios and use cases, as I’ve written about those here and here. Just to create a good starting point, I’ll start with a quick summary about the main characteristics of this specific deployment scenario in the table below. These characteristics will help with determining if this deployment scenario will fit on the use case. For a complete overview with the different deployment scenarios, please refer to my previous post around this subject.

Deployment scenarioUse casePersonal usePrivacy guaranteedEnrollment methodManagement reachReset requiredUser affinity
Corporate-Owned devices with Work ProfileCorporate-Owned, Personally Enabled (COPE)YesYesNear Field Communication, Token entry, QR code scanning, or Zero touchProfile owner with device-level settingsYesYes

Note: Keep in mind that the user experience will be similar to personal devices with work profile. That means a strict separation between personal apps and data and work apps and data.

Throughout this post, I want to discuss the main enrollment, configuration and distribution options for the Android Enterprise corporate-owned devices with work profile deployment scenario. I want to achieve that by going through the following subjects and touching the most important points for the different configurations. I’ll simply provide the steps to get to the correct profiles, policies and apps that are applicable to this deployment scenario. I’ll end by providing a quick overview of the end-user experience.

Enrollment profile for corporate-owned devices with work profile

The Android Enterprise corporate-owned devices with work profile deployment scenario starts with the enrollment profile, as the enrollment profile determines the deployment scenario that is used. That enrollment profile contains a unique token that does not expire. There can also be multiple enrollment profiles. Having multiple enrollment profiles can be useful for separating devices in different groups, as the enrollment profile name can be used for creating dynamic device groups. The following five steps walk through the process of creating that enrollment profile.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices Android > Android enrolment Corporate-owned devices with work profile to open the Corporate-owned devices with work profile blade
  2. On the Corporate-owned devices with work profile blade, click Create profile to open the Create a profile wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the enrollment profile for corporate-owned devices with work profile
  • Description: (Optional) Provide a valid description for the enrollment profile for corporate-owned devices with work profile
  1. On the Scope tags page, configure the required scope tags click Next
  2. On the Review + create page, verify the configuration and click Create

Note: When not using Zero-touch enrollment, or third-party services like Samsung Knox Mobile Enrollment, the easiest method for enrolling these devices is by using the created QR-code.

Device configuration profiles for corporate-owned devices with work profile

The configuration of devices in the Android Enterprise corporate-owned devices with work profile deployment scenario, is similar to most other Android Enterprise corporate-owned deployment scenarios. The different device configuration profiles can be used for configuring device features, assigning certificates or configuring Wi-Fi or VPN. To create a device configuration profile, focus on the profiles shown under the Fully Managed, Dedicated, and Coporate-Owned Work Profile category. The following three steps walk through the creation of a device configuration profile.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices Configuration profiles to open the Devices | Configuration profiles blade
  2. On the Devices | Configuration profiles blade, select Create profile to open the Create a profile page
  3. On the Create a profile page, provide the following information and click Create
  • Platform: Select Android Enterprise
  • Profile: Depending on the required configuration, select Derived credentials, Device restrictions, SCEP certificate, Trusted certificate, VPN or Wi-Fi in the Fully Managed, Dedicated, and Coporate-Owned Work Profile category

When creating a device restrictions profile, the settings are divided in different categories and in every category there a different headers. Those headers include the applicable deployment scenarios for the settings under the header. Make sure that the header includes “corporate-owned work profile“. In most cases that’s applicable to settings that are available for all deployment scenarios, with the exception of two categories. The Work profile password category (see Figure 1) and the Personal profile category (see Figure 2). Those categories are only applicable to Android Enterprise corporate-owned devices with work profile.

Note: Keep in mind that OEMConfig can also be used for configuring the work profile of these devices, when supported by the vendor.

Device compliance policies for corporate-owned devices with work profile

The compliance of devices in the Android Enterprise corporate-owned devices with work profile deployment scenario, is also similar to most other Android Enterprise corporate-owned deployment scenarios. The device compliance policy settings that are available for the existing corporate-owned deployment scenarios, are also applicable to this deployment scenario. A device compliance policy can be used for verifying the compliance with the device risk, device health, platform version and security settings. The following three steps walk through the creation of such a device compliance policy.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices Compliance policies to open the Compliance policies| Policies blade
  2. On the Compliance policies| Policies blade, select Create policy to open the Create a policy page
  3. On the Create a policy page, provide the following information and click Create
  • Platform: Select Android Enterprise
  • Profile: Select Fully managed, dedicated, and coporate-owned work profile

Note: Even though the devices are compliant, I’m currently seeing challenges with device-based Conditional Access, as a certificate should be selected that is not available.

Apps for corporate-owned devices with work profile

The deployment of apps to devices in the Android Enterprise corporate-owned devices with work profile deployment scenario, is the same as for any other Android Enterprise corporate-owned deployment scenario. The different app types can be used for installing store apps, line-of-business apps, web links, built-in apps, and Android Enterprise system apps. The following three steps walk through the process of adding such apps.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Apps All apps to open the Apps | All apps blade
  2. On the Apps | All apps blade, click Add to open the Select app type page
  3. On the Select app type page, provide the following information and click Select
  • App type: Depending on the required app, select Managed Google Play app, Web link, Built-in app, Line-of-business app or Android Enterprise system app

Note: Even though the Android Enterprise system apps are applicable, and will be available, most of those apps can only be used by the owner of the device.

App configuration policies for corporate-owned devices with work profile

The configuration of apps for devices in the Android Enterprise corporate-owned devices with work profile deployment scenario, is the same as for any other Android Enterprise corporate-owned deployment scenario. The app configurations can be configured by using the configuration designer, or JSON data. The following three steps walk through the process of adding such app configuration policies.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Apps App configuration policies to open the Apps | App configuration policies blade
  2. On the Apps | App configuration policies blade, click Add > Managed devices to open the Create app configuration policy wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the app configuration policy
  • Description: (Optional) Provide a valid description for the app configuration policy
  • Device enrollment type: Managed devices already selected
  • Platform: Select Android Enterprise
  • Profile Type: Select Fully Managed, Dedicated and Corporate-Owned Work Profile Only
  • Targeted app: Select the app that should be configured

Note: When possible, stick with the configuration designer, as it simplifies the app configuration.

App protection policies for corporate-owned devices with work profile

The protection of (the data in) apps for devices in the Android Enterprise corporate-owned devices with work profile deployment scenario, is the same as for any other Android Enterprise deployment scenario. The app protection policies can used for creating restrictions for data transfers, requiring encryption, creating access requirement and adding conditional launch requirements. The following four steps walk through the process of adding such app protection policies.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Apps App protection policies to open the Apps | App protection policies blade
  2. On the Apps | App protection policies blade, click Create policy > Android to open the Create policy wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the app protection policy
  • Description: (Optional) Provide a valid description for the app protection policy
  • Platform: Android already selected
  1. On the Apps page, provide at least the following information and click Next
  • Target to apps on all device types: Select Yes, or select No in combination with the following setting
    • Device types: Select at least Android Enterprise
  • Public apps: Select the public apps to which this policy applies
  • Custom apps: Select the custom apps to which this policy applies

Note: Keep in mind that when managed apps are allowed without a managed devices, users can also configure a managed app in their personal container.

Remote actions for corporate-owned devices with work profile

The available remote actions for devices in the Android Enterprise corporate-owned devices with work profile deployment scenario are limited. The remote actions can be used to wipe, delete, remote lock, reset work profile passcode, or restart the device. The following two steps walk through the process of getting to the remote actions.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices All devices to open the Devices | All devices blade
  2. On the Devices | All devices blade, select a specific Android Enterprise corporate-owned device with work profile to open the device Overview

Important: Keep in mind that the Wipe action will factory reset the device and that the factory reset of the device will remove all company apps and data and all personal apps and data.

Tip: The Wipe, Delete and Restart actions can also be performed by using Bulk Device actions.

Note: This figure also provides a nice overview of the combination of a corporate-owned device (see Ownership property) and a work profile (see Reset work profile passcode action).

User experience for corporate-owned devices with work profile

Let’s end this post by having a quick look at the end-user experience for the Android Enterprise corporate-owned devices with work profile deployment scenario. The enrollment process is pretty straight forward, it does take some time, but the steps almost can’t go wrong. That’s why I want to show the user experience for the personal and work profile. Mainly focused on showing the different configuration options and the main difference with personal devices with work profile.

Below in Figure 8 is an example of the personal profile after the enrollment of the device. It doesn’t contain a Company Portal app, as it’s not needed for the enrollment of the device. Below in Figure 9 is an example of the work profile after the enrollment of the device. It does contain the Microsoft Intune app with the device compliance information and the device policy sync option. It also contains multiple apps that are distributed, configured and managed.

Note: As shown in Figure 9, the work profile of my users also contains the Microsoft Tunnel app and I can confirm that Microsoft Tunnel Gateway is also working for my users.

More information

For more information regarding Android Enterprise Corporate-Owned Work Profile, refer to the following articles:

Android Enterprise corporate-owned dedicated devices and Azure AD shared device mode

This week is all around the Android Enterprise corporate-owned dedicated devices deployment scenario. That deployment scenario is designed to address the typical kiosk-type devices, which are often referred to as the corporate-owned, single-use (COSU) use case. This week is specifically focused on enrolling those devices in to Azure AD shared device mode. That mode will provide users with a single sign-on and single sign-out experience across all of the participating apps on the device. In other words, users will be able to sign in to the device and will automatically be signed in to any participating apps. That enables an organization to provide a little personalized experience across dedicated devices that are shared between multiple users. In this post I’ll have a look at the main configurations that are required for creating that experience and I’ll end by having a quick look at the created experience.

Important: At the moment of writing, this is still preview functionality and the participating apps are currently the Microsoft Teams and the Managed Home Screen app.

Enrollment profile for corporate-owned dedicated devices with Azure AD shared device mode

The first main configuration that is required, is the configuration of the enrollment profile for the corporate-owned dedicated devices. That’s not the most exiting configuration, but it contains an important configuration to trigger the enrollment in to the Azure AD shared device mode. That configuration is the toke type that should be configured. The following five steps walk through the process of creating an enrollment profile for corporate-owned dedicated devices with Azure AD shared device mode.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices Android > Android enrolment > Corporate-owned dedicated devices to open the Corporate-owned dedicated devices blade
  2. On the Corporate-owned dedicated devices blade, click Create profile to open the Create a profile wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the enrollment profile
  • Description: (Optional) Provide a valid description for the enrollment profile
  • Token type: Select Corporate-owned dedicated device with Azure AD shared mode
  • Token expiration date: (Optional) Select a valid date for the token expiration
  1. On the Scope tags page, configure the required scope tags click Next
  2. On the Review + create page, verify the configuration and click Create

Device configuration profile for corporate-owned dedicated devices

The second important configuration, is the configuration of the device configuration profile. It’s not a completely required step, but that’s the easiest method for performing a few basic configurations for a corporate-owned dedicated device. Even for a multi-app kiosk mode. The following eight steps walk through the creation of a device configuration profile that can be used for creating a multi-app kiosk mode.

Important: When creating a multi-app kiosk, keep in mind that the Managed Home Screen app is required for creating a multi-app kiosk experience.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices Android > Configuration profiles to open the Android | Configuration profiles blade
  2. On the Android | Configuration profiles blade, click Create profile to open the Create a profile page
  3. On the Create a profile page, provide the following information and click Create to open the Device restrictions wizard
  • Platform: Select Android Enterprise
  • Profile type: Select Device restrictions
  1. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the device restriction profile
  • Description: (Optional) Provide a valid name for the device restriction profile
  1. On the Configuration settings page, provide at least the following information and click Next
  • Navigate to section Device experience
    • Enrollment profile type: Select Dedicated device
    • Kiosk mode: Select Multi-app

Note: The mentioned settings are only the settings to create a minimal multi-app kiosk device. Make sure to further configure any required setting for the multi-app kiosk device. That includes any further limitations, or any apps, for the multi-app kiosk mode, in this section of the configuration, but that also includes any other configurations in the other sections of the device configuration profile.

  1. On the Scope tags page, configure the required scope tags click Next
  2. On the Assignments page, configure the assignment to the required devices and click Next
  3. On the Review + create page, verify the configuration and click Create

Note: For the assignment of the device configuration profile, a dynamic device group can be used that only contains corporate-owned dedicated devices with Azure AD shared device mode by using the enrollmentProfileName property. That dynamic device group can be used for every assignment for this specific scenario.

App configuration policy for Managed Home Screen app

The third important configuration, is the configuration of the app configuration policy for the Managed Home Screen app. It’s a required step – at this moment – to configure the Azure AD sign-in experience to the corporate-owned dedicated device. That can be achieved by performing app configurations on the Managed Home Screen app, which are currently not available by using the previously described device configuration profile. The following seven steps walk through the creation of an app configuration profile that can be used for further configuring the multi-app kiosk mode.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Apps App configuration profiles to open the Apps | App configuration policies blade
  2. On the Apps | App configuration policies blade, click Add > Managed devices to open the Create app configuration policy wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the app configuration policy
  • Description: (Optional) Provide a valid name for the app configuration policy
  • Device enrollment type: (Grayed out) Managed devices
  • Platform: Select Android Enterprise
  • Profile Type: Select Fully Managed, Dedicated, and Corporate-Owned Work Profile Only
  • Targeted app: Select Managed Home Screen
  1. On the Settings page, provide at least the following information and click Next
  • Configuration settings format: Select Use configuration designer
  • Click Add to add at least the keys and values as described in the table below to create a sign-in and sign-out experience for Azure AD accounts on the dedicated device.

Note: Most of the other keys and values can be configured by using the device configuration profile. Together with these new keys and values a few more new keys and values are introduced for configuring a sign-in wallpaper, custom privacy statement, session PIN and more. These keys and values are shown when using the configuration designer.

Configuration keyValue typeConfiguration valueDescription
Enable sign inbooltrue Enable sign-in to dedicated device
Sign in typestringAADConfigure AAD account sign-in when sign-in is enabled
Enable Auto Sign-outbooltrueEnable auto sign-out of dedicated device
Auto Sign-out timeinteger300Time (in seconds) until auto sign-out is determined when auto sign-out is enabled
Count down time on auto Sign-out dialoginteger60Time (in seconds) until sign on auto sign-out dialog is shown when auto sign-out is enabled
  1. On the Scope tags page, configure the required scope tags click Next
  2. On the Assignments page, configure the assignment to the required devices and click Next
  3. On the Review + create page, verify the configuration and click Create

Note: At some point in time, I expect that this configuration will become available in the device restrictions profile for dedicated devices with a multi-app kiosk.

End-user experience for corporate-owned dedicated devices with Azure AD shared device mode

Now let’s end this post by having a quick look at the end-user experience. Below are a few examples of the created behavior. When the users get their device at the beginning of their shift, they can sign in to the device (as shown in Figure 4). After sign-in, the users receive an awesome single sign-on experience with any participating app. At this moment that includes Microsoft Teams and the experience is as smooth as advertised. Can’t wait for more apps to follow. After the users become inactive on their device, the auto sign-out timer will start and will eventually show a countdown timer in a dialog box (as shown in Figure 5). At the end of their shift the users also always have the ability to sign-out manually by using the account section of the Managed Home Screen app (as shown in Figure 6). That will completely sign off the user of the device and the participating apps. As shown throughout the different figures, the look-and-feel can be completely customized.

Note: The Microsoft Intune app and the Microsoft Authenticator app are automatically installed during enrollment of a dedicated device with Azure AD shared device mode.

More information

For more information about Android Enterprise corporate-owned dedicated devices and Azure AD shared device mode, refer to the following docs.

Opting out of safeguard holds

This week is all about safeguard holds. More specifically, the ability of opting out of safeguard holds. Safeguard holds prevents devices with a known compatibility issue from being offered a new Windows 10 feature update by using Windows Update. That protects the device and user from a failed or poor experience with the Windows 10 feature update. Starting with the October 2020 security update, devices running Windows 10, version 1809 and above, receive a new setting that can be used for opting out of safeguard holds. In this post I’ll start with an introduction to safeguard holds, followed with the steps of creating a device configuration profile for opting out of safeguard holds.

Important: Opting out of a safeguard hold can put devices at risk from known performance issues.

Introduction to safeguard holds

Safeguard holds prevents devices with a known compatibility issue from being offered a new Windows 10 feature update by using Windows update. Microsoft uses quality and compatibility diagnostic data to identify issues that might cause a Windows 10 feature update to fail or roll back. When such an issue is found, a hold can be applied to Windows Update. That hold is the safeguard hold and that hold will prevent affected devices from installing the Windows 10 feature update by using Windows Update. That will protect those devices from a failed or poor performance experience. In other words, safeguard holds prevent devices with a known compatibility issue from being offered a new Windows 10 feature update. All to ensure a good experience for the users.

A safeguard hold will be released once the issue is fixed and the quality and compatibility diagnostic data confirms it. Once a safeguard hold is released, Windows Update will resume with offering the Windows 10 feature update to the affected devices. This also means that safeguard holds only affect devices that use Windows Update (for Business). Feature updates that are delivered via other channels, like an installation media, or Windows Server Update Services (WSUS), are not affected by safeguard holds.

For administrators it was already possible to use Update Compliance to see which devices are unable to install a new Windows 10 feature update due to safeguard holds. However, administrators did not have information on which particular hold was preventing the device from installing the Windows 10 feature update. That has changed. Update Compliance now contains queries to help administrators to retrieve the data related to the specific safeguard holds.

Configuration of opting out of safeguard holds

Before looking at the configurations for opting out of safeguard holds, keep in mind that the preferred path for validating new feature updates is the Windows Insider Program for Business Release Preview Channel. When that’s not an option (or was not an option), only opt out of safeguard holds for validation purposes. Don’t use it as a method to bring users to the new Windows 10 feature update. The hold is applied for a reason.

For opting out of safeguard holds, Microsoft has introduced a new ADMX-backed policy setting as part of the Update policies in the Policy CSP. That newly introduced ADMX-backed policy setting is DisableWUfBSafeguards and that policy setting can be configured to two different values that are further described in the table below.

PolicyDescription
DisableWUfBSafeguardsThis policy setting can be used for opting out of safeguard holds and is an ADMX-backed policy setting. The value for this policy setting is 0 and enables the safeguard hold functionality. The alternative value for this policy setting is 1 and is used for opting out of any safeguard holds.

To apply the DisableWUfBSafeguards setting, a custom device configuration profile can be used. The following 9 steps walk through the required steps to create that custom device configuration profile, with that policy setting.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices Windows > Configuration profiles to open the Windows | Configuration profiles blade
  2. On the Windows | Configuration profiles blade, click Create profile to open the Create a profile page
  3. On the Create a profile page, provide the following information and click Create to open the Custom wizard
  • Platform: Windows 10 and later
  • Profile type: Custom
  1. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the custom device configuration profile
  • Description: (Optional) Provide a valid description for the custom device configuration profile
  1. On the Configuration settings page, click Add to open the Add Row page. On the Add Row page, provide the following information and click Add (and click Next back on the Configuration settings page)
  • Name: Provide a valid name for the OMA-URI setting
  • Description: (Optional) Provide a valid description for the OMA-URI setting
  • OMA-URI: ./Vendor/MSFT/Policy/Config/Update/DisableWUfBSafeguards
  • Data type: Select Integer
  • Value: 1
  1. On the Scope tags page, configure the required scope tags click Next
  2. On the Assignments page, configure the assignment to the required users and/or devices and click Next
  3. On the Applicability rules page, configure the applicability rules (think about the existence of this setting for only the Pro, BusinessEnterprise and Education edition and the existence of this setting for only the 1809 version and later) and click Next
  4. On the Review + create page, verify the configuration and click Create

Note: At some point in time this configuration will probably become available in the Microsoft Endpoint Manager admin center portal without the requirement of creating a custom device configuration profile.

After applying the custom device configuration profile for opting out of safeguard holds, there is not a real difference in end-user experience to show. So, to verify the results, look at the familiar places for verifying configurations. The most common are shown below. The Advanced Diagnostic Report, the Registry and the Event Viewer. For convenience, I’ve marked the different values to look at and how those locations are related.

Note: After installing a new Windows 10 feature update, the value of this policy will revert to Not configured.

More information

For more information about (opting out of) safeguard holds, refer to the following docs.

Easily configuring the Microsoft Enterprise SSO plug-in for Apple devices

This week is all about the Microsoft Enterprise SSO plug-in for Apple devices. Both, iOS/iPadOS and macOS devices. That plug-in provides single sign-on (SSO) for Azure AD accounts across all apps that support the enterprise SSO feature of Apple. The plug-in is provided on iOS/iPadOS devices as an extension of the Microsoft Authenticator app and the plug-in is provided on macOS devices as an extension of the Company Portal app. The extensions can be enabled by using Microsoft Intune. In this post I’ll start with having a look at the configuration options, followed with the configuration steps. I’ll end this post by having a look at the end-user experience.

Important: Keep in mind that, at the moment of writing, this is still preview functionality.

Configuration options for the Microsoft Enterprise SSO plug-in

Let’s start by having a look at the configuration options for the Microsoft Enterprise SSO plug-in. The Microsoft Enterprise SSO plug-in, is a redirect-type SSO app extension. That plug-in provides SSO for Azure AD accounts across all apps that support the enterprise SSO feature of Apple and that authenticate via Azure AD. That includes accessing websites via supported browsers. In those cases, the SSO plug-in acts as an advanced authentication broker. The SSO plug-in is provided on iOS/iPadOS devices as an extension of the Microsoft Authenticator app and the SSO plug-in is provided on macOS devices as an extension of the Company Portal app. Configuring the SSO app extension will enable the SSO plug-in. The redirect SSO app extension configuration, for iOS/iPadOS and macOS devices, is provided in the table below.

PropertyiOS/iPadOSmacOS
TypeRedirectRedirect
Extension identifiercom.microsoft.azureauthenticator.ssoextensioncom.microsoft.CompanyPortalMac.ssoextension
Team identifierSGGM6D27TKUBF8T346G9
URLshttps://login.microsoftonline.comhttps://login.microsoftonline.com
https://login.microsoft.comhttps://login.microsoft.com
https://sts.windows.nethttps://sts.windows.net
https://login.partner.microsoftonline.cnhttps://login.partner.microsoftonline.cn
https://login.chinacloudapi.cnhttps://login.chinacloudapi.cn
https://login.microsoftonline.dehttps://login.microsoftonline.de
https://login.microsoftonline.ushttps://login.microsoftonline.us
https://login-us.microsoftonline.comhttps://login-us.microsoftonline.com

Note: The information in the table above is taken from a configured iPadOS device (Settings > General > Device Management > Management Profile > More Details > Authenticator) and a configured macOS device (System Preferences > Profiles > Extensible Single Sign On Profile – {GUID}). Those devices were configured by using the configuration steps provided in this post.

This all means that, to use the SSO app extension, an administrator should make sure that the correct app is installed and that the correct configuration is applied. That configuration can only be applied when the device is managed. Once the correct app is installed and the SSO app extension is configured, users can enter their credentials to sign in, and establish a session on their Apple device. That session is then used across the different supported apps, on their Apple device, without requiring users to authenticate again.

Note: Make sure to use the latest version of the Microsoft Authenticator app (iOS/iPadOS) and the latest version of the Company Portal app (macOS).

In addition to the default behavior, there are additional configuration options available to extend the SSO functionality to additional apps. Those settings are described in the table below and are recommended.

KeyTypeValueDescription
browser_sso_interaction_enabledInteger1This key and value enables non-MSAL apps and Safari browser to do the initial bootstrapping and get a shared credential.
disable_explicit_app_promptInteger1This key and value restricts ability of both native and web applications to force an end-user prompt on the protocol layer and bypass SSO.

Configuring the Microsoft Enterprise SSO plug-in

Once the configuration options and requirements are clear, it’s time to look at the configuration of the Microsoft Enterprise SSO plug-in. The configuration for iOS/iPadOS and macOS devices is identical. Only the platform is different. That platform difference will make sure that the correct configuration is applied to the correct app. The following eight steps walk through the steps to configure the Microsoft Enterprise SSO plug-in.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices Configuration profiles to open the Devices | Configuration profiles blade
  2. On the Devices | Configuration profiles blade, select Create profile to open the Create a profile page
  3. On the Create a profile page, provide the following information and click Create
  • Platform: Depending on the platform of choice select iOS/iPadOS or macOS
  • Profile: Select Device features
  1. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the device features profile
  • Description: (Optional) Provide a valid description for the device features profile
  1. On the Configuration settings page, configure at least the Single sign-on app extension section by providing the following information (see Figure 1 for an example configurations for iOS/iPadOS and see Figure 2 for an example configurations for and macOS) and click Next
  • SSO app extension type: Select Microsoft Azure AD
  • Enable shared device mode: Select Not configured
  • App bundle IDs: Add the bundle identifiers of any additional app that should use the Microsoft Azure AD single sign-on extension and that doesn’t use the (latest) Microsoft libraries
  • Additional configuration: Configure the earlier mentioned key-value pairs
    • Key: browser_sso_interaction_enabled; Type: Integer; Value: 1
    • Key: disable_explicit_app_prompt; Type: Integer; Value: 1

Note: When the earlier described configuration is not sufficient, because more URLs are required, configure a SSO app extension type of Redirect, start with providing the described configuration and add the additional URLs.

  1. On the Scope tags page, configure the required scope tags click Next
  2. On the Assignments page, configure the assignment to the required users and/or devices and click Next
  3. On the Review + create page, verify the configuration and click Create

End-user experience with the Microsoft Enterprise SSO plug-in

Now let’s end by having a look at the end-user experience with a configured Microsoft Enterprise SSO plug-in. To create the best picture, I’ve used a Safari browser on a macOS device and the experience was awesome. That experience is shown below, in Figure 3, by navigating to portal.office.com and simply picking the required account.

Note: The end-user experience is identical on iOS/iPadOS devices.

More information

For more information about the Microsoft Enterprise SSO plug-in and configuring device features on iOS/iPadOS and macOS devices, refer to the following docs.

Getting familiar with Microsoft Tunnel Gateway

This week is a follow-up on my post of a few weeks ago about getting started with Microsoft Tunnel Gateway. In that post I’ve showed how to get started with Microsoft Tunnel Gateway and in this post I want to show how to get more familiar with Microsoft Tunnel Gateway. Getting to know the installation location, getting to know the configuration files, getting to know the log files and getting to know a few important commands for more information. All of that will eventually help with getting more familiar with Microsoft Tunnel Gateway. In this post I’ll look a few directories, files, logs and commands. Also in that order.

Directories

Let’s start with a few directories. Actually, one directory and a few sub-directories. After the installation of Microsoft Tunnel Gateway, a few important directories become available. Below are the most important directories, including a short description.

DirectoryDirectory description
/etc/mstunnelThis is the root directory that contains the configuration.
/etc/mstunnel/certsThis is the directory that contains the TLS certificate.
/etc/mstunnel/privateThis is the directory that contains the Intune Agent certificate and the TLS private key.

Tip: When navigating to the root directory, a simple ls command will show all the available directories. Keep in mind that the permissions will be denied for a normal user and that the usage of sudo is required.

Files

Within the mentioned root directory, many files are added during the different stages of the installation of Microsoft Tunnel Gateway. Below are the most important files, including a short description and an example.

FileFile description
AgentSettings.jsonThis file contains the generic server configuration information (name, site, and more).
admin-settings.jsonThis file contains the configuration as configured in the Server configuration in Intune.
agent-info.jsonThis file contains the agent information (Intune tenant Id, Azure AD tenant Id, and more).
Images_configuredThis file contains the hash values of the current images.
ocserv-sec.jsonThis file contains the VPN server configuration information.
ocserv.confThis file contains the VPN server configuration.
oidc.jsonThis file contains the OpenID configuration.
version-info.jsonThis file contains the version information (configuration version, docker version, and more).
env.shThis file contains the environment variables (like the proxy addresses) when used.

Tip: When looking at the files in the directory, a simple cat command will print the content in the terminal. Keep in mind that the permissions will be denied for a normal user and that the usage of sudo is required.

Note: AgentLoggingInfo.json, AgentMonitorLoggingInfo.json, GeneralLoggingInfo.json, JournalLoggingInfo.json, OcservErrorLoggingInfo.json, OcservLoggingInfo.json and VpnLoggingInfo.json only contain the last processed logs date and mstunnel-agent-state and mstunnel-server-state only contains the status of the service.

AgentSetting.json

The AgentSettings.json shows the generic server properties. That includes the id of the site that the server belongs to, the name of the server, the id of the server and the id of the configurations that is applied to the server. Below is an example of an AgentSettings.json file.

{
	"SiteId":"n0tm1n3-da01-4633-9ad4-82bf34a93ab4",
	"ServerName":"cldmtg01",
	"ServerId":"n0tm1n3-3d69-4d8f-bdc0-e0c0e929bb6c",
	"ConfigId":"n0tm1n3-5c3c-43a9-8324-deb553da795b",
	"ServerImageTime":"2020-10-13T20:18:26.2199173+00:00",
	"AgentImageTime":"2020-10-13T20:18:26.1972649+00:00",
	"PatchExpirationDate":"0001-01-01T00:00:00+00:00"
}

admin-settings.json

The admin-settings.json shows the configured properties of the Server configuration. This file should only be adjusted by using Intune and not manually. Below is an example of an agent-settings.json file.

{
  "DisplayName": "Default server configuration",
  "Network": "192.168.50.1/24",
  "DNSServers": [
    "192.168.20.1"
  ],
  "DefaultDomainSuffix": "",
  "RoutesInclude": [],
  "RoutesExclude": [],
  "ListenPort": 443,
  "ConfigVersion": 637370578342241628,
  "SplitDNS": [],
  "AditionalSettings": []
}

agent-info.json

The agent-info.json shows the basic agent properties. That includes the id of the agent, the id of the Intune tenant that the server belongs to, the id of the Azure AD tenant that the server belongs to and the certificate information. Below is an example of an agent-info.json file.

{
  "AgentId": "n0tm1n3-09ff-4e0b-8c0b-0e1b7d6cb5fb",
  "IntuneTenantId": "n0tm1n3-8b8f-428c-a3f6-774ec1f94b6d",
  "AADTenantId": "n0tm1n3-1ce1-41db-8aff-4c59298d4ba9",
  "Type": 8,
  "Certificate": null,
  "RenewalDate": "2021-08-20T10:34:01+00:00"
}

Images_configured

The Images_configured show the hash values of the installed images. That information can be used to identify the version of the installed images. Below is an example of an Images_configured file.

mst_use_custom_image=""
agentImageDigest="sha256:3d888864ecafa1d8c05754e3059519a2cf0d4ca56a234e13f60431cff9ba152b"
serverImageDigest="sha256:525f329010088bd4a27e930e613635dc3cbcadd0611011c6d5d8f5e1d087cb41"

ocserv-sec.json

The ocserv-sec.json shows the VPN server properties. That includes the authentication configuration that is used and the certificate configuration that is used. Below is an example of an ocserv-sec.json file.

{
  "StatsReportTime": 60,
  "StatsResetTime": 3600,
  "MaxClients": 5500,
  "RateLimit": 100,
  "KeepAlive": 32400,
  "AuthTimeout": 40,
  "MinReauthTime": 300,
  "Auth": "oidc[config=/etc/ocserv/oidc.json]",
  "CertPath": "/etc/ocserv/certs/site.crt",
  "KeyPath": "/etc/ocserv/private/site.key",
  "PinPath": null,
  "UseOcctl": true,
  "Rekey": "ssl",
  "PidFile": "/var/run/ocserv.pid",
  "SockeFile": "/var/run/ocserv-socket",
  "RunAsUser": "nobody",
  "RunAsGroup": "nogroup",
  "IsolateWorkers": true,
  "Device": "ma-tun",
  "CookieTimeout": 300,
  "PersistentCookies": true,
  "MobileDpd": 1800,
  "Dpd": 240,
  "TryMtuDiscovery": true,
  "TlsPriorities": "Secure256:-CIPHER-ALL:\u002BAES-256-GCM:-KX-ALL:\u002BECDHE-RSA:-MAC-ALL:\u002BAEAD:-VERS-TLS-ALL:\u002BVERS-TLS1.3:\u002BVERS-TLS1.2:-COMP-ALL",
  "MatchTlsDtlsCiphers": true,
  "DtlsLegacy": false,
  "ConnectScript": "/usr/local/sbin/ocserv-telemetry.sh",
  "DisconnectScript": "/usr/local/sbin/ocserv-telemetry.sh",
  "ServerDrainMs": 15000
}

ocserv.conf

The ocserv.conf shows the VPN server configuration. That includes the network configuration, the authentication configuration and the certificates that are used. Below is an example of an ocserv.conf file.

ipv4-network = 192.168.50.1/24
dns = 192.168.20.1
route = default
tcp-port = 443
udp-port = 443
server-stats-reset-time = 3600
max-clients = 5500
rate-limit-ms = 100
auth = oidc[config=/etc/ocserv/oidc.json]
server-cert = /etc/ocserv/certs/site.crt
server-key = /etc/ocserv/private/site.key
use-occtl = True
rekey-method = ssl
pid-file = /var/run/ocserv.pid
socket-file = /var/run/ocserv-socket
run-as-user = nobody
run-as-group = nogroup
isolate-workers = True
device = ma-tun
cookie-timeout = 300
persistent-cookies = True
mobile-dpd = 1800
dpd = 240
try-mtu-discovery = True
tls-priorities = Secure256:-CIPHER-ALL:+AES-256-GCM:-KX-ALL:+ECDHE-RSA:-MAC-ALL:+AEAD:-VERS-TLS-ALL:+VERS-TLS1.3:+VERS-TLS1.2:-COMP-ALL
match-tls-dtls-ciphers = True
dtls-legacy = False
connect-script = /usr/local/sbin/ocserv-telemetry.sh
disconnect-script = /usr/local/sbin/ocserv-telemetry.sh
server-drain-ms = 15000

oidc.json

The oidc.json shows the OpenID properties. That includes the sts-url that is used and the issuer. Below is an example of the oidc.json file.

{
  "openid_configuration_url": "https://sts.windows.net/n0tm1n3-1ce1-41db-8aff-4c59298d4ba9/v2.0/.well-known/openid-configuration",
  "user_name_claim": "oid",
  "required_claims": {
    "aud": "n0tm1n3-9681-447a-974d-d19f668fcd88",
    "acct": 0,
    "iss": "https://sts.windows.net/n0tm1n3-1ce1-41db-8aff-4c59298d4ba9/"
  }
}

version-info.json

The version-info.json shows the version information of the different components. That includes, the version of the configuration, the version of Docker, the version of the different images and the version of the operating system. Below is an example of the version-info.json file.

{
    "ConfigVersion": 637370578342241628,
    "DockerVersion": "Docker version 19.03.13, build 4484c46d9d",
    "AgentImageHash": "sha256:3d888864ecafa1d8c05754e3059519a2cf0d4ca56a234e13f60431cff9ba152b",
    "AgentCreateDate": "2020-10-09T18:50:54.560584825Z",
    "ServerImageHash": "sha256:525f329010088bd4a27e930e613635dc3cbcadd0611011c6d5d8f5e1d087cb41",
    "ServerCreateDate": "2020-10-09T18:49:24.487117764Z",
    "HostOS": "Ubuntu 20.04.1 LTS",
    "HostKernel":"5.4.0-48-generic"
}

Commands

When looking at the different commands that are available for basic interaction with Microsoft Tunnel Gateway, locally on the Linux server, journalctl is important for querying the journal (the place for logs) and mst-cli is important for actually interacting with Microsoft Tunnel Gateway.

Logs

With the latest update of Microsoft Tunnel Gateway, the logs are logged in the Linux server logs in the syslog format. That also means that the standard journalctl command can be used view the journal (the logs) and that the -t parameter can be used for showing entries with only the specific identifier. When looking at the Microsoft Tunnel Gateway log entries, the identifiers in the table below are important.

IdentifierIdentifier description
ocservThis identifier only displays the VPN server logs.
mstunnel-agentThis identifier only displays the Intune agent logs.
mstunnel_monitorThis identifier only displays the monitoring task logs.

An example for using journalctl for displaying the Intune agent logs, can be found below.

journalctl -t mstunnel_monitor

Tip: When looking at the logs, the -f parameter will follow the log and display a rolling log. For more an overview of all the available parameters, use the -h parameter.

Interface

For local interaction with Microsoft Tunnel Gateway, Microsoft provides the mst-cli command-line tool. This command-line tool is available on the Linux server after the installation of Microsoft Tunnel Gateway and can be found at /usr/sbin/mst-cli. This command-line tool can be used to get some basic interaction with Microsoft Tunnel Gateway, like getting information, restarting the service and server and even uninstalling Microsoft Tunnel Gateway.

Note: Keep in mind that when running the mst-cli command-line tool, the usage of sudo is required.

When looking at the mst-cli command-line tool, the following commands are the first layer of local interaction capabilities with Microsoft Tunnel Gateway.

CommandCommand description
agentOperate commands on the agent component (use the -h command for more command options).
serverOperate commands on the server component (use the -h command for more command options).
uninstallUninstall Microsoft Tunnel Gateway.
eulaShow the EULA that was accepted during the installation of Microsoft Tunnel Gateway.
import_certImport the TLS certificate.

An example for using mst-cli, can be found below. This example will show the accepted EULA.

sudo /usr/sbin/mst-cli eula

Important: Be careful with the uninstall parameter of the mst-cli command-line tool, because at this moment the uninstall will start immediately without verification.

agent parameter

When looking at the agent command, the following commands are the options for interacting with the agent component.

CommandCommand description
statusShows the status of the agent component.
startStart the service of the agent component.
stopStop the service of the agent component.
restartRestart the service of the agent component.

An example for using mst-cli agent, can be found below. This example will show the status of the agent component.

sudo /usr/sbin/mst-cli agent status

server parameter

When looking at the server command, the following commands are options for interacting with the server component.

CommandCommand description
statusShows the status of the server component.
startStart the service of the server component.
stopStop the service of the server component.
restartRestart the service of the server component.
showShow various stats of the server component (use the -h command for more command options). This command can show a lot of stats, including the statistics of the server and the connected users.

An example for using mst-cli server, can be found below. This example will show the status of the server component.

sudo /usr/sbin/mst-cli server status

Tip: For an overview of all the available commands use sudo /usr/sbin/mst-cli -h. For an overview of the available commands for a specific component use something similar to sudo /usr/sbin/mst-cli server show -h.

More information

For more information about the further details about Microsoft Tunnel Gateway, refer to the following docs.

Easily exporting Intune reports using Microsoft Graph

This week a short blog post about Intune reports and more specifically about exporting Intune reports by using Microsoft Graph. Since recently, all reports that are available in the (new) Intune reporting infrastructure are available for export. That export can be achieved from a single top-level export API. Simply use Microsoft Graph API to make the required HTTP call(s). The result of the HTTP call(s) will be a downloadable ZIP-file that contains a CSV-file. That CSV-file contains an export of the latest real-time information and can be imported in EXCEL for some simple data analyses, or in Power BI for more advanced data analyses and visualizations. In this post I’ll show how to use Microsoft Graph to export Intune reports and I’ll show the results of the export.

Export Intune reports

Let’s start with the easiest part, which is knowing the correct Microsoft Graph API endpoint. That’s the endpoint below.

https://graph.microsoft.com/beta/deviceManagement/reports/exportJobs

The more challenging part is the parameters that can be submitted in the request body. Basically there are the following three main parameters that can be submitted in the request body to define the export request:

  • reportName: This is a required parameter (type String) that contains the name of the report that should be exported.
  • filter: This is an optional parameter, for most reports, (type String) that can be used to filter the dataset.
  • select: This is an optional parameter (type String collection) that can be used to select specific columns of the dataset. When nothing is specified, a default set of columns, which for most reports is the entire dataset, is selected.

Note: The documentation about exporting reports provides information about the available reports, the name of the reports, the information that can be used to filter the data and the properties that can be used to select specific columns of the data.

Now when making the request, the reportName parameter must be provided as part of the request body. That parameter contains the name of the report that should be exported. Below is an example of an export request for the Devices report that filters on specific data and only selects specific columns. That example can be used in a HTTP POST method on the request. The HTTP POST method is used to perform an action to export the report. A simple method to perform this action is by using Microsoft Graph Explorer. In Graph Explorer, simply select POST, provide the mentioned endpoint as URL, provide the example below as request body and click Run query.

{
    "reportName": "Devices",
    "filter": "(ManagementAgents eq '2') and (OwnerType eq '1')",
    "select": [
        "DeviceName",
	"DeviceType",
	"Ownership",
        "ManagedBy",
        "managementState",
        "complianceState",
        "OS",
        "OSVersion",
        "LastContact",
        "UPN"
    ],
    "localization": "true",
    "ColumnName": "ui"
}

Note: In most cases I would suggest to not filter the data. I only used a filter to show how it works. A tool like Power BI can be used to actually filter the data and to create some nice data analyses and visualizations. Not filtering the data, when exporting the data, leaves more room for a good interpretation of the data.

After posting the provided HTTP POST method on the request, Microsoft Graph returns a response message. That response message contains the information that was provided in the request and the id and status of the request. Especially the id is important, as that id should be used to follow the status of the request.

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#deviceManagement/reports/exportJobs/$entity",
    "id": "Devices_115d909a-7574-4e94-b236-e6e082ab6788",
    "reportName": "Devices",
    "filter": "(ManagementAgents eq '2') and (OwnerType eq '1')",
    "select": [
        "DeviceName",
        "DeviceType",
        "Ownership",
        "ManagedBy",
        "managementState",
        "complianceState",
        "OS",
        "OSVersion",
        "LastContact",
        "UPN"
    ],
    "format": "csv",
    "snapshotId": null,
    "status": "notStarted",
    "url": null,
    "requestDateTime": "2020-10-07T09:42:06.388268Z",
    "expirationDateTime": "0001-01-01T00:00:00Z"
}

To follow the status of the export request, the id can be used to query for an updated status. In Graph Explorer, simply select Get, provide something similar to the example below (just adjust the provided id) as the URL and click Run query.

https://graph.microsoft.com/beta/deviceManagement/reports/exportJobs('Devices_115d909a-7574-4e94-b236-e6e082ab6788')

Once the status of the export request changes to completed, the url in the response will contain a link to a downloadable ZIP-file in a storage blob.

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#deviceManagement/reports/exportJobs/$entity",
    "id": "Devices_115d909a-7574-4e94-b236-e6e082ab6788",
    "reportName": "Devices",
    "filter": "(ManagementAgents eq '2') and (OwnerType eq '1')",
    "select": [
        "DeviceName",
        "DeviceType",
        "Ownership",
        "ManagedBy",
        "managementState",
        "complianceState",
        "OS",
        "OSVersion",
        "LastContact",
        "UPN"
    ],
    "format": "csv",
    "snapshotId": null,
    "status": "completed",
    "url": "https://amsub0201repexpstorage.blob.core.windows.net/a3283525-8b8f-428c-a3f6-774ec1f94b6d/Devices_115d909a-7574-4e94-b236-e6e082ab6788.zip?sv=2019-02-02&sr=b&sig=Rm301BTLjYTEmTNl7WHk1UL2bu6TKYIhezlpH8lzveU%3D&skoid=1db6df02-4c8b-4cb3-8394-7ac2390642f8&sktid=72f988bf-86f1-41af-91ab-2d7cd011db47&skt=2020-10-07T09%3A43%3A10Z&ske=2020-10-07T15%3A42%3A52Z&sks=b&skv=2019-02-02&se=2020-10-07T15%3A42%3A52Z&sp=r",
    "requestDateTime": "2020-10-07T09:42:06.388268Z",
    "expirationDateTime": "2020-10-07T15:42:52.0376315Z"
}

Intune reports result

The downloaded ZIP-file has the name of the id of the generated report. That ZIP-file contains a CSV-file and that also has the name of the id of the generated report. After exporting the CSV-file, the data can be imported in anyone’s favorite tool. That can be as simple as EXCEL, or a bit more advanced as Power BI. Especially the latter provides some real (simple) capabilities to transform this data into a report. Below are some examples. Figure 1 provides a quick overview of the exported data in a table format.

Figure 2 also provides a quick overview of a similar exported dataset in a table format, but in this case without the filtering of the data. The main goal is to show my earlier note, which will be even clearer with the next figure.

Figure 3 provides an overview of a visualization of both datasets. The main goal is to show that the non-filtered dataset provides a lot more flexibility when analyzing the data. The totally green pie charts are the filtered dataset and the colored pie charts are the non-filtered datasets.

More information

For more information about exporting Intune reports by using Graph APIs, refer to the following docs:

Getting started with Microsoft Tunnel Gateway

This week is all about the just, during Microsoft Ignite 2020, released Microsoft Tunnel Gateway (often referred to as Microsoft Tunnel or Tunnel). Microsoft Tunnel Gateway is a new solution that can provide iOS and Android devices with access to on-premises resources. In other words, Microsoft Tunnel Gateway is a VPN solution. The best part of Microsoft Tunnel Gateway is that it fully integrates with a Microsoft 365 solution and that it’s included in the existing Microsoft Intune license. That integration is also one of the strongest points of Microsoft Tunnel Gateway, as it also provides single sign-on capabilities and even conditional access. All of that with a relatively simple deployment. Also, to work with Microsoft Tunnel Gateway, Microsoft released the Microsoft Tunnel app for iOS and Android. That app can be deployed to users and can be used to provide access via Microsoft Tunnel Gateway. That provides a truly great experience for the user. In this post I want to walk through the prerequisites for Microsoft Tunnel Gateway, followed with the different configurations to configure Microsoft Tunnel Gateway. I’ll end this post by distributing the app and configurations to the user and by looking at the user experience.

Important: At this moment, Microsoft Tunnel Gateway is a solution for iOS and Android only.

Prerequisites for Microsoft Tunnel Gateway

For this post it’s important to start with a list of prerequisites for Microsoft Tunnel Gateway. The main reason for that is that I’ll leave a few subjects out-of-scope for this post, but those subjects are important for getting started with Microsoft Tunnel Gateway. Make sure that the following is in place, before starting with Microsoft Tunnel Gateway.

  • a server with a supported Linux distribution that will be used for hosting Microsoft Tunnel Gateway
  • Docker is installed on the server to support containers on the Microsoft Tunnel Gateway server
  • a (preferably publicly) trusted TSL certificate, that contains the public FQDN of the Microsoft Tunnel Gateway server, is available for securing the connection between the devices and the Microsoft Tunnel Gateway server
  • inbound port 443 (UDP and TCP) is available on the server for a functioning Microsoft Tunnel Gateway
  • outbound port 80 (TCP) and 443 (TCP) is available on the server for interaction with Microsoft Intune
  • add Microsoft Tunnel Gateway as a cloud app to Azure AD to enable the use of Conditional Access

My setup

Also, I thought it would be a good idea for this post to provide some information about the starting point that I’ll use for the configurations that are provided throughout this post. That starting point is described below.

  • a virtual server that is running Ubuntu 20.04
  • Docker is installed on that virtual Ubuntu 20.04 server by using these configuration steps
  • a publicly trusted certificate for *.petervanderwoude.nl is available
  • an A-record is configured for vpn.petervanderwoude.nl
  • a gateway router is used to forward port 443 to the virtual Ubuntu 20.04 server

Create the server configuration

The first Microsoft Intune related configuration is the Server configuration. The Server configuration is used to create a configuration that can be applied to one or multiple Microsoft Tunnel Gateway servers. That contains the configuration that will be used for configuring the Microsoft Tunnel Gateway server. That contains information like the IP address range that is used for devices connecting to Microsoft Tunnel Gateway and the port that the Microsoft Tunnel Gateway server is listening to. This information can also be adjusted when Microsoft Tunnel Gateway is up-and-running, but that would require a restart of the server to apply the new configuration. The following five steps walk through creating the Server configuration.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Tenant administrationMicrosoft Tunnel Gateway (Preview) to open the Tenant admin | Microsoft Tunnel Gateway (Preview) blade
  2. On the Tenant admin | Microsoft Tunnel Gateway (Preview) blade, navigate to Server configurations and click Create new to open the Create server configuration wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the server configuration
  • Description: (Optional) Provide a valid description for the server configuration
  1. On the Settings page, provide the following information and click Next
  • IP address range: Provide an IP address range that is leased to devices that connect to Microsoft Tunnel Gateway
  • DNS servers: Provide DNS server addresses that are used for DNS request from devices that are connected to Microsoft Tunnel Gateway
  • DNS suffix search: (Optional) Provide a DNS suffix that is used as default domain for devices that are connected to Microsoft Tunnel Gateway
  • Split tunneling: (Optional) Provide addresses that are included or excluded from Microsoft Tunnel Gateway
  • Server port: Provide the port that Microsoft Tunnel Gateway listens to
  1. On the Review + create page, verify the information and click Create

Important: The server port will also be used for the configuration of the Microsoft Tunnel app.

Create the site

The second Microsoft Intune related configuration is creating a Site. A Site is used to create a logical group of servers that host Microsoft Tunnel Gateway. A Site contains two important configurations that are applied to all the Microsoft Tunnel Gateway servers in the site and that’s the public address and the Server configuration that should be applied. Make sure that the Site is configured correctly, as it can’t be adjusted afterwards. The following three steps walk through the creation of a Site.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Tenant administrationMicrosoft Tunnel Gateway (Preview) to open the Tenant admin | Microsoft Tunnel Gateway (Preview) blade
  2. On the Tenant admin | Microsoft Tunnel Gateway (Preview) blade, navigate to Sites and servers and click Create > New site to open the Create a site page
  3. On the Create a site page, provide the following information and click Create
  • Name: Provide a valid name for this site
  • Description: (Optional) Provide a valid description for this site
  • Public IP address or FQDN: Provide a public IP address or FQDN that is used by the devices as the connection point to to Microsoft Tunnel Gateway
  • Server configuration: Select the just created server configuration

Note: The IP address or FQDN can point to an individual server or to a load-balancing server. When there is a firewall in between, make sure to create the necessary network adjustments.

Important: The IP address must be publicly routable and the FQDN must be publicly resolvable.

Install Microsoft Tunnel Gateway

After creating the Site and the Server configuration that can be applied to a Microsoft Tunnel Gateway server, it’s time to start with the actual installation of Microsoft Tunnel Gateway on the created Linux server with Docker. The installation is performed by downloading and running the Microsoft Tunnel Gateway installation script on the Linux server with Docker installed. The Microsoft Tunnel Gateway installation script will walk through the different required actions that should be performed to get the Microsoft Tunnel Gateway server up-and-running and interacting with Microsoft Intune. The following seven steps walk through that process.

  1. Connect to the Linux server with Docker and logon
  2. Download the Microsoft Tunnel Gateway installation script by using a command like this
wget https://aka.ms/microsofttunneldownload -O mstunnel-setup
  1. Start the Microsoft Tunnel Gateway installation script by using a command like this
sudo bash mstunnel-setup
  1. When prompted by the Microsoft Tunnel Gateway installation script, accept the license agreement (EULA)
  2. When prompted by the Microsoft Tunnel Gateway installation script, copy the TLS certificate to the specified location

Important: The name of the certificate file(s) is mandatory for the Microsoft Tunnel Gateway installation script to detect the existence of the required certificate file(s).

  1. When prompted by the Microsoft Tunnel Gateway installation script, register Microsoft Tunnel Gateway with Microsoft Intune by opening a browser, navigating to https://microsoft.com/devicelogin and entering the code that was provided by the Microsoft Tunnel Gateway installation script

Tip: The browser action can be performed on a different device.

Note: The Microsoft Tunnel Gateway script will prompt to enter a GUID of the site that this Microsoft Tunnel Gateway server should join, when multiple sites are configuration in Microsoft Intune.

  1. After the Microsoft Tunnel Gateway installation script is finished, the server will show in the Microsoft Endpoint Manager admin center portal when navigating to Tenant administrationMicrosoft Tunnel Gateway (Preview) > Health status as shown below in Figure 3.

Tip: When the Microsoft Tunnel Gateway installation script is stopped, it can be restarted again by using the same installation command. The installation will continue were it was stopped.

Deploy Microsoft Tunnel app

Once Microsoft Tunnel Gateway is up-and-running and online, it’s time to look at the device configurations. The first thing of those configurations is distributing the Microsoft Tunnel app. The Microsoft Tunnel app is required for accessing resources via Microsoft Tunnel Gateway on a mobile device. As the steps differ per platform, the most common options for deploying the Microsoft Tunnel app are described below per platform.

Deploy Microsoft Tunnel app for Android

The following seven steps walk through the process of distributing the Microsoft Tunnel app to the different Android Enterprise managed devices. As this is focused on Android Enterprise, the focus is on the Managed Google Play store.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to AppsAll apps > Android to open the Android | Android apps blade
  2. On the Android | Android apps blade, click Add to open the Select app type blade
  3. On the Select app type blade, select Managed Google Play app as App type and click Select to open the Managed Google Play page
  4. On the Managed Google Play page, search for the Microsoft Tunnel app, select the app (as shown in Figure 4) and click Approve
  5. On the Approval settings dialog, select Keep approved when app requests new permissions click Done
  6. Click Sync to synchronize the approval to Microsoft Intune
  7. Assign the Microsoft Tunnel app to the required users and/or devices

Deploy Microsoft Tunnel app for iOS/iPadOS

The following seven steps walk through the process of distributing the Microsoft Tunnel app to iOS/iPadOS devices. As my lab doesn’t contain Apple Business Manager (ABM), the focus is on the normal App Store.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to AppsAll apps > iOS/iPadOS to open the iOS/iPadOS | iOS/iPadOS apps blade
  2. On the iOS/iPadOS | iOS/iPadOS apps blade, click Add to open the Select app type blade
  3. On the Select app type blade, select iOS store app as App type and click Select to open the Add app wizard
  4. On the App information page, click Search the App Store, select the Microsoft Tunnel app (as shown in Figure 5) and click Select and click Next
  1. On the Scope tags page, click Next
  2. On the Assignments page, configure the assignment to the required users and/or devices and click Next
  3. On the Review + create page, verify the configuration and click Create

Deploy VPN profile

Once Microsoft Tunnel Gateway is up-and-running and online and the Microsoft Tunnel app is deployed to the mobile devices, it’s time to configure and deploy the VPN profile. The VPN profile is used to apply the correct configuration to the Microsoft Tunnel app and to make sure that the device can connect via Microsoft Tunnel Gateway.

Deploy VPN profile on Android

The following eight steps walk through the process of creating a VPN profile for the different Android Enterprise managed devices. Even thought the corporate-owned device and personal device deployment scenarios require a separate VPN profile, the steps below are applicable for both deployment scenarios.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices Android > Configuration profiles to open the Android | Configuration profiles blade
  2. On the Android | Configuration profiles blade, select Create profile to open the Create a profile page
  3. On the Create a profile page, provide the following information and click Create
  • Platform: Android Enteprise
  • Profile: Select Fully Managed, Dedicated, and Corporate-Owned Work Profile > VPN or select Work Profile > VPN, depending on the Android Enterprise deployment scenario to open the VPN wizard
  1. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the VPN profile
  • Description: (Optional) Provide a valid description for the VPN profile
  1. On the Configuration settings page, provide the following information and click Next
  • Connection type: Select Microsoft Tunnel
  • Connection name: Provide a valid name for the VPN profile that will be shown to the user in the Microsoft Tunnel app
  • Microsoft Tunnel site: Select the Site that will be used by this VPN profile

Note: When selecting the Site, the configuration also shows the complete public address that will be used for the Microsoft Tunnel app configuration.

  • Select apps that would trigger this VPN on use: (Optional) Add apps that should use this VPN profile to send app traffic to the tunnel

Note: When adding apps to this VPN profile, this VPN profile will only be used as a per-app VPN.

  • Always-on VPN: (Optional) Select Enable to make sure that the VPN will automatically connect and reconnect
  • Automatic configuration script: (Optional) Configure the location of the automatic configuration script, when a proxy should be used
  • Address: (Optional) Configure the address of the proxy server, when a proxy should be used
  • Port number: (Optional) Configure the port number of the proxy server, when a proxy should be used
  1. On the Scope tags page, click Next
  2. On the Assignments page, configure the assignment to the required users and/or devices and click Next
  3. On the Review + create page, verify the configuration and click Create

Deploy VPN profile on iOS/iPadOS

The following eight steps walk through the process of creating a VPN profile for iOS and iPadOS devices. These steps are nearly identical to the steps for creating a VPN profile for Android Enterprise device, but only the available configurations for per-app VPN, in step 5, are slightly different.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Devices iOS/iPadOS > Configuration profiles to open the iOS/iPadOS | Configuration profiles blade
  2. On the iOS/iPadOS | Configuration profiles blade, select Create profile to open the Create a profile page
  3. On the Create a profile page, provide the following information and click Create
  • Platform: iOS/iPadOS
  • Profile: Select VPN to open the VPN wizard
  1. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the VPN profile
  • Description: (Optional) Provide a valid description for the VPN profile
  1. On the Configuration settings page, provide the following information and click Next
  • Connection type: Select Microsoft Tunnel
  • Connection name: Provide a valid name for the VPN profile that will be shown to the user in the Microsoft Tunnel app
  • Microsoft Tunnel site: Select the Site that will be used by this VPN profile

Note: When selecting the Site, the configuration also shows the complete public address that will be used for the Microsoft Tunnel app configuration.

  • Per-app VPN: (Optional) Select Enable when this profile should be used for per-app VPN

Note: When enabling per-app VPN, an app should be specifically associated with the VPN profile.

  • Automatic configuration script: (Optional) Configure the location of the automatic configuration script, when a proxy should be used
  • Address: (Optional) Configure the address of the proxy server, when a proxy should be used
  • Port number: (Optional) Configure the port number of the proxy server, when a proxy should be used
  1. On the Scope tags page, click Next
  2. On the Assignments page, configure the assignment to the required users and/or devices and click Next
  3. On the Review + create page, verify the configuration and click Create

Conditional access reflections

As mentioned in the prerequisites, to facilitate a working Microsoft Tunnel Gateway in combination with Conditional Access, a Microsoft Tunnel Gateway cloud app should be registered in Azure AD. That cloud app can be used in the different Conditional Access rules within an organization. Without adding that cloud app to Azure AD, and assigning Conditional Access rules to all cloud apps, those Conditional Access rules will also be applicable to Microsoft Tunnel Gateway. Of course, that doesn’t have to be a bad thing. However, one scenario to keep in mind is with requiring an approved client app or a requiring an app protection policy. The problem is that the Microsoft Tunnel app is not yet on the list of approved client apps or on the list of app protection policy apps. That means that the Microsoft Tunnel app will be blocked when either one of those settings is applicable to Microsoft Tunnel Gateway. Requiring a compliant device is not a problem.

End-user experience

The best way to end this long post is by looking at the end-user experience. More specifically, a successful end-user experience. Below are three screenshots that are showing a working connection with Microsoft Tunnel Gateway. Figure 8 provides an example of the basic connection information. That contains information about the status. uptime, data sent and received and the name of the connection. The latter can be related to the name in the VPN profile. Figure 9 provides an example about the details of the connection. That contains information about the type of VPN (per-app versus device-wide), if always-on is enabled and also the name and status. All of that information can be related to the configured VPN profile. Figure 10 provides an example of a connection to an internal resource (with internal IP) within my environment. The icons on the top left of the screen show the successful VPN connection that is still on.

Note: An administrator can look at more details about the status of Microsoft Tunnel Gateway, by using the mst-cli command line tool on the Microsoft Tunnel Gateway server. That tool can be used to look at details, like the status, statistics, connected users and much more.

More information

For more information about Microsoft Tunnel Gateway, refer to the following docs

Remediating local administrators with proactive remediations

Like last week, this week is all about proactive remediations, a feature of Endpoint Analytics. As mentioned last week, proactive remediations are script packages that can detect common issues and remediate those issues if needed. All of that before the user even realizes that there is an issue. Those remediations can help with reducing support calls. The strength is that the remediations can be anything to address potential issues, as long as it can be addressed by using PowerShell. Each script package contains a detection script and a remediation script and that script package is deployed through Microsoft Intune. For deploying script packages, Microsoft Intune relies on the Intune Management Extension (IME).

To show the real power of proactive remediations, I’ll further develop the local administrators example of last week. Even in this modern world, local administrators are still a hot item. Last week the focus was on the detection part of proactive remediations and in this post I’ll focus on the remediation part of proactive remediations. I’ll start this post by constructing the remediation script, followed by creating the script package. I’ll end this post by verifying the results. Last week the focus for the results was locally on the device and in this post I’ll focus on the results in Microsoft Intune. This week I’ll skip the important requirements, as I’ve already documented them last week.

Constructing the remediation script

The first step is constructing the remediation script. That script should remediate the faulty configuration that was detected by the detection script. In this example, which is shown below, the remediation script is focused on a scenario in which the user of the device is a local administrator and should remain a local administrator. To fulfill that scenario the remediation script will remove all accounts, with exception of the default Administrator and the currently logged-on user, from the Administrators group. After removal of the accounts from the Administrators group, the script will add the correct accounts to the Administrators group. That will make sure that only the verified and correct accounts are members of the Administrators group and are configured on the local device. When the adjustment to the members of the Administrators group was successful, the script will return an exit code of 0 and when the adjustment to the members of the Administrators was a failure, the script will return an exit code of 1. The last line of output, before the exit code, will be displayed in the logs and can be useful information when verifying and troubleshooting the remediation script. Before using the script, make sure to adjust the array with administrator accounts to the correct list of administrators. That required adjustments is mentioned in the script example below.

#Define variables
$currentUser = (Get-CimInstance Win32_ComputerSystem).Username -replace '.*\\'
$localAdministrators = @("[YourGlobalAdminRoleSid]","[YourDeviceAdminRoleSid]") #Adjust to your local administrators
try {
$administratorsGroup = ([ADSI]"WinNT://$env:COMPUTERNAME").psbase.children.find("Administrators")
$administratorsGroupMembers = $administratorsGroup.psbase.invoke("Members")
foreach ($administratorsGroupMember in $administratorsGroupMembers) {
$administrator = $administratorsGroupMember.GetType().InvokeMember('Name','GetProperty',$null,$administratorsGroupMember,$null)
if (($administrator -ne "Administrator") -and ($administrator -ne $currentUser)) {
$administratorsGroup.Remove("WinNT://$administrator")
Write-Host "Successfully removed $administrator from Administrators group"
}
}
foreach ($localAdministrator in $localAdministrators) {
$administratorsGroup.Add("WinNT://$localAdministrator")
Write-Host "Successfully added $localAdministrator to Administrators group"
}
Write-Host "Successfully remediated the local administrators"
}
catch {
$errorMessage = $_.Exception.Message
Write-Error $errorMessage
exit 1
}

Note: Just like last week I’m relying on ADSI for making the required adjustments.

Creating the script package

The second step is creating the script package. The script package can be created by using the proactive remediations functionality of Endpoint Analytics. That functionality can be used to schedule scripts to detect specific configurations and when that configuration is faulty, it can run scripts to remediate the configuration. The following six steps walk through the process of creating a script package, with a detection script and a remediation script. That will create a script package to detect the currently configured accounts from the Administrators and to remediate any faulty configuration that is detected. That script package can be scheduled to either perform the detection and remediation only once, or on a recurring schedule. The latter will make sure that it can actually be used for creating some baseline configurations, which might sound familiar when previously, or still, using Configuration Manager. The idea is the same, just a bit more simplistic and easier to use.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Reports Endpoint analytics (Preview) > Proactive remediations to open the Endpoint analytics (Preview) | Proactive remediations blade
  2. On the Endpoint analytics (Preview) | Proactive remediations blade, click Create script package to open the Create custom script wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the custom script package
  • Description: (Optional) Provide a valid description for the custom script package
  • Publisher: Provide a valid publisher for the custom script package
  • Version: [Greyed out]
  1. On the Settings page, provide the following information and click Next
  • Detection script file: Select the previously week created detection script
  • Detection script: [Greyed out]
  • Remediation script file: Select the created remediation script
  • Remediation script: [Greyed out]
  • Run this script using the logged-on credentials: No
  • Enforce script signature check: No
  • Run script in 64-bit PowerShell: No

Important: This configuration will run these scripts with bypassing the execution policy. Together with the information of my previous post, this could enable an administrative user to edit the script before running (and without the script being checked before running).

  1. On the Assignments page, provide the following information and click Next
  • Assign to: Select the assigned group and when selecting multiple groups, multiple lines will appear with all separate schedule configurations
  • Schedule: Click on the three dots to open the schedule configuration. This enables the administrator to configure a recurrence frequency for the script package. This can be Once, Daily, or Hourly.
    • When selecting Once, a specific date and time should be configured
    • When selecting Daily, a frequency and daily time should be configured
    • When selecting Hourly, a frequency should be configured
  1. On the Review + create page, verify the information and click Create

Verifying the results

When verifying the results, in Microsoft Intune, the first place to look is the proactive remediations overview. That provides an overview of all the different script packages that are deployed within the organization. That overview provides an easy first method to monitor the detection and remediation results of all the different deployed script packages. That overview is shown below and is available via Reports > Endpoint analytics > Proactive remediations.

When more details are required about a specific script package, the script package overview is the best place to look. That provides an overview that is specifically related to the status of a specific script package. That overview provides a clear bar chart for the status of the detection and remediation script of the script package. Besides that it also shows a nice daily remediation trend. That daily trend provides an overview of how often that specific situation is remediated. That overview is shown below and is available via Reports > Endpoint analytics > Proactive remediations > [Specific script package] > Overview.

When even more details are required about a specific script package on a specific device, the script package device status overview is the best place to look. That provides a clear overview about status details of a script package on the different devices. That overview includes standard information about the device and the last sync time, but also includes useful information that was part of the output of the detection script. That overview is shown below and is available via Reports > Endpoint analytics > Proactive remediations > [Specific script package] > Device status.

More information

For more information about Endpoint Analytics and Proactive Remediations, refer to the following docs

Detecting local administrators with proactive remediations

This week is all about proactive remediations, which is a feature of Endpoint Analytics. Proactive remediations are script packages that can detect common issues and remediate those issues if needed. All of that before the user even realizes that there is an issue. Those remediations can help with reducing support calls. The strength is that the remediations can be anything to address potential issues, as long as it can be addressed by using PowerShell. Each script package contains a detection script and a remediation script and that script package is deployed through Microsoft Intune. For deploying script packages, Microsoft Intune relies on the Intune Management Extension (IME).

To show the power of proactive remediations, I’ll use local administrators as an example. I’ve did something similar a long time ago for Configuration Manager and I still get many questions around that subject on my post about managing local administrators. Even in this modern world, local administrators are still a hot item. In this post I’ll focus on the detection part of proactive remediations and the remediation part itself might only be a week away. I’ll start this post by constructing the detection script, followed by creating the script package. I’ll end this post by verifying the results locally on the device.

Important prerequisites

Before actually starting with Endpoint Analytics it’s important to have the different prerequisites in place. That means the correct licenses and the correct configuration.

  • The device must be running Windows 10 Enterprise, Professional, or Education
  • The devices must be enrolled into Endpoint Analytics
  • The devices must be Azure AD joined or hybrid Azure AD joined and meet one of the following conditions:
    • the device is managed by Intune.
    • the device is co-managed device and running Windows 10, version 1903 or later.
    • the device is co-managed device and running on pre-1903 versions of Windows 10 with the Client apps workload pointed to Intune
  • The user must be licensed for Endpoint Analytics, which is included in Enterprise Mobility + Security E3 or higher and Microsoft 365 Enterprise E3 or higher, and when not using the latter, additional licensing of the following:
    • Windows 10 Enterprise E3 or E5
    • Windows 10 Education A3 or A5
    • Windows Virtual Desktop Access E3 or E5

Constructing the detection script

The first step is constructing the detection script. That script should detect the correct situation. In this example, the detection script should detect the correct number of local administrators and also the correct local administrator users. For a successful detection of the correct (number of) local administrators, the script should return an exit code of 0 and for a failed detection of the (number of) local administrators, the script should return an exit code of 1. That failure will eventually trigger the remediation script. More about that, next week. Besides that, it’s good to know that the last line of output, before the exit code, will also be displayed in the logs. That can be helpful when verifying and troubleshooting the detection script. The following example detection script will verify the number of local administrators and once the number matches, it will actually verify the local administrator users with the configured list of local administrators. Make sure to adjust that list with the correct local administrators and make sure to adjust the number of local administrators. The required adjustments are mentioned in the script example below.

#Define variables
$localAdministrators = @()
$memberCount = 0
$numberLocalAdministrators = 4 #Adjust to your number of administrators
try {
$currentUser = (Get-CimInstance Win32_ComputerSystem).Username -replace '.*\\'
$administratorsGroup = ([ADSI]"WinNT://$env:COMPUTERNAME").psbase.children.find("Administrators")
$administratorsGroupMembers= $administratorsGroup.psbase.invoke("Members")
foreach ($administrator in $administratorsGroupMembers) {
$localAdministrators += $administrator.GetType().InvokeMember('Name','GetProperty',$null,$administrator,$null)
}
if ($localAdministrators.Count -eq $numberLocalAdministrators) {
foreach($localAdministrator in $localAdministrators) {
switch ($localAdministrator) {
#Adjust to your local administrators
"Administrator" { $memberCount = $memberCount + 1; break; }
"$currentUser" { $memberCount = $memberCount + 1; break; }
"[YourGlobalAdminRoleSid]" { $memberCount = $memberCount + 1; break; }
"[YourDeviceAdminRoleSid]" { $memberCount = $memberCount + 1; break; }
default {
Write-Host "The found local administrators are no match"
exit 1
}
}
}
if ($memberCount -eq $numberLocalAdministrators) {
Write-Host "The found local administrators are a match"
exit 0
}
}
else {
Write-Host "The number of local administrators doesn't match"
exit 1
}
}
catch {
$errorMessage = $_.Exception.Message
Write-Error $errorMessage
exit 1
}

Note: Compared to my previous post, I prefer to use ADSI above WMI and Get-LocalGroupMember. WMI was often too slow and the mentioned cmdlet doesn’t really like SIDs yet.

Creating the script package

The second step is creating the script package. The script package can be created by using the relatively new functionality of Endpoint Analytics, which is proactive remediations. That functionality can be used to basically schedule scripts to detect specific configurations and, if needed, remediate the configuration. The following six steps walk through the process of creating a script package, with a focus on the detection script. That will create a script package to detect the local administrators. That script package can be scheduled to either perform the detection (and remediation) only once, or on a recurring schedule. The latter will make sure that it can actually be used for creating some baseline configurations, which might sound familiar when previously, or still, using Configuration Manager. The idea is the same, just a bit more simplistic and easier to use.

  1. Open the Microsoft Endpoint Manager admin center portal navigate to Reports Endpoint analytics (Preview) > Proactive remediations to open the Endpoint analytics (Preview) | Proactive remediations blade
  2. On the Endpoint analytics (Preview) | Proactive remediations blade, click Create script package to open the Create custom script wizard
  3. On the Basics page, provide the following information and click Next
  • Name: Provide a valid name for the custom script package
  • Description: (Optional) Provide a valid description for the custom script package
  • Publisher: Provide a valid publisher for the custom script package
  • Version: [Greyed out]
  1. On the Settings page, provide the following information and click Next
  • Detection script file: Select the created detection script
  • Detection script: [Greyed out]
  • Remediation script file: (Optional) More about the remediation script file next week
  • Remediation script: (Optional) More about the remediation script next week
  • Run this script using the logged-on credentials: No
  • Enforce script signature check: No
  • Run script in 64-bit PowerShell: No
  1. On the Assignments page, provide the following information and click Next
  • Assign to: Select the assigned group and when selecting multiple groups, multiple lines will appear with all separate schedule configurations
  • Schedule: Click on the three dots to open the schedule configuration. This enables the administrator to configure a recurrence frequency for the script package. This can be Once, Daily, or Hourly.
    • When selecting Once, a specific date and time should be configured
    • When selecting Daily, a frequency and daily time should be configured
    • When selecting Hourly, a frequency should be configured
  1. On the Review + create page, verify the information and click Create

Verifying the results

For the detection of the local administrators, I’ll focus mainly on the information locally on the device. Next week, when adding the remediation, the focus will be on Microsoft Intune when looking at the results. As it’s the IME that is addressing the execution of the script packages, the information related to the execution is also logged in the IME related logfiles. The most interesting information can be found in the IntuneManagementExtension.log. That logfile contains the execution information of the script packages and every related line in the log has a prefix of [HS]. That prefix is referring to HealthScripts, which is shown in the different logs and file locations. When looking at the [HS] prefix throughout the log, it’s divided into the following two categories:

  1. Scheduler – Looking at the log, the Scheduler is responsible for requesting and scheduling the script packages. Below, in Figure 3, is an example of the Scheduler that is scheduling the script package for detecting local administrators. The highlighted sections show information about the user, the policy and the schedule. All of that information is referenced below in more logs, file locations and the registry.
  1. Runner – Looking at the log, the Runner is responsible for executing and reporting about the script packages. Below, in Figure 4, is an example of the Runner that is actually executing the scheduled policy for detecting local administrators. The highlighted sections show information about the user, the policy, the schedule, the result and the output. All that information is referenced above in the script, and below in the file location and the registry.

The script package is store locally in the HealthScripts folder in the IMECache folder. That folder contains a folder, as shown below in Figure 5, that corresponds with the policy that was highlighted in the IntuneManagementExtension.log. That folder contains a script named detect and a script named remediate and both of those scripts correspond to the scripts of the script package. When the script package is only used for detection, the remediate script will be empty.

In the end all of the most important information is stored in the registry, in the Scrips key in HKLM\SOFTWARE\Microsoft\IntuneManagementExtension\SideCarPolicies. That key contains a key with information about the execution of the script package and that information is stored below a key of the user and the policy. That key contains the latest execution information and is shown below in Figure 6.

The Scripts key also contains a key with information about the result of the script package and that information is store below a key of the user and the policy. That key contains the result information that is reported and is shown in Figure 7.

The actual content of the Result value is shown below. That information contains the policy, the user, that status and the output. All the information that was referenced earlier in the script, log, file location and registry.

{ 
    "PolicyId":"176b61ca-59e6-4af1-b852-13a3102c5578",
    "UserId":"dedbba8f-f4f1-475c-a30b-895d87d77e9b",
    "PolicyHash":null,
    "Result":3,
    "ResultDetails":null,
    "InternalVersion":1,
    "ErrorCode":0,
    "ResultType":1,
    "PreRemediationDetectScriptOutput":"The found local administrators are a match",
    "PreRemediationDetectScriptError":null,
    "RemediationScriptErrorDetails":null,
    "PostRemediationDetectScriptOutput":null,
    "PostRemediationDetectScriptError":null,
    "RemediationStatus":4,
    "Info": {
        "RemediationExitCode":0,
        "FirstDetectExitCode":0,
        "LastDetectExitCode":0,
        "ErrorDetails":null
    }
}

More information

For more information about Endpoint Analytics and Proactive Remediations, refer to the following docs