title: Extensible Single Sign-On
description: The payload that configures an app extension that performs single sign-on
  (SSO).
payload:
  payloadtype: com.apple.extensiblesso
  supportedOS:
    iOS:
      introduced: '13.0'
      multiple: true
      supervised: false
      allowmanualinstall: false
      sharedipad:
        mode: allowed
        devicechannel: false
        userchannel: true
      userenrollment:
        mode: allowed
    macOS:
      introduced: '10.15'
      multiple: true
      devicechannel: true
      userchannel: true
      supervised: false
      requiresdep: false
      userapprovedmdm: true
      allowmanualinstall: false
      userenrollment:
        mode: allowed
    tvOS:
      introduced: n/a
    visionOS:
      introduced: '1.1'
      multiple: true
      supervised: false
      allowmanualinstall: false
      userenrollment:
        mode: allowed
    watchOS:
      introduced: n/a
  content: Configures an app extension that performs SSO on behalf of certain URLs.
    User channel support was added in macOS 11.0.
payloadkeys:
- key: ExtensionIdentifier
  type: <string>
  presence: required
  content: The bundle identifier of the app extension that performs SSO for the specified
    URLs.
- key: TeamIdentifier
  supportedOS:
    iOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The team identifier of the app extension. This key is required on macOS
    and ignored elsewhere.
- key: Type
  type: <string>
  presence: required
  rangelist:
  - Credential
  - Redirect
  content: The type of SSO.
- key: Realm
  type: <string>
  presence: optional
  content: The realm name for `Credential` payloads. Use proper capitalization for
    this value. Ignored for `Redirect` payloads.
- key: ExtensionData
  type: <dictionary>
  presence: optional
  content: A dictionary of arbitrary data passed through to the app extension.
  subkeys:
  - key: ANY
    type: <any>
    presence: optional
    content: Keys and values to pass to the app extension.
- key: URLs
  type: <array>
  presence: optional
  content: |-
    An array of URL prefixes of identity providers where the app extension performs SSO.

    Required for `Redirect` payloads. Ignored for `Credential` payloads.

    The URLs need to begin with `http://` or `https://`.

    The system:

    - Matches scheme and host name case-insensitively
    - Doesn't allow query parameters and URL fragments
    - Requires that the URLs of all installed Extensible SSO payloads are unique
  subkeys:
  - key: URL
    type: <string>
    presence: required
    content: An http or https URL prefix.
- key: Hosts
  type: <array>
  presence: optional
  content: |-
    An array of host or domain names that apps can authenticate through the app extension.

    Required for `Credential` payloads. Ignored for `Redirect` payloads.

    The system:

    - Matches host or domain names case-insensitively
    - Requires that all the host and domain names of all installed Extensible SSO payloads are unique

    > Note:
    > Host names that begin with a "." are wildcard suffixes that match all subdomains; otherwise the host name needs be an exact match.
  subkeys:
  - key: hostname
    type: <string>
    presence: required
    content: A host or domain name, with or without a leading dot.
- key: ScreenLockedBehavior
  supportedOS:
    iOS:
      introduced: '15.0'
    macOS:
      introduced: '12.0'
  type: <string>
  presence: optional
  rangelist:
  - Cancel
  - DoNotHandle
  default: Cancel
  content: If set to `Cancel`, the system cancels authentication requests when the
    screen is locked. If set to `DoNotHandle`, the request continues without SSO instead.
    This doesn't apply to requests where `userInterfaceEnabled` is `false`, or for
    background `URLSession` requests. Available in iOS 15 and later, and macOS 12
    and later.
- key: DeniedBundleIdentifiers
  supportedOS:
    iOS:
      introduced: '15.0'
    macOS:
      introduced: '12.0'
  type: <array>
  presence: optional
  content: An array of bundle identifiers of apps that don't use SSO provided by this
    extension. Available in iOS 15 and later, and macOS 12 and later.
  subkeys:
  - key: bundleIdentifier
    type: <string>
    presence: required
    content: The bundle identifier of the app.
