Quick Setup for Xpsso Service

Xpsso with SimpleMDM

Xpsso with Mosyle MDM

Xpsso with Jamf MDM

Xpsso Service is a service to enable macOS Platform SSO to work with Google Identity and other OIDC-standard identity providers.

Items Required

1. Google Business Plus or similar
2. Any Mobile Device Management Service. Jamf Pro, Mosyle, and SimpleMDM have been verified to work.
3. A Mac or Linux machine to run the service, available on the internet (required by PSSO requirement for Associated Domains). Support for Windows Server is on the roadmap.
4. A registered DNS hostname (for example, xpsso.example.com)
5. A TLS certificate from a well known authority (for example, Let’s Encrypt)
6. A Mac enrolled in Apple Business Manager or Apple School Manager for Automated Device Enrollment.
7. The Xpsso macOS app that provides an app extension for enabling PSSO.
8. The Xpsso microservice for providing the machine trust and user authentication to the Google Cloud.
9. A configuration profile for configuring the PSSO service and the Xpsso macOS app.

Setup

1. In Google Workspace, set up an OIDC app and note the OIDC details like client id and client secret. Set the redirect URL to https://twocanoes.com/xcreds-redirect. Any redirect URL can be used, but needs to match the redirect defined in the Xpsso configuration profile. The content at this URL is not shown because redirect is only used to signal when authentication with OIDC is complete.
2. In Google Workspace, set up the LDAP service:
   • Be sure to sign in using your super administrator account, and not your personal Gmail account.
   • Go to Apps and then LDAP.
   • Click Add LDAP client and give the client the name Xpsso.
   • Generate a certificate and download the certificate and key. These will be used later.
3. Download the PSSO mobile config from https://tc-static.s3.amazonaws.com/xcreds/xpsso_config_template.mobileconfig and replace all instances of <DNS_HOST_NAME> with your DNS hostname of the microservice (for example, xpsso.example.com). This profile will be installed by your MDM later.
4. Download the most recent build of the Xpsso app from https://bitbucket.org/twocanoes/xpsso/downloads/.
5. In MDM, set up Automated Device Enrollment to install the Xpsso app and configuration profile during Automated Device Enrollment. See the MDM Setup section in the Xpsso Admin Guide for specific instructions on some common MDMs.
6. Set up DNS to point to the hostname of the Mac or Linux instance that is hosting the microservice.
7. Set up TLS using Let’s Encrypt or something similar, and install the certificate and key in /etc/psso/fullchain.pem and /etc/psso/privkey.pem respectively.
8. Install the LDAP certificate on the Mac or Linux instance hosting the microservice. For macOS, combine the certificate and key into a p12, import it into the system keychain. Give ldapsearch access to the private key by clicking the triangle next to “LDAP Client” in the system keychain, double-clicking the item shown called “Imported Private Key”, then click the “Access Control” tab and click the plus icon to add an item, then press command-shift-g and enter /usr/bin/ldapsearch, then click Add. For Linux, install the certificate and key into /var/psso/ldap_certificates.crt and /var/psso/ldap_private.key respectively.
9. Download the microservice zip file from https://bitbucket.org/twocanoes/xpsso-service/downloads/, then unzip it. For macOS, install the package file. For Linux, put the xpsso-service binary file in /usr/local/bin/.
10. Update <DNS_HOST_NAME>, <YOUR_CLIENT_ID_FROM_OIDC>, <YOUR_CLIENT_SECRET_FROM_OIDC> in the command below and run the command as root:

PSSO_ISSUER=<DNS_HOST_NAME>  \
OIDCISSUER=https://accounts.google.com \
PSSO_REDIRECT_URI=https://twocanoes.com/xcreds-redirect \
PSSO_CLIENT_ID=<YOUR_CLIENT_ID_FROM_OIDC> \
PSSO_SCOPE="profile openid" \
PSSO_CLIENT_SECRET=<YOUR_CLIENT_SECRET_FROM_OIDC> \
/usr/local/bin/xpsso-service

The service should now be running on port 443 and show output such as:

Version: 1.0.1063
Running local...
Checking JWKS
jwks file exists. reading
2026/02/21 17:31:12 Server is starting on :443

Make sure to leave the terminal window open for the service to stay running. In a future release, this will be moved to a background service.

Testing

1. If the host is not available on the internet, make the service available on the internet using port forwarding, ngrok or another method to expose the service port 443 to the internet.
2. Test to make sure it is available by accessing the nonce: https://<DNS_HOST_NAME>/nonce. If a value is returned, then the service is running. Make sure it is running over https and no TLS errors are returned.
3. Enroll a Mac using ADE and verify a user is able to use their Google Credentials during account setup. You may be required to provide your credentials multiple times during setup. After setup is complete and the user is at the desktop, verify the local user name and home directory are set up using the account information from Google Identity.