apple_device-management/declarative/declarations/configurations/passcode.settings.yaml

title: Passcode:Settings
description: The declaration to configure passcode policy settings.
payload:
  declarationtype: com.apple.configuration.passcode.settings
  supportedOS:
    iOS:
      introduced: '15.0'
      allowed-enrollments:
      - supervised
      - device
      - user
      - local
      allowed-scopes:
      - system
      sharedipad:
        allowed-scopes: []
    macOS:
      introduced: '13.0'
      allowed-enrollments:
      - supervised
      - local
      allowed-scopes:
      - system
      - user
    tvOS:
      introduced: n/a
    visionOS:
      introduced: '2.0'
      allowed-enrollments:
      - supervised
      - device
      - user
      - local
      allowed-scopes:
      - system
    watchOS:
      introduced: '10.0'
      allowed-enrollments:
      - supervised
      - local
      allowed-scopes:
      - system
  apply: combined
payloadkeys:
- key: RequirePasscode
  title: Require Passcode on Device
  type: <boolean>
  presence: optional
  default: false
  combinetype: boolean-or
  content: If `true`, the system requires the user to set a passcode without any requirements
    about the length or quality of the passcode. The presence of any other keys implicitly
    requires a passcode, and overrides this key's value.
- key: RequireAlphanumericPasscode
  title: Require Alphanumeric Passcode
  supportedOS:
    iOS:
      introduced: '16.2'
    macOS:
      introduced: '13.1'
    watchOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  combinetype: boolean-or
  content: If `true`, the passcode needs to consist of at least one alphabetic character
    and at least one number.
- key: RequireComplexPasscode
  title: Require Complex Passcode
  type: <boolean>
  presence: optional
  default: false
  combinetype: boolean-or
  content: If `true`, the system requires a complex passcode. A complex passcode is
    one that doesn't contain repeated characters or increasing or decreasing characters
    (such as 123 or CBA).
- key: MinimumLength
  title: Minimum Passcode Length
  type: <integer>
  presence: optional
  range:
    min: 0
    max: 16
  default: 0
  combinetype: number-max
  content: The minimum number of characters a passcode can contain.
- key: MinimumComplexCharacters
  title: Minimum Complex Characters
  supportedOS:
    iOS:
      introduced: '16.2'
    macOS:
      introduced: '13.1'
    watchOS:
      introduced: n/a
  type: <integer>
  presence: optional
  range:
    min: 0
    max: 4
  default: 0
  combinetype: number-max
  content: Specifies the minimum number of complex characters in the password. A complex
    character is a character other than a number or a letter, such as `&`, `%`, `$`,
    and `#`.
- key: MaximumFailedAttempts
  title: Maximum Number of Failed Attempts
  type: <integer>
  presence: optional
  range:
    min: 2
    max: 11
  default: 11
  combinetype: number-min
  content: |-
    The number of failed passcode attempts that the system allows the user before it erases or locks the device. After six failed attempts, the device imposes a time delay before the user can enter a passcode again. The time delay increases with each failed attempt. On macOS, set `FailedAttemptsResetInMinutes` to define the time delay. The time delay begins after the sixth attempt, so if `MaximumFailedAttempts` is six or lower, the system has no time delay and triggers the erase or lock as soon as the user exceeds the limit.

    After the final failed attempt, the system locks a macOS device, or securely erases all data and settings from an iOS, visionOS, or watchOS device.
- key: FailedAttemptsResetInMinutes
  title: Failed Attempts Reset
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '13.1'
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  type: <integer>
  presence: optional
  combinetype: number-min
  content: The number of minutes before the login is reset after the maximum number
    of failed attempts. Also set the `MaximumFailedAttempts` key for this to take
    effect.
- key: MaximumGracePeriodInMinutes
  title: Maximum Grace Period
  type: <integer>
  presence: optional
  combinetype: number-min
  content: The maximum period that a user can select, during which the user can unlock
    the device without a passcode. A value of `0` means no grace period, and the device
    requires a passcode immediately. In the absence of this key, the user can select
    any period. In macOS, the system translates this to screensaver settings.
- key: MaximumInactivityInMinutes
  title: Automatic Device Lock
  type: <integer>
  presence: optional
  range:
    min: 0
    max: 15
  combinetype: number-min
  content: The maximum period that a user can select, during which the device can
    be idle before the system automatically locks it. When the device reaches this
    limit, the device locks and the user must enter the passcode to unlock it. In
    the absence of this key, the user can select any period. In macOS, the system
    translates this to screensaver settings.
- key: MaximumPasscodeAgeInDays
  title: Maximum Passcode Age
  supportedOS:
    iOS:
      introduced: '16.2'
    macOS:
      introduced: '13.1'
  type: <integer>
  presence: optional
  range:
    min: 0
    max: 730
  combinetype: number-min
  content: Specifies the maximum number of days that the passcode can remain unchanged.
    After this number of days, the system forces the user to change the passcode before
    it unlocks the device.
- key: PasscodeReuseLimit
  title: Passcode Reuse Limit
  type: <integer>
  presence: optional
  range:
    min: 1
    max: 50
  combinetype: number-min
  content: The number of historical passcode entries the system checks when validating
    a new passcode. The device refuses a new passcode if it matches a previously used
    passcode within the specified passcode history range. In the absence of this key,
    the system performs no historical check.
- key: ChangeAtNextAuth
  title: Change At Next Auth
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '13.1'
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  combinetype: boolean-or
  content: If `true`, the system forces a password reset the next time the user tries
    to authenticate. If you set this key in a configuration in the system scope (device
    channel), the setting takes effect for all users, and admin authentication may
    fail until the admin user password is also reset.
- key: CustomRegex
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '14.0'
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  type: <dictionary>
  presence: optional
  content: Specifies a regular expression, and its description, to enforce password
    compliance. Use the simpler passcode settings whenever possible, and rely on regular
    expression matching only when necessary. Mistakes in regular expressions can lead
    to frustrating user experiences, such as unsatisfiable passcode policies, or policy
    descriptions that don't match the enforced policy.
  subkeys:
  - key: Regex
    type: <string>
    presence: required
    content: A regular expression string to match against the password to determine
      whether it complies with a policy. The regular expression uses the ICU syntax.
      The string can't exceed 2048 characters in length.
  - key: Description
    type: <dictionary>
    presence: optional
    content: A dictionary with supported OS language IDs for the keys (such as `en-US`),
      and values that represent a localized description of the policy that the regular
      expression enforces. Use the special `default` key for languages that the dictionary
      doesn't contain.
    subkeys:
    - key: ANY
      type: <string>
      presence: optional
      content: A localized description.
related-status-items:
- status-items:
  - passcode.is-compliant
  - passcode.is-present
  note: This configuration may affect the corresponding status items.
notes:
- title: ''
  content: |-
    The presence of this configuration type causes the device to present the user with a passcode entry mechanism. The configuration controls the complexity of the passcode.

    For user enrollments, the system allows this configuration type, but ignores most of the keys. Instead, the presence of the configuration forces only these settings:

    - `RequirePasscode`: always set to `true`
    - `RequireComplexPasscode`: always set to `true`
    - `MinimumLength`: always set to `6`
    - `MaximumInactivityInMinutes`: if this key is present its value is ignored, but the `never` option is removed in the Settings UI.