apple_device-management/declarative/declarations/configurations/account.exchange.yaml

title: Account:Exchange
description: The declaration to configure an Exchange account.
payload:
  declarationtype: com.apple.configuration.account.exchange
  supportedOS:
    iOS:
      introduced: '15.0'
      allowed-enrollments:
      - supervised
      - device
      - user
      - local
      allowed-scopes:
      - system
      sharedipad:
        allowed-scopes:
        - user
    macOS:
      introduced: '13.0'
      allowed-enrollments:
      - supervised
      - user
      - local
      allowed-scopes:
      - user
    tvOS:
      introduced: n/a
    visionOS:
      introduced: '1.1'
      allowed-enrollments:
      - supervised
      - device
      - user
      - local
      allowed-scopes:
      - system
    watchOS:
      introduced: n/a
  apply: multiple
payloadkeys:
- key: VisibleName
  title: Account name
  type: <string>
  presence: optional
  content: The name that apps show to the user for this Exchange account. If not present,
    the system generates a suitable default.
- key: EnabledProtocolTypes
  title: Enabled protocol types
  type: <array>
  presence: required
  content: |-
    The set of protocol types to enable on the Exchange server, in order of preference. This is an array of unique strings with possible values:

    - `EAS:` Exchange ActiveSync
    - `EWS:` Exchange Web Services

    If the device supports one or more of the listed protocol types, it sets up an account for the first supported type.

    If the device doesn't support any of the listed protocol types, it doesn't set up an account and the system reports an error.
  subkeys:
  - key: EnabledProtocolTypesItem
    type: <string>
    presence: required
    rangelist:
    - EAS
    - EWS
- key: UserIdentityAssetReference
  title: User identity asset reference
  type: <string>
  assettypes:
  - com.apple.asset.useridentity
  presence: optional
  content: The identifier of an asset declaration that contains the user identity
    for this account. The corresponding asset must be of type `UserIdentity`.
- key: HostName
  title: Server host name
  type: <string>
  presence: optional
  content: The IP address or fully qualified domain name (FQDN) of the Exchange host.
- key: Port
  title: Server port
  supportedOS:
    iOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <integer>
  presence: optional
  content: The port number of the EWS server. The system uses this only when this
    declaration has a `HostName` value. Applicable for "EWS" only.
- key: Path
  title: Server path
  supportedOS:
    iOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The path of the EWS server. The system uses this only when this declaration
    has a `HostName` value. Applicable for "EWS" only.
- key: ExternalHostName
  title: Server external host name
  supportedOS:
    iOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The external hostname of the EWS server (or IP address). Applicable for
    "EWS" only.
- key: ExternalPort
  title: Server external port
  supportedOS:
    iOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <integer>
  presence: optional
  content: The external port number of the EWS server. The system uses this only when
    this declaration has an `ExternalHostName` value. Applicable for "EWS" only.
- key: External Path
  title: Server external path
  supportedOS:
    iOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The external path of the EWS server. The system uses this only when this
    declaration has an `ExternalHostName` value. Applicable for "EWS" only.
- key: OAuth
  title: Controls use of OAuth
  type: <dictionary>
  presence: optional
  content: The configuration settings for OAuth for this account.
  subkeys:
  - key: Enabled
    title: Use OAuth
    type: <boolean>
    presence: required
    content: If `true`, enables OAuth for this account.
  - key: SignInURL
    title: Sign in URL
    type: <string>
    presence: optional
    content: The URL that this account uses for signing in with OAuth. The system
      ignores this value unless `Enabled` is `true`. The system doesn't use autodiscovery
      when a declaration contains this URL, so the declaration must also contain a
      `HostName`.
  - key: TokenRequestURL
    title: Token request URL
    supportedOS:
      macOS:
        introduced: n/a
    type: <string>
    presence: optional
    content: The URL that this account uses for token requests with OAuth. The system
      ignores this value unless `Enabled` is `true`. Applicable for "EAS" only.
- key: AuthenticationCredentialsAssetReference
  title: Authentication credentials asset reference
  type: <string>
  assettypes:
  - com.apple.asset.credential.userpassword
  presence: optional
  content: The identifier of an asset declaration that contains the credentials for
    this account to authenticate with an Exchange server. Set the corresponding asset
    type to `CredentialUserNameAndPassword`.
- key: AuthenticationIdentityAssetReference
  title: Authentication identity asset reference
  type: <string>
  assettypes:
  - com.apple.asset.credential.acme
  - com.apple.asset.credential.identity
  - com.apple.asset.credential.scep
  presence: optional
  content: The identifier of a credential asset declaration that contains the identity
    that this account requires to authenticate with the Exchange server.
