--- title: Implementing Platform SSO during device enrollment framework: devicemanagement role: article role_heading: Article path: devicemanagement/implementing-platform-sso-during-device-enrollment --- # Implementing Platform SSO during device enrollment Streamline device enrollment by using Platform SSO. ## Overview Overview A device management service can configure a macOS device to use Platform SSO during setup after the administrator registers the device with the Automated Device Enrollment program. This streamlines the enrollment process and enforces Platform SSO registration to enable 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 that users can sign in to that account using the identity provider credentials. The complete set of steps for the Platform SSO during enrollment flow are: Post a MACHINEINFO request with a PSSO indicator. Detect PSSO support for the device. Return the required 403 PSSO error response. Fetch the ExtensibleSingleSignOn profile. Return the ExtensibleSingleSignOn profile. Install the ExtensibleSingleSignOn profile. Fetch the package. Return the package. Install the package. Create a web view for AuthURL. Present the sign-in view to the user. Return an HTTP 308 redirect response. Authenticate the user. Post a MACHINEINFO request with the bearer token. Verify the bearer token. Return the enrollment profile. Enroll with the device management service. The following sections describe the details of each step. Send the initial request In step 1, the device posts a request to the enrollment URL and includes the MachineInfo details with an MDM_CAN_REQUEST_PSSO_CONFIG key with a value of true in the request body. A sample HTTP request: <<<<< Request POST /enroll HTTP/1.1 Host: mdmserver.example.com Content-Type: application/xml Content-Length: 500 UDID 0000-1111-2222 SERIAL ABCD1234 PRODUCT MacBookPro18,2 VERSION 25A300 OS_VERSION 16.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. In step 3, the device management service 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://mdmserver.example.com/psso.mobileconfig Package ManifestURL https://mdmserver.example.com/psso-app.plist AuthURL https://idp.example.com/authenticate Set up Platform SSO After receiving the error response, the device sets up Platform SSO as follows: It downloads the configuration profile that the ProfileURL key specifies (steps 4 and 5). The profile needs to contain an ExtensibleSingleSignOn profile payload with a configuration to implement Platform SSO using the SSO extension that the package delivers. The payload needs to contain an EnableRegistrationDuringSetup key set to true in the ExtensibleSingleSignOn.PlatformSSO object. It installs the configuration profile (step 6). It downloads the manifest document that the Package key specifies, and installs the package that the manifest document specifies (steps 7 and 8). The package needs to contain an app that includes the SSO extension for Platform SSO. It installs the package (step 9). This installs the app and its SSO extension on the device. 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. In addition to the ExtensibleSingleSignOn profile payload, the provided configuration profile can also contain the following profile payloads if needed: ACMECertificate AssociatedDomains CertificatePEM CertificatePKCS1 CertificatePKCS12 CertificatePreference CertificateRoot CertificateTransparency IdentityPreference ManagedPreferences SCEP Authenticate the user The device creates an ASWebAuthenticationSession using AuthURL and a callback scheme that it sets to apple-remotemanagement-user-login (step 10). This starts an authentication flow with the organization’s identity provider. The ASWebAuthenticationSession performs an HTTPS GET request for the web-auth URL and presents the resulting HTML data to the user in a web view for sign-in (step 11). A simple HTML 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. 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 … Process the user authentication result The ASWebAuthenticationSession web flow completes when the device management service returns an HTTP 308 permanent redirect response to the device (step 12), 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 (step 13). If authentication fails, the service returns an appropriate HTTP error response code that terminates the enrollment on the device. Enroll the device After authentication with the identity provider is complete, the device posts a request to the enrollment URL and includes the MachineInfo details without an MDM_CAN_REQUEST_PSSO_CONFIG key in the request body (step 14). 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 (step 15), and if that succeeds, it responds to the request by returning the device management MDM enrollment profile (step 16), which the device uses to enroll (step 17). A sample HTTP request and response: <<<<< Request POST /enroll HTTP/1.1 Host: mdmserver.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 16.0 >>>>> Response HTTP/1.1 200 OK Content-Type: application/x-apple-aspen-config Content-Length: nnn PayloadType Configuration … PayloadContent PayloadType com.apple.mdm … Manage the device After enrollment, the device management service manages the device, which has a configuration for Platform SSO. The SSO app and configuration profile persist on the device and remain managed. ## See Also ### Detailed flow instructions - [Implementing Platform SSO for unattended device enrollment](devicemanagement/implementing-platform-sso-for-unattended-device-enrollment.md)