Add app configuration policies for managed iOS/iPadOS devices

Use app configuration policies in Microsoft Intune to provide custom configuration settings for an iOS/iPadOS app. These configuration settings allow an app to be customized based on the app suppliers direction. You must get these configuration settings (keys and values) from the supplier of the app. To configure the app, you specify the settings as keys and values, or as XML containing the keys and values.

As the Microsoft Intune admin, you can control which user accounts are added to Microsoft 365 (Office) applications on managed devices. You can limit access to only allowed organization user accounts and block personal accounts on enrolled devices. The supporting applications process the app configuration and remove and block unapproved accounts. The configuration policy settings are used when the app checks for them, typically the first time it is run.

Once you add an app configuration policy, you can set the assignments for the app configuration policy. When you set the assignments for the policy, you can choose to use a filter and to include and exclude the groups of users for which the policy applies. When you choose to include one or more groups, you can choose to select specific groups to include or select built-in groups. Built-in groups include All Users, All Devices, and All Users + All Devices.

Note

Intune provides pre-created All Users and All Devices groups in the console with built-in optimizations for your convenience. It is highly recommended that you use these groups to target all users and all devices instead of any 'All users' or 'All devices' groups you may have created yourself.

Once you have selected the included groups for your application configuration policy, you can also choose the specific groups to exclude. For more information, see Include and exclude app assignments in Microsoft Intune.

Tip

This policy type is currently available only for devices running iOS/iPadOS 8.0 and later. It supports the following app installation types:

  • Managed iOS/iPadOS app from the app store
  • App package for iOS

For more information about app installation types, see How to add an app to Microsoft Intune. For more information about incorporating app config into your .ipa app package for managed devices, see Managed App Configuration in the iOS developer documentation.

Create an app configuration policy

  1. Sign in to the Microsoft Intune admin center.

  2. Choose the Apps > App configuration policies > Add > Managed devices. Note that you can choose between Managed devices and Managed apps. For more information see Apps that support app configuration.

  3. On the Basics page, set the following details:

    • Name - The name of the profile that appears in the Microsoft Intune admin center.
    • Description - The description of the profile that appears in the Microsoft Intune admin center.
    • Device enrollment type - This setting is set to Managed devices.
  4. Select iOS/iPadOS as the Platform.

  5. Click Select app next to Targeted app. The Associated app pane is displayed.

  6. On the Targeted app pane, choose the managed app to associate with the configuration policy and click OK.

  7. Click Next to display the Settings page.

  8. In the dropdown box, select the Configuration settings format. Select one of the following methods to add configuration information:

  9. Click Next to display the Scope tags page.

  10. [Optional] You can configure scope tags for your app configuration policy. For more information about scope tags, see Use role-based access control (RBAC) and scope tags for distributed IT.

  11. Click Next to display the Assignments page.

  12. On the Assignments page, select either Add groups, Add all users, or Add all devices to assign the app configuration policy. Once you've selected an assignment group, you can select a filter to refine the assignment scope when deploying app configuration policies for managed devices.

    Screenshot of configuration policy assignments page

  13. Select All users in the dropdown box.

    Screenshot of Policy assignments - All Users dropdown option

  14. [Optional] Click Edit filter to add a filter and refine the assignment scope.

    Screenshot of Policy assignments - Edit filter

  15. Click Select groups to exclude to display the related pane.

  16. Choose the groups you want to exclude and then click Select.

    Note

    When adding a group, if any other group has already been included for a given assignment type, it is pre-selected and unchangeable for other include assignment types. Therefore, that group that has been used, cannot be used as an excluded group.

  17. Click Next to display the Review + create page.

  18. Click Create to add the app configuration policy to Intune.

Use configuration designer

Microsoft Intune provides configuration settings that are unique to an app. You can use the configuration designer for apps on devices that are enrolled or not enrolled in Microsoft Intune. The designer lets you configure specific configuration keys and values that help you create the underlying XML. You must also specify the data type for each value. These settings are supplied to apps automatically when the apps are installed.

Add a setting

  1. For each key and value in the configuration, set:
    • Configuration key - The case sensitive key that uniquely identifies the specific setting configuration.
    • Value type - The data type of the configuration value. Types include Integer, Real, String, or Boolean.
    • Configuration value - The value for the configuration.
  2. Choose OK to set your configuration settings.

