Keycloak / Apple Business / Apple School Manager Integration PoC Doc

readme.md

Keycloak + Apple Business Integration

This guide describes how to integrate Keycloak with Apple Business Manager (ABM) as a Custom Identity Provider, using OIDC for authentication and SSF (Shared Signals Framework) for propagating session and credential change events.

Note that the frontend hostname that Keycloak uses as issuer for the ssf-configuration endpoint.

Keycloak Setup

1. Use Keycloak 26.7.0+ or a nightly Keycloak build.

2. Enable the SSF feature: --features=ssf

3. Create a realm, e.g. ssf-poc.

4. Configure the realm for SSF:

   • 4.1) In Realm Settings, set SSF Transmitter to On.
   • 4.2) Copy the SSF configuration URL: https://site/realms/ssf-poc/.well-known/ssf-configuration
   • 4.3) Copy the OpenID configuration URL: https://site/realms/ssf-poc/.well-known/openid-configuration
   • 4.4) Ensure that the client scopes ssf.read / ssf.manage are both present and exposed in token scope claim.

5. Create a client:

   • 5.1) Client ID: apple-abm
   • 5.2) Client Authentication: On
   • 5.3) Authentication Flow: Standard Flow enabled
   • 5.4) Valid redirect URIs: https://gsa-ws.apple.com/grandslam/GsService2/acs/*
   • 5.5) Valid post logout redirect URIs: +
   • 5.6) PKCE: Off (Apple currently does not appear to support PKCE for OIDC federations at the moment)
   • 5.7) Copy the client secret from the Credentials tab.

6. Configure SSF Receiver support for the client:

   • 6.1) SSF Receiver: On
   • 6.2) In the Client Scopes tab, add ssf.manage, ssf.read, and offline_access — all as Default.
   • 6.3) Add the client role ssf-admin (required for the ABM admin user).

7. Configure the SSF Receiver:

   • 7.1) Open the client's SSF tab.
   • 7.2) Set Profile to SSE CAEP 1.0.
   • 7.3) Default Subjects: NONE
   • 7.4) Subject format: iss_sub
   • 7.5) Add subject on login: On
   • 7.6) Auto verify stream: On (sends the verification event immediately after Apple creates the stream).
   • 7.7) Verification delay: 1500
   • 7.8) Required Role: apple-abm → ssf-admin
   • 7.9) Allowed delivery methods: Push Delivery
   • 7.10) Valid push URLs: https://federation.apple.com/feeds/business/caep/* (for business manager) https://federation.apple.com/feeds/school/caep/* (for school manager)
   • 7.11) Supported Events: CaepCredentialChange, CaepSessionRevoked
   • 7.12) Emit events enabled: On
   • 7.13) Emit-only events: CaepSessionRevoked (lets you control when user sign-outs are propagated via API).

8. Create the ABM admin user. This user is used to establish the ABM ↔ Keycloak connection via the Authorization Code Flow, producing an access/refresh token bound to an offline user session.

   • 8.1) Create a user, e.g. username abm, and complete the profile as needed.
   • 8.2) In Credentials, configure a strong password and 2FA (this is the Apple integration user).
   • 8.3) Assign the client role apple-abm/ssf-admin.

The apple-abm client is now ready to receive stream-create requests from Apple Business Manager.

ABM Setup

1. Go to https://business.apple.com and sign in with your ABM user.

2. Navigate to Settings → Domains → Domains.

3. Ensure your domain (e.g. your-domain.com) is verified. See: https://support.apple.com/guide/business/verify-a-domain-axm48c3280c0/web

4. Set up Keycloak as an Identity Provider:

   • 4.1) Under User sign-in and directory sync, click Connect.
   • 4.2) Select Custom Identity Provider → Continue.
   • 4.3) Enter a name, e.g. abmkc.
   • 4.4) Client ID: your client id, e.g. apple-abm
   • 4.5) Client Secret: your client secret
   • 4.6) SSF URL: the SSF configuration URL, e.g. https://site/realms/ssf-poc/.well-known/ssf-configuration
   • 4.7) OIDC URL: the OpenID configuration URL, e.g. https://site/realms/ssf-poc/.well-known/openid-configuration
   • 4.8) Click Continue.
   • 4.9) After a few seconds a new window appears with a Sign in with abmkc button.
   • 4.10) Click Sign in with abmkc.
   • 4.11) A Keycloak login page opens in a new window.
   • 4.12) Sign in with the ABM admin user.
   • 4.13) You should see an Authorizing Account message.
   • 4.14) On success, an abmkc connected confirmation is shown.

   At this point, Apple has created an SSF stream for the apple-abm SSF receiver OIDC client. The stream is visible in the client's SSF → Streams tab.

5. Connect the new Identity Provider to your domain in Apple Business:

   • 5.1) Go to Settings → Domains → Domains.
   • 5.2) Select your target domain and click Manage.
   • 5.3) At the bottom of the page, find the Sign In with abmkc section and click Set up.
   • 5.4) After a few seconds a toggle appears — switch it to On.

Federation is now enabled for your domain. The ABM account should receive a Federation Enabled confirmation email.

Onboarding a User via Device

Users can now onboard their Apple devices via Keycloak. The following describes the flow for an unpaired device.

See: https://support.apple.com/guide/iphone/sign-in-and-manage-your-apple-account-iph76e54c61e/ios

1. Open Settings.
2. Tap Apple Account.
3. Tap Sign In Manually.
4. Enter an email address that matches the federated ABM domain, e.g. user@your-domain.com, then tap Proceed.
5. A hint appears: Apple account for <Company Name> — tap Proceed.
6. The Keycloak login page is shown with the username pre-filled.
7. After signing in with the correct password, a processing screen displays the user's first and last name.
8. After a short delay, enter your device PIN.
9. Settings → Apple Account now shows the connected user with the correct email address.

The ABM user account is now linked to the federated Keycloak user and can be managed through Apple Business Manager.