Implementing Single Sign-on Extension (SSOe)

II. Overview

I. Introduction

  • Feature Name: Extensible Single Sign-On or SSOe for short.

  • Deployment: At least iOS 13 or iPadOS 13, and macOS 10.15.

  • Purpose: Allow users to easily single sign-on (SSO) into vendors’ apps and websites that support federated identity providers.

II. Overview

In general, the Single Sign-On Extension (SSOe) solves a common problem for employees or users in larger organizations.

An employee commonly uses multiple organization-related apps and web pages throughout the day. Each app may require authentication to access the resources in that app or website.

In many educational or enterprise environments, these users may include school children, teachers, or staff attempting to access digital resources provided by their institution. In short, they may need to sign in through a centralized identity system across multiple apps & websites.

To solve this problem, the SSOe provides a way to handle separate app requests and provide the same credentials to each app. Thus, the user only has to sign in the first time, and each subsequent login will not prompt for their credentials again.

The SSOe provides a secure way to authenticate different apps and websites if they all share the same Identity Provider (IdP) without prompting each time a different app is accessed.

The Single Sign-On Extension provides a way to securely share credentials between apps by handling the URL requests sent to the identity provider and sharing the authentication between different apps, including web browsers such as Safari.

In short, requests from apps attempting to authenticate with an IdP will be routed to the SSOe to provide a seamless single sign-on experience.

III. Required Services

1. Identity Provider (IdP): 

The web service is used for providing user authentication. The IdP must provide the Associated Domain file in a specific location with content matching the Container App’s entitlement.

In general usage, the Identity Provider can be any supported authentication provider, which might be used interchangeably with the term IdP in this document.

2. Mobile Device Management (MDM) Service:

Provides the configuration for the SSOe. The MDM Service must provide configuration and cannot be provided by other means for the SSOe to handle requests.

The MDM Service must support the SSOe payload type to deploy the needed configuration for the SSOe.

IV. Required Components

The SSOe requires the following components:

1. Container App

In our case, the container app already exists in the form of the a mobile iOS app.

In general, the container app should be a standard macOS or iOS application to which a single sign-on extension (SSOe) is attached. The app does not have to provide any functionality outside of hosting the SSOe but typically has information or utility functions related to the Identity Provider. 

The only SSOe-specific requirement for the Container App is that it must have an entitlement containing the Identity Provider’s hostname to allow the extension to route requests to the extension. The SSOe Domain is required for the OS to verify that the IdP allows the extension to access the IdP.

2. Single Sign-On Extension 

A macOS or iOS system extension that gets registered with the OS when the container app is installed. The SSOe must be configured from an MDM profile. 

If the device running the extension is not managed via MDM or does not contain an installed SSOe MDM payload, the SSOe extension will not trigger, and the host app will continue to function normally without single sign-on capability.

3. Associated Domain File 

A JSON file that is uploaded to a specific endpoint on the Identity Provider’s web service. This file identifies the developer and extension that will be accessing the Identity Provider through the extension. The file is checked by the OS when the SSOe is installed.

4. Mobile Device Management Configuration Profile 

A configuration file for the SSOe must be delivered with a Mobile Device Management (MDM) server. This configuration file associates the authentication URLs with the specific extension by the bundle identifier.

Attached below is the setup for the SSOe MDM Configuration profile on Mosyle.com. 

The profile must contain:

  • The name;

  • The SSO type, Credential or Redirect (Redirect is commonly used in educational or enterprise environments);

  • The list of IdP URLs to be intercepted by the extension;

  • The extension Bundle ID.

More info on the MDM Payload settings can be found in Apple’s documentation for the feature.

V. Core Functionality

When any installed app requests authentication with a web service for a URL that requires authentication with the IdP, the URL request is passed to the SSOe extension. The SSOe extension can then complete the request by showing a user interface (typically for entering a username and password) and/or calling services required to complete the authentication. The SSOe can also securely cache required credentials to process subsequent requests without user interaction. Once authentication is complete, the initial URL request is completed by the SSOe, usually by redirecting the requesting app’s URL request back to the requested service with the provided authentication in the redirected request.

The app itself does not need to be aware of the SSO functionality and does not need any Identity Provider-specific user interface built into the app requesting authentication. The authentication information is shared between any apps that call the defined authentication URLs, including a browser. This provides SSO between the browser session and the app, resulting in the user only entering their credentials once.

The SSOe is protocol-agnostic and does not require the app to know that the SSOe extension is being used. From the app perspective, the app requests a network resource, and the content is delivered in the response. The SSOe can authenticate using OIDC redirects, SAML, or other authentication protocols. Once the authentication is complete, the response can populate cookies, set an authentication header, and redirect to another URL. It is up to the IdP to implement the SSOe that best implements the required authentication protocols for authenticating the user and caching the authentication information.

For a more visual representation, here are the flows for an app without & with SSOe:

Flow with SSOE

VI. IdP Trust Requirements

For the SSOE extension to be deployed successfully, there are trust requirements and protections to limit the scope of what an SSOE can access:

  1. Organization Trust of App: The SSOE must be sandboxed and code-signed by a certificate issued by Apple. The extension is trusted by Apple to run on the device because it is signed by a certificate from Apple or with an organization’s certificate issued by Apple.

  2. Organization Trust of URLs: URLs that are handled by the SSOE must be specified in an MDM profile. An organization that manages the devices enrolled in the MDM can trust that only the URLs specified in the MDM-delivered profile will be handled by the SSOE.

  3. OS trust of IDP: An associated domain file is made available on the IdP’s website and cached by Apple’s CDN.

VII. Setup & Installation

To run & test the SSOe implementation on your device, the following conditions must be met:

  1. The container app and extension must be signed with a valid developer certificate.

  2. The container app must be hardened and notarized (on macOS).

  3. The extension must be sandboxed (on both macOS and iOS).

  4. The container app must have an Associated Domain entitlement with a hostname defined to a publicly accessible web server. This entitlement is specified in Xcode for the container app.

  5. Download a version of the container app that includes the SSOe functionality.

  6. The publicly accessible web server of the IdP must return a valid JSON from /.well-known/apple-app-site-association that contains the team ID and bundle ID of the container app in a specific format. This URL endpoint must be the exact path at the root level of the host specified in the entitlement.

  7. An MDM SSOe configuration profile must be installed by an MDM and must contain URLs whose hostname matches the hostname defined in the entitlement and the com.apple.associated-domains MDM profile (macOS or iOS). Alternatively, the com.apple.associated-domains can be distributed by the AssociatedDomains property of the InstallApplicationCommand on iOS.