Delete a setting

  1. Choose the ellipsis (...) next to the setting.
  2. Select Delete.

The {{ and }} characters are used by token types only and must not be used for other purposes.

Allow only configured organization accounts in apps

As the Microsoft Intune administrator, you can control which work or school accounts are added to Microsoft apps on managed devices. You can limit access to only allowed organization user accounts and block personal accounts within the apps (if supported) on enrolled devices. For iOS/iPadOS devices, use the following key/value pairs in a Managed Devices app configuration policy:

Key Values
IntuneMAMAllowedAccountsOnly
  • Enabled: The only account allowed is the managed user account defined by the IntuneMAMUPN key.
  • Disabled (or any value that is not a case insensitive match to Enabled): Any account is allowed.
IntuneMAMUPN
  • UPN of the account allowed to sign into the app.
  • For Intune enrolled devices, the {{userprincipalname}} token may be used to represent the enrolled user account.

Note

The following apps process the above app configuration and only allow organization accounts:

  • Copilot for iOS (28.1.420324001 and later)
  • Edge for iOS (44.8.7 and later)
  • Office, Word, Excel, PowerPoint for iOS (2.41 and later)
  • OneDrive for iOS (10.34 and later)
  • OneNote for iOS (2.41 and later)
  • Outlook for iOS (2.99.0 and later)
  • Teams for iOS (2.0.15 and later)

Require configured organization accounts in apps

On enrolled devices, organizations can require that the work or school account is signed into managed Microsoft apps in order to receive Org data from other managed apps. For example, consider the scenario where the user has attachments included in email messages contained within the managed email profile located in the native iOS mail client. If the user attempts to transfer the attachments to a Microsoft app, like Office, that is managed on the device and has these keys applied, then this configuration will treat the transferred attachment as Org data, requiring the work or school account to be signed in and enforcing the app protection policy settings.

For iOS/iPadOS devices, use the following key/value pairs in a Managed Devices app configuration policy for each Microsoft app:

Key Values
IntuneMAMRequireAccounts
  • Enabled: The app requires the user to sign-in to the managed user account defined by the IntuneMAMUPN key to receive Org data.
  • Disabled (or any value that is not a case insensitive match to Enabled): No account sign-in is required
IntuneMAMUPN
  • UPN of the account allowed to sign into the app.
  • For Intune enrolled devices, the {{userprincipalname}} token may be used to represent the enrolled user account.

Note

Apps must have Intune APP SDK for iOS version 12.3.3 or later and be targeted with an Intune app protection policy when requiring sign-in to work or school account. Within the app protection policy, the “Receive data from other apps” must be set to “All apps with incoming Org data”.

At this time, app sign-in is only required when there is incoming Org data to a targeted app.

Enter XML data

You can type or paste an XML property list that contains the app configuration settings for devices enrolled in Intune. The format of the XML property list varies depending on the app that you are configuring. For details about the exact format to use, contact the supplier of the app.

Intune validates the XML format. However, Intune does not check that the XML property list (PList) works with the target app.

To learn more about XML property lists:

Example format for an app configuration XML file

When you create an app configuration file, you can specify one or more of the following values by using this format:

<dict>
  <key>userprincipalname</key>
  <string>{{userprincipalname}}</string>
  <key>mail</key>
  <string>{{mail}}</string>
  <key>partialupn</key>
  <string>{{partialupn}}</string>
  <key>accountid</key>
  <string>{{accountid}}</string>
  <key>deviceid</key>
  <string>{{deviceid}}</string>
  <key>userid</key>
  <string>{{userid}}</string>
  <key>username</key>
  <string>{{username}}</string>
  <key>serialnumber</key>
  <string>{{serialnumber}}</string>
  <key>serialnumberlast4digits</key>
  <string>{{serialnumberlast4digits}}</string>
  <key>udidlast4digits</key>
  <string>{{udidlast4digits}}</string>
  <key>aaddeviceid</key>
  <string>{{aaddeviceid}}</string>
  <key>IsSupervised</key>
  <string>{{IsSupervised}}</string>