- key: SMIME
  title: S/MIME settings
  supportedOS:
    iOS:
      introduced: '17.0'
    macOS:
      introduced: n/a
  type: <dictionary>
  presence: optional
  content: Settings for S/MIME. Applicable for "EAS" only.
  subkeys:
  - key: Signing
    title: S/MIME signing settings
    type: <dictionary>
    presence: optional
    content: Settings for S/MIME signing. Applicable for "EAS" only.
    subkeys:
    - key: Enabled
      title: Signing enabled
      type: <boolean>
      presence: required
      content: If `true`, the system enables S/MIME signing. Applicable for "EAS"
        only.
    - key: IdentityAssetReference
      title: S/MIME signing identity asset reference
      type: <string>
      assettypes:
      - com.apple.asset.credential.acme
      - com.apple.asset.credential.identity
      - com.apple.asset.credential.scep
      presence: optional
      content: The identifier of an asset declaration containing the identity required
        for S/MIME signing of messages sent from this account. Applicable for "EAS"
        only.
    - key: UserOverrideable
      title: Signing user overrideable
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the user can turn S/MIME signing on or off in Settings.
        Applicable for "EAS" only.
    - key: IdentityUserOverrideable
      title: Signing identity user overrideable
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the user can select an S/MIME signing identity in Settings.
        Applicable for "EAS" only.
  - key: Encryption
    title: S/MIME encryption settings
    type: <dictionary>
    presence: optional
    content: Settings for S/MIME encryption. Applicable for "EAS" only.
    subkeys:
    - key: Enabled
      title: Encryption by default enabled
      type: <boolean>
      presence: required
      content: If `true`, the system enables S/MIME encryption by default, which the
        user can't override if `PerMessageSwitchEnabled` is `false`. Applicable for
        "EAS" only.
    - key: IdentityAssetReference
      title: S/MIME encryption identity asset reference
      type: <string>
      assettypes:
      - com.apple.asset.credential.acme
      - com.apple.asset.credential.identity
      - com.apple.asset.credential.scep
      presence: optional
      content: The identifier of an asset declaration containing the identity required
        for S/MIME encryption. The system attaches the public certificate to outgoing
        mail to allow the user to receive encrypted mail. When the user sends encrypted
        mail, the system uses the public certificate to encrypt the copy of the mail
        in their Sent mailbox. Applicable for "EAS" only.
    - key: UserOverrideable
      title: Encryption by default user overrideable
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the user can turn S/MIME encryption by default on or off
        in Settings. Applicable for "EAS" only.
    - key: IdentityUserOverrideable
      title: Encryption identity user overrideable
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the user can select an S/MIME signing identity in Settings.
        Applicable for "EAS" only.
    - key: PerMessageSwitchEnabled
      title: Per message switch enabled
      type: <boolean>
      presence: optional
      default: false
      content: If `true`, the system enables the per-message encryption switch in
        the compose view. Applicable for "EAS" only.
- key: MailServiceActive
  title: Mail service active
  type: <boolean>
  presence: optional
  default: true
  content: If `true`, the system activates the mail service for this account.
- key: LockMailService
  title: Lock mail service
  supportedOS:
    macOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the system prevents the user from changing the status of the
    mail service for this account. Applicable for "EAS" only.
- key: ContactsServiceActive
  title: Contacts service active
  type: <boolean>
  presence: optional
  default: true
  content: If `true`, activates the address book service for this account.
- key: LockContactsService
  title: Lock contacts service
  supportedOS:
    macOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the system prevents the user from changing the status of the
    address book service for this account. Applicable for "EAS" only.
- key: CalendarServiceActive
  title: Calendar service active
  type: <boolean>
  presence: optional
  default: true
  content: If `true`, activates the calendar service for this account.
- key: LockCalendarService
  title: Lock calendar service
  supportedOS:
    macOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the system prevents the user from changing the status of the
    calendar service for this account. Applicable for "EAS" only.
- key: RemindersServiceActive
  title: Reminders service active
  type: <boolean>
  presence: optional
  default: true
  content: If `true`, the system activates the reminders service for this account.
- key: LockRemindersService
  title: Lock reminders service
  supportedOS:
    macOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the system prevents the user from changing the status of the
    reminders service for this account. Applicable for "EAS" only.
- key: NotesServiceActive
  title: Notes service active
  type: <boolean>
  presence: optional
  default: true
  content: If `true`, the system activates the notes service for this account.
- key: LockNotesService
  title: Lock notes service
  supportedOS:
    macOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the system prevents the user from changing the status of the
    notes service for this account. Applicable for "EAS" only.
related-status-items:
- status-items:
  - account.list.exchange
  note: Each configuration will have a corresponding status item.
examples:
- title: Configuration example
  files:
  - description: This configuration sets up a Microsoft Exchange account.
    file: examples/declarative/declarations/configurations/account.exchange/example1.json