--- title: Implementing Platform SSO during Automated Device Enrollment framework: Device Management role: article role_heading: Article path: devicemanagement/implementing-platform-sso-during-automated-device-enrollment --- # Implementing Platform SSO during Automated Device Enrollment Streamline authentication during Automated Device Enrollment with Platform SSO. ## Overview Overview A device management service can configure a Mac to use Platform SSO during setup after the administrator registers the device for Automated Device Enrollment. This streamlines the enrollment process and enforces Platform SSO registration to provide single sign-on access to apps and websites. Implement the Platform SSO flow When the Automated Device Enrollment Profile for a device indicates that it needs to enroll during initial setup, the device posts a request to the enrollment URL and includes the MachineInfo details in the request body. If the device is capable of supporting Platform SSO during enrollment, the MachineInfo details include an MDM_CAN_REQUEST_PSSO_CONFIG key with a value of true. When the device management service detects a device capable of using Platform SSO during enrollment, it returns an ErrorCodePlatformSSORequired 403 error response to the device. That response contains the details that allow the device to configure Platform SSO and initiate an initial authentication with the organization’s identity provider. After the initial authentication completes successfully, the device resends the enrollment URL request and includes the MachineInfo details again. However, this time, the MachineInfo details don’t contain the MDM_CAN_REQUEST_PSSO_CONFIG key. The device also includes an Authorization HTTP request header and sets its value to include a Bearer token key containing an identity provider authorization token for the user. When the device management service verifies the authorization token, it delivers the device management (MDM) enrollment profile to the device to start the enrollment. The device then proceeds through Setup Assistant and automatically creates a local user account that it configures with the Platform SSO details so people can sign in to that account using the identity provider credentials. The complete set of steps for the Platform SSO during enrollment flow are: The device requests the enrollment by posting a MACHINEINFO request with a PSSO indicator. The device management service returns a 403 error that includes the details needed to set up and configure Platform SSO. The device downloads and installs the ExtensibleSingleSignOn profile and the package specified in the response. The package needs to contain an app that includes the SSO extension for Platform SSO. The device starts an authentication flow with the organization’s identity provider using the AuthURL specified in the 403 response and prompts the user to authenticate. If authentication is successful, the device receives an authorization token and an HTTP 308 redirect response. The device posts another MACHINEINFO request and includes the authorization token. If authorization is successful, the device management service returns the enrollment profile. The device enrolls and creates a local user account based on information from the identity provider. The following sections describe the details of each step. note: The described flow enables authenticating the enrollment using tokens provided by Platform SSO. Alternatively, you can use the await_device_configured flag to keep the device in Setup Assistant while installing the Platform SSO extension and required configuration. Requesting the enrollment In step 1, the device posts an HTTP request to the enrollment URL specified in the Automated Device Enrollment Profile and includes the MachineInfo details with an MDM_CAN_REQUEST_PSSO_CONFIG key with a value of true in the request body. The following is a sample HTTP request: <<<<< Request POST /enroll HTTP/1.1 Host: devicemanagement.example.com Content-Type: application/xml Content-Length: 500 UDID 0000-1111-2222 SERIAL ABCD1234 PRODUCT MacBookPro18,2 VERSION 25A300 OS_VERSION 27.0 MDM_CAN_REQUEST_PSSO_CONFIG Process the Platform SSO required response In step 2, the device management service detects that a device that supports Platform SSO during enrollment is trying to enroll and returns an ErrorCodePlatformSSORequired 403 error response to the device. The 403 error response is a JSON object that contains a Code key with a value of com.apple.psso.required, and a Details object with the following keys: | | | | | | | | The Package key contains a JSON object with the following keys: | | | | | | | | A sample HTTP response: >>>>> Response HTTP/1.1 403 Forbidden Content-Type: application/xml Content-Length: 601 code com.apple.psso.required details ProfileURL https://devicemanagement.example.com/psso.mobileconfig Package ManifestURL https://devicemanagement.example.com/psso-app.plist AuthURL https://idp.example.com/authenticate important: To enforce a minimum operating system version, your device management service needs to provide the ErrorCodeSoftwareUpdateRequired 403 error in its first response. After the version provided in the MachineInfo shows the required operating system version, return the ErrorCodePlatformSSORequired 403 error response the next time the device requests enrollment. Set up Platform SSO To set up Platform SSO after receiving the error response, the device: Downloads the configuration profile that the ProfileURL key specifies (see step 3 in the figure, above). The profile needs to contain an ExtensibleSingleSignOn profile payload with a ExtensibleSingleSignOn.PlatformSSO object to configure Platform SSO using the SSO extension that the package delivers. The payload must contain at least the EnableRegistrationDuringSetup key set to true. Installs the configuration profile. Downloads the manifest document that the Package key specifies, and installs the package that the manifest document specifies. The package needs to contain an app that includes the SSO extension for Platform SSO. Installs the package. This installs the app and its SSO extension on the device. important: Sign the package with a certificate the device can verify at this stage. This can be a certificate, with a trust chain rooted in a Certificate Authority within the built-in trust store or provided by a CertificateRoot configuration. If you use a custom root certificate, provide any intermediate certificates required to verify the signature. If any of the above steps fail, the device displays an error alert to the user and cycles back to a state that allows the user to try signing in again. important: The package needs to install the app containing the SSO extension into the /Applications folder to ensure the device management service is managing the app. If the Platform SSO extension requires it, combine the following payloads in the same profile together with the ExtensibleSingleSignOn payload: ACMECertificate AssociatedDomains CertificatePEM CertificatePKCS1 CertificatePKCS12 CertificatePreference CertificateRoot CertificateTransparency IdentityPreference ManagedPreferences SCEP Authenticate the user In step 4, the device creates an ASWebAuthenticationSession using AuthURL and a callback scheme that is set to apple-remotemanagement-user-login. This starts an authentication flow with the organization’s identity provider. The ASWebAuthenticationSession performs an HTTPS GET request for the AuthURL and presents the resulting HTML data to the user in a web view for sign-in. The sign-in page can contain a form with text entry fields for a user ID and password, OK and Cancel buttons, optional terms and conditions, optional branding, and so on. The user can opt to cancel out of the web view at any time, which terminates the authentication flow and the enrollment. The following is a sample HTTP request and response: <<<<< Request GET /authenticate HTTP/1.1 Host: idp.example.com >>>>> Response HTTP/1.1 200 OK Content-Type: text/html; charset="utf-8" Content-Length: 17643 … The ASWebAuthenticationSession web flow completes when the device management service returns an HTTP 308 permanent redirect response to the device, with a Location header that the service sets to a URL with a scheme of apple-remotemanagement-user-login (the authentication session callback URL scheme). The service sets the network location component of the URL to authentication-results. It includes an access-token query item in the URL and sets its value to the identity provider authorization token. The identity provider controls the format of the authorization token, so the device treats it as an opaque token. A sample HTTP response: >>>>> Response HTTP/1.1 308 Permanent Redirect Content-Length: 0 Location: apple-remotemanagement-user-login://authentication-results?access-token=dXNlci1pZGVudGl0eQ The device management service verifies the access token to determine whether authentication succeeds. If authentication fails, the service returns an appropriate HTTP error response code that terminates the enrollment on the device. Enroll the device After completing authentication with the identity provider, the device posts a request (see step 5 in the figure, above) to the enrollment URL and includes the MachineInfo details without an MDM_CAN_REQUEST_PSSO_CONFIG key in the request body. The request includes an Authorization HTTP header with a Bearer key that the device sets to the authorization token that the identity provider returns. The device management service verifies the authorization token, and if that succeeds, it responds to the request by returning the device management MDM enrollment profile, which the device uses to enroll. The following is a sample HTTP request and response: <<<<< Request POST /enroll HTTP/1.1 Host: devicemanagement.example.com Content-Type: application/xml Content-Length: 500 Authorization: Bearer dXNlci1pZGVudGl0eQ UDID 0000-1111-2222 SERIAL ABCD1234 PRODUCT MacBookPro18,2 VERSION 25A300 OS_VERSION 27.0 >>>>> Response HTTP/1.1 200 OK Content-Type: application/x-apple-aspen-config Content-Length: nnn PayloadType Configuration … PayloadContent PayloadType com.apple.mdm … Create the local user account The device creates a local account using the information provided by the identity provider. When SynchronizeProfilePicture is set to true, the device uses the profile picture provided by the SSO extension for the created account. ## See Also ### Detailed flow instructions - [Implementing Platform SSO for unattended device enrollment](devicemanagement/implementing-platform-sso-for-unattended-device-enrollment.md)