</dict>

Supported XML PList data types

Intune supports the following data types in a property list:

  • <integer>
  • <real>
  • <string>
  • <array>
  • <dict>
  • <true /> or <false />

Tokens used in the property list

Additionally, Intune supports the following token types in the property list:

  • {{userprincipalname}}—for example, [email protected]
  • {{mail}}—for example, [email protected]
  • {{partialupn}}—for example, John
  • {{accountid}}—for example, fc0dc142-71d8-4b12-bbea-bae2a8514c81
  • {{deviceid}}—for example, b9841cd9-9843-405f-be28-b2265c59ef97
  • {{userid}}—for example, 3ec2c00f-b125-4519-acf0-302ac3761822
  • {{username}}—for example, John Doe
  • {{serialnumber}}—for example, F4KN99ZUG5V2 (for iOS/iPadOS devices)
  • {{serialnumberlast4digits}}—for example, G5V2 (for iOS/iPadOS devices)
  • {{aaddeviceid}}—for example, ab0dc123-45d6-7e89-aabb-cde0a1234b56
  • {{issupervised}}—for example, True (for iOS/iPadOS devices)
  • {{OnPremisesSamAccountName}}—for example, contoso\John

Configure the Company Portal app to support iOS and iPadOS devices enrolled with Automated Device Enrollment

Apple's Automated Device Enrollments are not compatible with the app store version of the Company Portal app by default. However, you can configure the Company Portal app to support iOS/iPadOS ADE devices even when users have downloaded the Company Portal from the App Store by using the following steps.

  1. In Microsoft Intune admin center, add the Intune Company Portal app if it has not been added yet, by going to Apps > All apps > Add > iOS Store App.

  2. Go to Apps > App configuration policies, to create an app configuration policy for the Company Portal app.

  3. Create an app configuration policy with the XML below. More information on how to create an app configuration policy and enter XML data can be found at Add app configuration policies for managed iOS/iPadOS devices.

    • Use the Company Portal on an Automated Device Enrollment (ADE) device enrolled with user affinity:

      Note

      When the enrollment profile has "Install Company Portal" set to yes, Intune pushes the application configuration policy below automatically as part of the initial enrollment process. This configuration should not be deployed manually to users or devices as this will cause a conflict with the payload already sent during enrollment, resulting on end-users being asked to download a new management profile after signing in to Company Portal (when they shouldn't, because there is a management profile already installed on these devices).

      <dict>
          <key>IntuneCompanyPortalEnrollmentAfterUDA</key>
          <dict>
              <key>IntuneDeviceId</key>
              <string>{{deviceid}}</string>
              <key>UserId</key>
              <string>{{userid}}</string>
          </dict>
      </dict>
      
    • Use the Company Portal on a ADE device enrolled without user affinity (also known as Device Staging):

      Note

      The user signing in to Company Portal is set as the primary user of the device.

      <dict>
          <key>IntuneUDAUserlessDevice</key>
          <string>{{SIGNEDDEVICEID}}</string>
      </dict>
      
  4. Deploy the Company Portal to devices with the app configuration policy targeted to desired groups. Be sure to only deploy the policy to groups of devices that are already ADE enrolled.

  5. Tell end users to sign into the Company Portal app when it is automatically installed.

Note

When you add an app configuration to allow the Company Portal app on ADE devices without user affinity, you may experience a STATE Policy Error. Unlike other app configurations, this situation does not apply every time the device checks in. Instead, this app configuration is meant to be a one-time operation to enable existing devices enrolled without user affinity to attain user affinity when a user signs into the Company Portal. This app configuration is removed from the policy in the background once it has been successfully applied. The policy assignment will exist, but it will not report "success" once the app configuration is removed in the background. Once the app configuration policy has applied to the device, you can unassign the policy.

Monitor iOS/iPadOS app configuration status per device

Once a configuration policy has been assigned, you can monitor iOS/iPadOS app configuration status for each managed device. From Microsoft Intune in the Microsoft Intune admin center, select Devices > All devices. From the list of managed devices, select a specific device to display a pane for the device. On the device pane, select App configuration.

Additional information

Next steps

Continue to assign and monitor the app.