- key: AuthenticationMethod
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '13.0'
      deprecated: '14.0'
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  rangelist:
  - Password
  - UserSecureEnclaveKey
  content: The Platform SSO authentication method the extension uses. Requires that
    the SSO Extension also supports the method. Available in macOS 13 and later, and
    deprecated in macOS 14.
- key: RegistrationToken
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '13.0'
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The token this device uses for registration with Platform SSO. Use it for
    silent registration with the Identity Provider. Requires that `AuthenticationMethod`
    in `PlatformSSO` isn't empty. Available in macOS 13 and later.
- key: PlatformSSO
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '14.0'
    visionOS:
      introduced: n/a
  type: <dictionary>
  presence: optional
  content: The dictionary to configure Platform SSO. Requires `Type` to be set to
    `Redirect`.
  subkeys:
  - key: AuthenticationMethod
    type: <string>
    presence: optional
    rangelist:
    - Password
    - UserSecureEnclaveKey
    - SmartCard
    content: The Platform SSO authentication method to use with the extension. Requires
      that the SSO Extension also support the method.
  - key: UseSharedDeviceKeys
    supportedOS:
      macOS:
        userchannel: false
    type: <boolean>
    presence: optional
    default: false
    content: If `true`, the system uses the same signing and encryption keys for all
      users. Only supported on the device channel.
  - key: AccountDisplayName
    type: <string>
    presence: optional
    content: The display name for the account in notifications and authentication
      requests.
  - key: LoginFrequency
    type: <integer>
    presence: optional
    range:
      min: 3600
    default: 64800
    content: The duration, in seconds, until the system requires a full login instead
      of a refresh. The default value is 64,800 (18 hours). The minimum value is 3600
      (1 hour).
  - key: EnableCreateUserAtLogin
    type: <boolean>
    presence: optional
    default: false
    content: Enables creating users at the Login Window with an `AuthenticationMethod`
      of either `Password` or `SmartCard`. Requires that `UseSharedDeviceKeys` is
      `true`.
  - key: EnableCreateFirstUserDuringSetup
    supportedOS:
      macOS:
        introduced: '26.0'
    type: <boolean>
    presence: optional
    default: true
    content: If `true`, the device uses Platform SSO to create the first user account
      on the Mac during `Setup Assistant`.
  - key: EnableAuthorization
    type: <boolean>
    presence: optional
    default: false
    content: Enables using identity provider accounts at authorization prompts. Requires
      that `UseSharedDeviceKeys` is `true`. The system assigns groups using `AdministratorGroups`,
      `AdditionalGroups`, or `AuthorizationGroups`.
  - key: TokenToUserMapping
    type: <dictionary>
    presence: optional
    content: The attribute mapping to use when creating users, or for authorization.
    subkeys:
    - key: AccountName
      type: <string>
      presence: optional
      content: The claim name to use for the user's account name.
    - key: FullName
      type: <string>
      presence: optional
      content: The claim name to use for the user's full name.
  - key: NewUserAuthenticationMethods
    supportedOS:
      macOS:
        introduced: '26.0'
    type: <array>
    presence: optional
    content: The set of authentication methods to use for newly created accounts at
      login or during `Setup Assistant`. The system uses `Password` and `SmartCard`
      if this key isn't present.
    subkeys:
    - key: NewUserAuthenticationMethod
      type: <string>
      presence: optional
      rangelist:
      - Password
      - SmartCard
      - AccessKey
      content: |-
        An authentication method to use for newly created accounts at login or during `Setup Assistant`. Allowed values:

        - `Password`: The account uses a password for authentication.
        - `SmartCard`: The account uses a smart card for authentication.
        - `AccessKey`: The account uses an access key for authentication.
  - key: NewUserAuthorizationMode
    type: <string>
    presence: optional
    rangelist:
    - Standard
    - Admin
    - Groups
    - Temporary
    content: |-
      The permission to apply to newly created accounts at login. Allowed values:

      - `Standard`: The account is a standard user.
      - `Admin`: The system adds the account to the local administrators group.
      - `Groups`: The system assigns groups to the account using `AdministratorGroups`, `AdditionalGroups`, or `AuthorizationGroups`.
      - `Temporary`: The system uses a temporary session configuration for newly created accounts at login.
  - key: UserAuthorizationMode
    type: <string>
    presence: optional
    rangelist:
    - Standard
    - Admin
    - Groups
    content: |-
      The permission to apply to an account each time the user authenticates. Allowed values:

      - `Standard`: The account is a standard user.
      - `Admin`: The system adds the account to the local administrators group.
      - `Groups`: The system assigns group to the account using `AdministratorGroups`, `AdditionalGroups`, or `AuthorizationGroups`.
  - key: AdministratorGroups
    type: <array>
    presence: optional
    content: The list of groups to use for administrator access. The system requests
      membership during authentication.
    subkeys:
    - key: Group
      type: <string>
      presence: optional
      content: The group name.
  - key: AdditionalGroups
    type: <array>
    presence: optional
    content: The list of created groups that don't have administrator access.
    subkeys:
    - key: Group
      type: <string>
      presence: optional
      content: The group name.
  - key: AuthorizationGroups
    type: <dictionary>
    presence: optional
    content: The pairing of Authorization Rights to group names. When using this,
      the system updates the Authorization Right to use the group.
    subkeys:
    - key: ANY
      type: <string>
      presence: optional
      content: The key is an access right value, the value is the group to be associated
        with that access right.
  - key: AccessKeyReaderGroupIdentifier
    supportedOS:
      macOS:
        introduced: '26.0'
    type: <data>
    presence: optional
    content: The reader group identifier for use with the `AccessKey`. The value needs
      to match the configured access key. Required if `NewUserAuthenticationMethods`
      contains `AccessKey`.
  - key: AccessKeyTerminalIdentityUUID
    supportedOS:
      macOS:
        introduced: '26.0'
    type: <string>
    presence: optional
    content: |-
      The `PayloadUUID` of an identity payload to use as the `Terminal` identity of the access key. The identity needs to be trusted by the access key. Required if `NewUserAuthenticationMethods` includes `AccessKey`. Allowed identity payload types:

      - `com.apple.security.pkcs12`
      - `com.apple.security.acme`
      - `com.apple.security.scep`
  - key: AccessKeyReaderIssuerCertificateUUID
    supportedOS:
      macOS:
        introduced: '26.2'
    type: <string>
    presence: optional
    content: The `PayloadUUID` of a certificate payload for the issuer certificate
      of the `Terminal` identity of the access key. Other specifications refer to
      the key as the "Reader CA Public Key". The key must be an elliptic curve key.
      Required if `NewUserAuthenticationMethods` includes `AccessKey`. The issuer
      of the Terminal identity of the access key needs to match this certificate,
      otherwise the device fails the authentication.
  - key: AllowAccessKeyExpressMode
    supportedOS:
      macOS:
        introduced: '26.0'
    type: <boolean>
    presence: optional
    default: false
    content: If `true`, the system uses the access key in express mode, and doesn't
      require authentication before use.
  - key: FileVaultPolicy
    supportedOS:
      macOS:
        introduced: '15.0'
    type: <array>
    presence: optional
    content: The policy to apply when using Platform SSO at FileVault unlock on a
      Mac with Apple silicon. Applies when `AuthenticationMethod` is `Password`. Available
      in macOS 15 and later.
    subkeys:
    - key: policy
      type: <string>
      presence: required
      rangelist:
      - AttemptAuthentication
      - RequireAuthentication
      - AllowOfflineGracePeriod
      - AllowAuthenticationGracePeriod
      content: |-
        * AttemptAuthentication
            Platform SSO authentication is attempted before proceeding. If offline, unlock will continue
            if the local account password matches. If online and the credential is incorrect, then a
            successful Platform SSO authentication is required to proceed, even if taken offline.
        * RequireAuthentication
            Platform SSO authentication is required before proceeding.  If the device is offline and
            `AllowOfflineGracePeriod` is enabled, then the offline `OfflineGracePeriod` is used to determine
            if the user can proceed or not. If online and the credential is incorrect, then a valid Platform
            SSO authentication is required to proceed regardless of the `OfflineGracePeriod`. If the account
            is not registered for Platform SSO and `AllowAuthenticationGracePeriod` is enabled, then the
            `AuthenticationGracePeriod` is used to determine if the user can proceed or not.
        * AllowOfflineGracePeriod
            Allow the use of the `OfflineGracePeriod` when `RequireAuthentication` is enabled.  If
            `AllowOfflineGracePeriod` is not set, then offline access is denied.
        * AllowAuthenticationGracePeriod
            Allow the use of the `AuthenticationGracePeriod` for other local accounts when `RequireAuthentication`
            is enabled. The `AuthenticationGracePeriod` starts when any of the policies have been updated. If
            `AllowAuthenticationGracePeriod` is not set, then unregistered account access is denied.
  - key: LoginPolicy
    supportedOS:
      macOS:
        introduced: '15.0'
    type: <array>
    presence: optional
    content: The policy to apply when using Platform SSO at the Login Window. Applies
      when `AuthenticationMethod` is `Password`. Available in macOS 15 and later.
    subkeys:
    - key: policy
      type: <string>
      presence: required
      rangelist:
      - AttemptAuthentication
      - RequireAuthentication
      - AllowOfflineGracePeriod
      - AllowAuthenticationGracePeriod
      content: |-
        * AttemptAuthentication
            Platform SSO authentication is attempted before proceeding. If offline, unlock will continue
            if the local account password matches. If online and the credential is incorrect, then a
            successful Platform SSO authentication is required to proceed, even if taken offline.
        * RequireAuthentication
            Platform SSO authentication is required before proceeding.  If the device is offline and
            `AllowOfflineGracePeriod` is enabled, then the offline `OfflineGracePeriod` is used to determine
            if the user can proceed or not. If online and the credential is incorrect, then a valid Platform
            SSO authentication is required to proceed regardless of the `OfflineGracePeriod`. If the account
            is not registered for Platform SSO and `AllowAuthenticationGracePeriod` is enabled, then the
            `AuthenticationGracePeriod` is used to determine if the user can proceed or not.
        * AllowOfflineGracePeriod
            Allow the use of the `OfflineGracePeriod` when `RequireAuthentication` is enabled.  If
            `AllowOfflineGracePeriod` is not set, then offline access is denied.
        * AllowAuthenticationGracePeriod
            Allow the use of the `AuthenticationGracePeriod` for other local accounts when `RequireAuthentication`
            is enabled. The `AuthenticationGracePeriod` starts when any of the policies have been updated. If
            `AllowAuthenticationGracePeriod` is not set, then unregistered account access is denied.
  - key: UnlockPolicy
    supportedOS:
      macOS:
        introduced: '15.0'
    type: <array>
    presence: optional
    content: The policy to apply when using Platform SSO at screensaver unlock. Applies
      when `AuthenticationMethod` is `Password`. Available in macOS 15 and later.
    subkeys:
    - key: policy
      type: <string>
      presence: required
      rangelist:
      - AttemptAuthentication
      - RequireAuthentication
      - AllowOfflineGracePeriod
      - AllowAuthenticationGracePeriod
      - AllowTouchIDOrWatchForUnlock
      content: |-
        * AttemptAuthentication
            Platform SSO authentication is attempted before proceeding. If offline, unlock will continue
            if the local account password matches. If online and the credential is incorrect, then a
            successful Platform SSO authentication is required to proceed, even if taken offline.
        * RequireAuthentication
            Platform SSO authentication is required before proceeding.  If the device is offline and
            `AllowOfflineGracePeriod` is enabled, then the offline `OfflineGracePeriod` is used to determine
            if the user can proceed or not. If online and the credential is incorrect, then a valid Platform
            SSO authentication is required to proceed regardless of the `OfflineGracePeriod`. If the account
            is not registered for Platform SSO and `AllowAuthenticationGracePeriod` is enabled, then the
            `AuthenticationGracePeriod` is used to determine if the user can proceed or not.
        * AllowOfflineGracePeriod
            Allow the use of the `OfflineGracePeriod` when `RequireAuthentication` is enabled.  If
            `AllowOfflineGracePeriod` is not set, then offline access is denied.
        * AllowAuthenticationGracePeriod
            Allow the use of the `AuthenticationGracePeriod` for other local accounts when `RequireAuthentication`
            is enabled. The `AuthenticationGracePeriod` starts when any of the policies have been updated. If
            `AllowAuthenticationGracePeriod` is not set, then unregistered account access is denied.
        * AllowTouchIDOrWatchForUnlock
            Allow TouchID or Watch to unlock the screensaver instead of Platform SSO authentication when
            `RequireAuthentication` is enabled.
  - key: OfflineGracePeriod
    supportedOS:
      macOS:
        introduced: '15.0'
    type: <integer>
    presence: optional
    content: The amount of time after the last successful Platform SSO login for using
      a local account password offline. Required when setting `AllowOfflineGracePeriod`.
      Available in macOS 15 and later.
  - key: AuthenticationGracePeriod
    supportedOS:
      macOS:
        introduced: '15.0'
    type: <integer>
    presence: optional
    content: The amount of time after receiving or updating a `FileVaultPolicy`, `LoginPolicy`,
      or `UnlockPolicy` that the system can use unregistered local accounts. Required
      when `AllowAuthenticationGracePeriod` is set. Available in macOS 15 and later.
  - key: NonPlatformSSOAccounts
    supportedOS:
      macOS:
        introduced: '15.0'
    type: <array>
    presence: optional
    content: The list of local accounts that aren't subject to the `FileVaultPolicy`,
      `LoginPolicy`, or `UnlockPolicy`. The accounts don't receive a prompt to register
      for Platform SSO. Available in macOS 15 and later.
    subkeys:
    - key: username
      type: <string>
      presence: required
      content: A local account username.
  - key: AllowDeviceIdentifiersInAttestation
    supportedOS:
      macOS:
        introduced: '15.4'
    type: <boolean>
    presence: optional
    default: false
    content: If `true`, the system includes the device UDID and serial number in Platform
      SSO attestations.
  - key: SynchronizeProfilePicture
    supportedOS:
      macOS:
        introduced: '26.0'
    type: <boolean>
    presence: optional
    default: false
    content: If `true`, the system requests the user's profile picture from the SSO
      extension.
  - key: TemporarySessionQuickLogin
    supportedOS:
      macOS:
        introduced: '26.0'
    type: <boolean>
    presence: optional
    default: false
    content: If `true`, the system uses a quicker Authenticated Guest Mode login to
      Mac behavior. The system erases user data from only select locations in the
      user home directory after each session completes. Once every eight hours the
      system erases the full user home directory after a session completes. Turn this
      on for shared environments that have a high frequency of short sessions.
  - key: EnableRegistrationDuringSetup
    supportedOS:
      macOS:
        introduced: '26.0'
    type: <boolean>
    presence: optional
    default: false
    content: If `true`, the system enables the PlatformSSO registration process during
      Setup Assistant on devices running macOS 26 and later. Set this key to `true`
      when configuring PlatformSSO before enrollment using the `com.apple.psso.required`
      error response.
notes:
- title: ''
  content: The system supports user channel installation in macOS 11 and later.