mirror of
https://github.com/apple/device-management.git
synced 2026-05-26 19:02:27 +02:00
Cyrus Daboo
235 lines
8.0 KiB
YAML
235 lines
8.0 KiB
YAML
title: Token Update
|
|
description: Updates the token for a device on the server.
|
|
payload:
|
|
requesttype: TokenUpdate
|
|
supportedOS:
|
|
iOS:
|
|
introduced: '4.0'
|
|
supervised: false
|
|
requiresdep: false
|
|
sharedipad:
|
|
mode: allowed
|
|
devicechannel: true
|
|
userchannel: true
|
|
userenrollment:
|
|
mode: allowed
|
|
macOS:
|
|
introduced: '10.7'
|
|
devicechannel: true
|
|
userchannel: true
|
|
supervised: false
|
|
requiresdep: false
|
|
userenrollment:
|
|
mode: allowed
|
|
tvOS:
|
|
introduced: '10.2'
|
|
supervised: false
|
|
visionOS:
|
|
introduced: '1.1'
|
|
supervised: false
|
|
requiresdep: false
|
|
userenrollment:
|
|
mode: allowed
|
|
watchOS:
|
|
introduced: '10.0'
|
|
supervised: false
|
|
content: Check-in protocol token update request and response.
|
|
payloadkeys:
|
|
- key: NotOnConsole
|
|
supportedOS:
|
|
iOS:
|
|
introduced: n/a
|
|
macOS:
|
|
introduced: '10.11'
|
|
devicechannel: false
|
|
visionOS:
|
|
introduced: n/a
|
|
watchOS:
|
|
introduced: n/a
|
|
type: <boolean>
|
|
presence: required
|
|
content: If `true`, the device isn't on-console.
|
|
- key: MessageType
|
|
type: <string>
|
|
presence: required
|
|
rangelist:
|
|
- TokenUpdate
|
|
content: The message type, which requires a value of `TokenUpdate`.
|
|
- key: Topic
|
|
type: <string>
|
|
presence: required
|
|
content: The topic the device subscribes to.
|
|
- key: UDID
|
|
supportedOS:
|
|
iOS:
|
|
userenrollment:
|
|
mode: forbidden
|
|
macOS:
|
|
userenrollment:
|
|
mode: forbidden
|
|
visionOS:
|
|
userenrollment:
|
|
mode: forbidden
|
|
type: <string>
|
|
presence: required
|
|
content: The device's UDID (unique device identifier). The system requires this
|
|
value if the enrollment type is a device enrollment.
|
|
- key: EnrollmentID
|
|
supportedOS:
|
|
iOS:
|
|
introduced: '13.0'
|
|
userenrollment:
|
|
mode: required
|
|
macOS:
|
|
introduced: '10.15'
|
|
userenrollment:
|
|
mode: required
|
|
tvOS:
|
|
introduced: n/a
|
|
visionOS:
|
|
userenrollment:
|
|
mode: required
|
|
watchOS:
|
|
introduced: n/a
|
|
type: <string>
|
|
presence: required
|
|
content: |-
|
|
The per-enrollment identifier for the device. The system requires this value if the enrollment type is a user enrollment.
|
|
|
|
Available in iOS 13 and later, macOS 10.15 and later, and visionOS 2 and later.
|
|
- key: EnrollmentUserID
|
|
supportedOS:
|
|
iOS:
|
|
introduced: n/a
|
|
macOS:
|
|
introduced: '10.15'
|
|
devicechannel: false
|
|
userenrollment:
|
|
mode: required
|
|
tvOS:
|
|
introduced: n/a
|
|
visionOS:
|
|
introduced: n/a
|
|
watchOS:
|
|
introduced: n/a
|
|
type: <string>
|
|
presence: required
|
|
content: |-
|
|
The per-enrollment identifier for the user. The system requires this value if the enrollment type is a user enrollment on the user channel.
|
|
|
|
Available in macOS 10.15 and later.
|
|
- key: UserShortName
|
|
supportedOS:
|
|
iOS:
|
|
introduced: '9.3'
|
|
sharedipad:
|
|
mode: required
|
|
macOS:
|
|
devicechannel: false
|
|
tvOS:
|
|
introduced: n/a
|
|
visionOS:
|
|
introduced: n/a
|
|
watchOS:
|
|
introduced: n/a
|
|
type: <string>
|
|
presence: optional
|
|
content: |-
|
|
For macOS, this value is the short name of the user.
|
|
|
|
For Shared iPad, this value is the Managed Apple Account identifier of the user on Shared iPad. It indicates that the token is for the user channel.
|
|
- key: UserID
|
|
supportedOS:
|
|
iOS:
|
|
introduced: '9.3'
|
|
sharedipad:
|
|
mode: required
|
|
macOS:
|
|
devicechannel: false
|
|
tvOS:
|
|
introduced: n/a
|
|
visionOS:
|
|
introduced: n/a
|
|
watchOS:
|
|
introduced: n/a
|
|
type: <string>
|
|
presence: optional
|
|
content: |-
|
|
For macOS, this value is the ID of the user.
|
|
|
|
For Shared iPad, this value is `FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF` to indicate that authentication doesn't occur.
|
|
- key: UserLongName
|
|
supportedOS:
|
|
iOS:
|
|
introduced: n/a
|
|
macOS:
|
|
devicechannel: false
|
|
tvOS:
|
|
introduced: n/a
|
|
visionOS:
|
|
introduced: n/a
|
|
watchOS:
|
|
introduced: n/a
|
|
type: <string>
|
|
presence: required
|
|
content: The full name of the user.
|
|
- key: Token
|
|
type: <data>
|
|
presence: required
|
|
content: The push token for the device.
|
|
- key: PushMagic
|
|
type: <string>
|
|
presence: required
|
|
content: The magic string to include in the push notification message.
|
|
- key: UnlockToken
|
|
supportedOS:
|
|
iOS:
|
|
accessrights: AllowPasscodeRemovalAndLock
|
|
sharedipad:
|
|
mode: forbidden
|
|
userenrollment:
|
|
mode: forbidden
|
|
macOS:
|
|
introduced: n/a
|
|
visionOS:
|
|
accessrights: AllowPasscodeRemovalAndLock
|
|
userenrollment:
|
|
mode: forbidden
|
|
watchOS:
|
|
accessrights: AllowPasscodeRemovalAndLock
|
|
type: <data>
|
|
presence: optional
|
|
content: The data to use to unlock the device. If provided, the server needs to
|
|
retain this data and send it when trying to implement `Clear-Passcode-Command`.
|
|
- key: AwaitingConfiguration
|
|
supportedOS:
|
|
iOS:
|
|
introduced: '9.0'
|
|
macOS:
|
|
introduced: '10.11'
|
|
userchannel: false
|
|
watchOS:
|
|
introduced: n/a
|
|
type: <boolean>
|
|
presence: optional
|
|
default: false
|
|
content: |-
|
|
If `true` from the device channel, the device is awaiting a `Device-Configured-Command` command before proceeding through Setup Assistant.
|
|
|
|
If `true` from the user channel (Shared iPad only), the device is awaiting a `User-Configured-Command` command before proceeding through Setup Assistant.
|
|
notes:
|
|
- title: ''
|
|
content: |-
|
|
The device sends an initial `TokenUpdate` message to the server when it installs the MDM payload. The server needs to send push messages to the device only after receiving the first `TokenUpdate` message. If the device reports that it is `AwaitingConfiguration`, the MDM server needs to send a `Device-Configured-Command` MDM command before the device allows the user to proceed in Setup Assistant. This gives the MDM server the opportunity to perform some setup using MDM commands.
|
|
|
|
In addition to sending the initial `TokenUpdate` message, the device may send additional `TokenUpdate` messages to the check-in server at any time while it has a valid MDM enrollment.
|
|
|
|
The use of `PushMagic` constrains the device to a unique MDM relationship. When a user removes the MDM profile, the device no longer listens to the former relationship, even if the user reestablishes a management relationship with the same server topic. Note that only the push topic is the same in this case; the server's address might change. This also helps when a user restores a device from backup that contains an older relationship. The use of `PushMagic` also ensures that the same organization owns both the server that receives the `CheckIn` message and the computer sending the push notifications. This is important because there's no way of knowing if the push topic belongs to the owner of the check-in server. It's conceivable that Apple might revoke a push token for one party, only to have that party reenroll people from some other topic that's actively pushing. The fact that all MDM push topics reside in the namespace `com.apple.mgmt.*` helps prevent this.
|
|
|
|
The `PushMagic` or `UnlockToken` fields of subsequent `TokenUpdate` messages may be identical to those in previous messages, or may be different (and may differ in size from previous values). If different, the server needs to update its record for the device to the new values in the message. Failure to do so results in the server being unable to send push notifications or perform passcode resets.
|
|
|
|
Although a device can send the `TokenUpdate` message multiple times, it might send it only once if the values in the message never change. Ensure your implementation doesn't rely on repeated messages to update lost server-side data or to recover from a failure to process a previous `TokenUpdate` message. Also note that `UnlockToken` is optional. Don't treat the absence of an `UnlockToken` in a `TokenUpdate` message as an invalidation of a previously received `UnlockToken`.
|
|
|
|
> Note:
|
|
> The topic string for the MDM check-in protocol needs to start with `com.apple.mgmt.*` where `*` is a unique suffix.
|