AssignedAccess CSP
The AssignedAccess configuration service provider (CSP) is used to configure a kiosk or restricted user experience. Once the CSP is executed, the next user login that is associated with the Assigned Access profile puts the device into the kiosk mode specified in the CSP configuration.
To learn more about how to configure Assigned Access, see Configure kiosks and restricted user experiences.
The following list shows the AssignedAccess configuration service provider nodes:
- ./Vendor/MSFT/AssignedAccess
Configuration
| Scope | Editions | Applicable OS |
|---|---|---|
| ✅ Device ❌ User |
✅ Pro ✅ Enterprise ✅ Education ✅ Windows SE ✅ IoT Enterprise / IoT Enterprise LTSC |
✅ Windows 10, version 1709 [10.0.16299] and later |
./Vendor/MSFT/AssignedAccess/Configuration
This node accepts an AssignedAccessConfiguration xml as input.
To learn how to configure xml file, see Create an Assigned Access configuration XML file
Description framework properties:
| Property name | Property value |
|---|---|
| Format | chr (string) |
| Access Type | Add, Delete, Get, Replace |
Examples:
Get Configuration
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Get> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/Configuration</LocURI> </Target> </Item> </Get> <Final /> </SyncBody> </SyncML>Delete Configuration
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Delete> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/Configuration</LocURI> </Target> </Item> </Delete> <Final /> </SyncBody> </SyncML>
KioskModeApp
Note
This policy is deprecated and may be removed in a future release.
| Scope | Editions | Applicable OS |
|---|---|---|
| ✅ Device ❌ User |
✅ Pro ✅ Enterprise ✅ Education ✅ Windows SE ✅ IoT Enterprise / IoT Enterprise LTSC |
✅ Windows 10, version 1507 [10.0.10240] and later |
./Vendor/MSFT/AssignedAccess/KioskModeApp
This node can accept and return json string which comprises of account name, and AUMID for Kiosk mode app.
Example: {"User":"domain\\user", "AUMID":"Microsoft.WindowsCalculator_8wekyb3d8bbwe!App"}.
When configuring kiosk mode app, account name will be used to find the target user. Account name includes domain name and user name. Domain name can be optional if user name is unique across the system. For a local account, domain name should be machine name. When "Get" is executed on this node, domain name is always returned in the output.
This node supports Add, Delete, Replace and Get methods. When there's no configuration, "Get" and "Delete" methods fail. When there's already a configuration for kiosk mode app, "Add" method fails. The data pattern for "Add" and "Replace" is the same.
Tip
In the above example the double \\ is required because it's in JSON and JSON escapes \\ into \. If an MDM server uses JSON parser\composer, they should ask customers to type only one \, which will be \\ in the JSON. If user types \\, it'll become \\\\ in JSON, which will cause erroneous results. For the same reason, domain\user used in Configuration xml does not need \\ but only one \, because xml does not (need to) escape \.
This applies to both domain\user, AzureAD\someone@contoso.onmicrosoft.com, as long as a \ is used in JSON string.
For more information about how to get the AUMID, see Find the Application User Model ID of an installed app.
Important
- In Windows 10, version 1803, the Configuration node introduced single app kiosk profile to replace KioskModeApp CSP node. KioskModeApp node will be deprecated soon, so you should use the single app kiosk profile in configuration xml for Configuration node to configure public-facing single app Kiosk.
- Additionally, starting in Windows 10, version 1803, the KioskModeApp node becomes No-Op if Configuration node is configured on the device. Add/Replace/Delete commands on KioskModeApp node always returns SUCCESS to the MDM server if Configuration node is set, but the data of KioskModeApp will not take any effect on the device. Get command on KioskModeApp will return the configured JSON string even it's not effective.
- You can't set both KioskModeApp and ShellLauncher at the same time on the device.
Description framework properties:
| Property name | Property value |
|---|---|
| Format | chr (string) |
| Access Type | Add, Delete, Get, Replace |
Examples:
Add KioskModeApp
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Add> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/KioskModeApp</LocURI> </Target> <Meta> <Format xmlns="syncml:metinf">chr</Format> </Meta> <Data>{"Account":"Domain\\AccountName","AUMID":"Microsoft.WindowsCalculator_8wekyb3d8bbwe!App"}</Data> </Item> </Add> <Final /> </SyncBody> </SyncML>Delete KioskModeApp
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Delete> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/KioskModeApp</LocURI> </Target> </Item> </Delete> <Final /> </SyncBody> </SyncML>Get KioskModeApp
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Get> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/KioskModeApp</LocURI> </Target> </Item> </Get> <Final /> </SyncBody> </SyncML>Replace KioskModeApp
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Replace> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/KioskModeApp</LocURI> </Target> <Meta> <Format xmlns="syncml:metinf">chr</Format> </Meta> <Data>{"Account":"Domain\\AccountName","AUMID":"Microsoft.WindowsAlarms_8wekyb3d8bbwe!App"}</Data> </Item> </Replace> <Final /> </SyncBody> </SyncML>
ShellLauncher
| Scope | Editions | Applicable OS |
|---|---|---|
| ✅ Device ❌ User |
❌ Pro ✅ Enterprise ✅ Education ❌ Windows SE ✅ IoT Enterprise / IoT Enterprise LTSC |
✅ Windows 10, version 1803 [10.0.17134] and later |
./Vendor/MSFT/AssignedAccess/ShellLauncher
This node accepts a ShellLauncherConfiguration xml as input.
To learn about Shell Launcher, see What is Shell Launcher?.
Important
You can't set both ShellLauncher and KioskModeApp at the same time on the device.
Note
Configuring Shell Launcher using the ShellLauncher node automatically enables the Shell Launcher feature, if it is available within the SKU.
Shell Launcher as a feature and the ShellLauncher node both require Windows Enterprise or Windows Education to function. The ShellLauncher node is not supported in Windows 10 Pro.
Description framework properties:
| Property name | Property value |
|---|---|
| Format | chr (string) |
| Access Type | Add, Delete, Get, Replace |
Here's the Shell Launcher XSD reference article: Shell Launcher XML Schema Definition (XSD).
Examples:
Add
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Add> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/ShellLauncher</LocURI> </Target> <Meta> <Format xmlns="syncml:metinf">chr</Format> </Meta> <Data> <![CDATA[ <!-- Add your XML configuration. For more information, see the Shell Launcher XSD reference article. --> ]]> </Data> </Item> </Add> <Final /> </SyncBody> </SyncML>Get
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Get> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/ShellLauncher</LocURI> </Target> </Item> </Get> <Final /> </SyncBody> </SyncML>
Status
| Scope | Editions | Applicable OS |
|---|---|---|
| ✅ Device ❌ User |
✅ Pro ✅ Enterprise ✅ Education ✅ Windows SE ✅ IoT Enterprise / IoT Enterprise LTSC |
✅ Windows 10, version 1803 [10.0.17134] and later |
./Vendor/MSFT/AssignedAccess/Status
This read only node contains kiosk health event xml.
This allows MDM server to query the current KioskModeAppRuntimeStatus as long as the StatusConfiguration node is set to "On" or "OnWithAlerts". If the StatusConfiguration is "Off", a "node not found" error will be reported to the MDM server.
Starting in Windows 10, version 1809, Assigned Access runtime status supports monitoring single-app kiosk and multi-app modes. Here are the possible status codes:
| Status Code | Status | Description |
|---|---|---|
| 0 | Unknown | Unknown status. |
| 1 | Running | The AssignedAccess account (kiosk or multi-app) is running normally. |
| 2 | AppNotFound | The kiosk app isn't deployed to the machine. |
| 3 | ActivationFailed | The AssignedAccess account (kiosk or multi-app) failed to sign in. |
| 4 | AppNoResponse | The kiosk app launched successfully but is now unresponsive. |
Additionally, the Status payload includes the following fields:
- profileId: It can be used by the MDM server to correlate which account caused the error.
- OperationList: It gives the list of failed operations that occurred while applying the assigned access CSP, if any exist.
Description framework properties:
| Property name | Property value |
|---|---|
| Format | chr (string) |
| Access Type | Get |
AssignedAccessAlert XSD:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema
elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://schemas.microsoft.com/AssignedAccess/2018/AssignedAccessAlert"
xmlns:default="http://schemas.microsoft.com/AssignedAccess/2018/AssignedAccessAlert"
targetNamespace="http://schemas.microsoft.com/AssignedAccess/2018/AssignedAccessAlert"
>
<xs:simpleType name="status_t">
<xs:restriction base="xs:int">
<xs:enumeration value="0"/> <!-- Unknown -->
<xs:enumeration value="1"/> <!-- Running -->
<xs:enumeration value="2"/> <!-- AppNotFound -->
<xs:enumeration value="3"/> <!-- ActivationFailed -->
<xs:enumeration value="4"/> <!-- AppNoResponse -->
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="guid_t">
<xs:restriction base="xs:string">
<xs:pattern value="\{[0-9a-fA-F]{8}\-([0-9a-fA-F]{4}\-){3}[0-9a-fA-F]{12}\}"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="operation_t">
<xs:sequence minOccurs="1" maxOccurs="1">
<xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="errorCode" type="xs:int" minOccurs="1" maxOccurs="1"/>
<xs:element name="data" type="xs:string" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="operationlist_t">
<xs:sequence minOccurs="1" maxOccurs="1">
<xs:element name="Operation" type="operation_t" minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="event_t">
<xs:sequence minOccurs="1" maxOccurs="1">
<xs:element name="status" type="status_t" minOccurs="1" maxOccurs="1"/>
<xs:element name="profileId" type="guid_t" minOccurs="1" maxOccurs="1"/>
<xs:element name="errorCode" type="xs:int" minOccurs="0" maxOccurs="1"/>
<xs:element name="OperationList" type="operationlist_t" minOccurs="0" maxOccurs="1"/>
</xs:sequence>
<xs:attribute name="Name" type="xs:string" use="required"/>
</xs:complexType>
<xs:element name="Events">
<xs:complexType>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element name="Event" type="event_t" minOccurs="1" maxOccurs="1"/>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>
Example:
<SyncML xmlns='SYNCML:SYNCML1.2'>
<SyncBody>
<Get>
<CmdID>2</CmdID>
<Item>
<Target>
<LocURI>./Device/Vendor/MSFT/AssignedAccess/Status</LocURI>
</Target>
</Item>
</Get>
<Final />
</SyncBody>
</SyncML>
StatusConfiguration
| Scope | Editions | Applicable OS |
|---|---|---|
| ✅ Device ❌ User |
✅ Pro ✅ Enterprise ✅ Education ✅ Windows SE ✅ IoT Enterprise / IoT Enterprise LTSC |
✅ Windows 10, version 1803 [10.0.17134] and later |
./Vendor/MSFT/AssignedAccess/StatusConfiguration
This node accepts a StatusConfiguration xml as input.
There are three possible values for StatusEnabled node inside StatusConfiguration xml:
- On
- OnWithAlerts
- Off
By default, the StatusConfiguration node doesn't exist, and it implies this feature is off. Once enabled via CSP, Assigned Access will check kiosk app status and wait for MDM server to query the latest status from the Status node. Optionally, the MDM server can opt in to the MDM alert so that an MDM alert will be generated and sent immediately to the MDM server when the assigned access runtime status is changed. This MDM alert will contain the status payload that is available via the Status node. This MDM alert header is defined as follows:
- MDMAlertMark:
Critical - MDMAlertType:
com.microsoft.mdm.assignedaccess.status - MDMAlertDataType:
string - Source:
./Vendor/MSFT/AssignedAccess - Target:
N/A
Note
MDM alert are only sent for errors.
Description framework properties:
| Property name | Property value |
|---|---|
| Format | chr (string) |
| Access Type | Add, Delete, Get, Replace |
StatusConfiguration XSD:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema
elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://schemas.microsoft.com/AssignedAccess/2018/StatusConfiguration"
xmlns:default="http://schemas.microsoft.com/AssignedAccess/2018/StatusConfiguration"
targetNamespace="http://schemas.microsoft.com/AssignedAccess/2018/StatusConfiguration"
>
<xs:simpleType name="status_enabled_t">
<xs:restriction base="xs:string">
<xs:enumeration value="Off"/>
<xs:enumeration value="On"/>
<xs:enumeration value="OnWithAlerts"/>
</xs:restriction>
</xs:simpleType>
<!--below is the definition of the config xml content-->
<xs:element name="StatusConfiguration">
<xs:complexType>
<xs:sequence minOccurs="1" maxOccurs="1">
<xs:element name="StatusEnabled" type="status_enabled_t" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Examples:
Add StatusConfiguration with StatusEnabled set to OnWithAlerts
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Add> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/StatusConfiguration</LocURI> </Target> <Meta> <Format xmlns="syncml:metinf">chr</Format> </Meta> <Data> <![CDATA[ <?xml version="1.0" encoding="utf-8" ?> <StatusConfiguration xmlns="http://schemas.microsoft.com/AssignedAccess/2018/StatusConfiguration"> <StatusEnabled>OnWithAlerts</StatusEnabled> </StatusConfiguration> ]]> </Data> </Item> </Add> <Final /> </SyncBody> </SyncML>Delete StatusConfiguration
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Delete> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/StatusConfiguration</LocURI> </Target> </Item> </Delete> <Final /> </SyncBody> </SyncML>Get StatusConfiguration
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Get> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/StatusConfiguration</LocURI> </Target> </Item> </Get> <Final /> </SyncBody> </SyncML>Replace StatusEnabled value with On
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Replace> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/StatusConfiguration</LocURI> </Target> <Meta> <Format xmlns="syncml:metinf">chr</Format> </Meta> <Data> <![CDATA[ <?xml version="1.0" encoding="utf-8" ?> <StatusConfiguration xmlns="http://schemas.microsoft.com/AssignedAccess/2018/StatusConfiguration"> <StatusEnabled>On</StatusEnabled> </StatusConfiguration> ]]> </Data> </Item> </Replace> <Final /> </SyncBody> </SyncML>
AssignedAccessConfiguration XSD
Here's the Assigned Access XSD reference article: Assigned Access XML Schema Definition (XSD).
For practical examples of Assigned Access configuration files, see Assigned Access examples.
Handling XML in Configuration
XML encoding (escaped) and CDATA of the XML in the Data node will both ensure that DM client can properly interpret the SyncML and send the configuration xml as string (in original format, unescaped) to AssignedAccess CSP to handle.
Similarly, the StartLayout xml inside the configuration xml is using the same format, xml inside xml as string. In the sample Configuration xml provided above, CDATA is used to embed the StartLayout xml. If you use CDATA to embed configuration xml in SyncML as well, you have nested CDATA, so pay attention to how CDATA is used in the provided CDATA sample. With that being said, when the Configuration xml is being constructed, MDM server can either escape start layout xml or put startlayout xml inside CDATA, when MDM server puts configuration xml inside SyncML, MDM server can also either escape it or wrap with CDATA.
Escape and CDATA are mechanisms used when handling xml in xml. Consider that it's a transportation channel to send the configuration xml as payload from server to client. It's transparent to both, the end user who configures the CSP and to our CSP. Both the customer on the server side and our CSP must only see the original configuration XML.
This example shows escaped XML of the Data node.
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Add> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/Configuration</LocURI> </Target> <Meta> <Format xmlns="syncml:metinf">chr</Format> </Meta> <Data> <?xml version="1.0" encoding="utf-8" ?> <AssignedAccessConfiguration xmlns="http://schemas.microsoft.com/AssignedAccess/2017/config"> <Profiles> <Profile Id="{9A2A490F-10F6-4764-974A-43B19E722C23}"> <AllAppsList> <AllowedApps> <App DesktopAppPath="C:\Windows\System32\notepad.exe" /> </AllowedApps> </AllAppsList> <StartLayout> <![CDATA[<LayoutModificationTemplate xmlns:defaultlayout="http://schemas.microsoft.com/Start/2014/FullDefaultLayout" xmlns:start="http://schemas.microsoft.com/Start/2014/StartLayout" Version="1" xmlns="http://schemas.microsoft.com/Start/2014/LayoutModification"> <LayoutOptions StartTileGroupCellWidth="6" /> <DefaultLayoutOverride> <StartLayoutCollection> <defaultlayout:StartLayout GroupCellWidth="6"> <start:Group Name="Group1"> <start:Tile Size="4x4" Column="0" Row="0" AppUserModelID="Microsoft.ZuneMusic_8wekyb3d8bbwe!Microsoft.ZuneMusic" /> </start:Group> </defaultlayout:StartLayout> </StartLayoutCollection> </DefaultLayoutOverride> </LayoutModificationTemplate> ]]> </StartLayout> <Taskbar ShowTaskbar="true"/> </Profile> </Profiles> <Configs> <Config> <Account>MultiAppKioskUser</Account> <DefaultProfile Id="{9A2A490F-10F6-4764-974A-43B19E722C23}"/> </Config> </Configs> </AssignedAccessConfiguration> </Data> </Item> </Add> <Final /> </SyncBody> </SyncML>
This example shows CData for the XML.
<SyncML xmlns='SYNCML:SYNCML1.2'> <SyncBody> <Add> <CmdID>2</CmdID> <Item> <Target> <LocURI>./Device/Vendor/MSFT/AssignedAccess/Configuration</LocURI> </Target> <Meta> <Format xmlns="syncml:metinf">chr</Format> </Meta> <Data> <![CDATA[<?xml version="1.0" encoding="utf-8" ?> <AssignedAccessConfiguration xmlns="http://schemas.microsoft.com/AssignedAccess/2017/config"> <Profiles> <Profile Id="{9A2A490F-10F6-4764-974A-43B19E722C23}"> <AllAppsList> <AllowedApps> <App DesktopAppPath="C:\Windows\System32\notepad.exe" /> </AllowedApps> </AllAppsList> <StartLayout> <![CDATA[<LayoutModificationTemplate xmlns:defaultlayout="http://schemas.microsoft.com/Start/2014/FullDefaultLayout" xmlns:start="http://schemas.microsoft.com/Start/2014/StartLayout" Version="1" xmlns="http://schemas.microsoft.com/Start/2014/LayoutModification"> <LayoutOptions StartTileGroupCellWidth="6" /> <DefaultLayoutOverride> <StartLayoutCollection> <defaultlayout:StartLayout GroupCellWidth="6"> <start:Group Name="Group1"> <start:Tile Size="4x4" Column="0" Row="0" AppUserModelID="Microsoft.ZuneMusic_8wekyb3d8bbwe!Microsoft.ZuneMusic" /> </start:Group> <start:Group Name="Group2"> <start:DesktopApplicationTile Size="2x2" Column="2" Row="0" DesktopApplicationID="{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\mspaint.exe" /> <start:DesktopApplicationTile Size="2x2" Column="0" Row="0" DesktopApplicationID="{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\notepad.exe" /> </start:Group> </defaultlayout:StartLayout> </StartLayoutCollection> </DefaultLayoutOverride> </LayoutModificationTemplate> ]]]]><![CDATA[> </StartLayout> <Taskbar ShowTaskbar="true"/> </Profile> </Profiles> <Configs> <Config> <Account>MultiAppKioskUser</Account> <DefaultProfile Id="{9A2A490F-10F6-4764-974A-43B19E722C23}"/> </Config> </Configs> </AssignedAccessConfiguration> ]]> </Data> </Item> </Add> <Final /> </SyncBody> </SyncML>