5. Keycloak as identity provider for ASM

Apple School Manager can federate the sign-in of its Managed Apple Accounts to an external identity provider. Your users then sign in to their Apple devices with the password from your UCS@school domain instead of a password that Apple School Manager manages.

This chapter describes how to set up the Keycloak app of UCS as that identity provider.

Caution

The SSF support that Apple School Manager requires is an experimental feature of Keycloak.

5.1. Why Apple School Manager needs SSF

The Shared Signals Framework is the standard of the OpenID Foundation for sharing security events, state changes, and risk signals between an identity provider and the applications that rely on it. See OpenID Foundation [5].

Apple School Manager uses SSF to learn about events in your domain, such as a changed credential or a revoked session. It therefore only accepts an identity provider that acts as an SSF transmitter. A plain OIDC client isn’t enough.

5.2. What you need

• A UCS@school domain with the Apple School Manager Connector and the Keycloak app in version 26.7.2-nubus1 or later.

• A domain that you verified in Apple School Manager. See Apple Inc. [6]. Your users need a primary email address in that domain to sign in.

• An account in Apple School Manager with the Administrator role to connect the identity provider. See Apple Inc. [7]. This account can’t sign in through the federation itself.

• An Apple device for the first sign-in.

• Anonymization turned off, because Apple School Manager needs the email address as the Apple Account:

  Listing 5.1 Turn anonymization off in /etc/asm-connections.json

  "defaults": {
      "student": {"anonymize": false},
      "staff": {"anonymize": false}
  }
  

  See Anonymization.

5.3. Configure Keycloak

Make every setting in the Keycloak admin console in the realm ucs, which holds the users of your domain. The admin console opens in the realm master. Select ucs in the realm selector before you change anything, and check the selected realm whenever you return to the admin console.

5.3.1. Enable the SSF feature

Set the app setting keycloak/server/feature/ssf of the Keycloak app to true.

1. Open the App Center in UMC and select the Keycloak app.

2. Click App settings.

3. Select keycloak/server/feature/ssf.

4. Click Apply changes.

Alternatively, set it on the command line:

Listing 5.2 Enable the SSF feature of Keycloak

$ univention-app configure keycloak --set keycloak/server/feature/ssf=true

The App Center then recreates the Keycloak container, which starts Keycloak with the SSF feature. Keycloak is unavailable for a short time while that happens.

Note

If you set the variable with ucr set instead, apply it with univention-app configure keycloak. Restarting the app with univention-app restart keycloak isn’t enough, and the Realm settings page doesn’t offer SSF Transmitter.

5.3.2. Turn the realm into an SSF transmitter

1. Open the Keycloak admin console at https://ucs-sso-ng.DOMAIN/admin/ and select the realm ucs. Replace DOMAIN with the domain name of your UCS domain.

2. On the Realm settings page, set SSF Transmitter to On.

With the transmitter on, the realm offers an SSF configuration metadata endpoint next to the OpenID endpoint configuration. You need the URLs of both endpoints in Connect the identity provider:

• https://ucs-sso-ng.DOMAIN/realms/ucs/.well-known/openid-configuration

• https://ucs-sso-ng.DOMAIN/realms/ucs/.well-known/ssf-configuration

The URLs use the defaults of the Keycloak app: the host ucs-sso-ng.DOMAIN and the realm ucs, which holds the users of the domain. If you changed keycloak/server/sso/fqdn or use another realm, adjust the URLs accordingly.

5.3.3. Create the client scopes

On the realm’s Client scopes page, create the client scopes ssf.manage and ssf.read, each with Include in token scope enabled.

5.3.4. Create the OIDC client

1. On the realm’s Clients page, click Create client.

2. On the General settings page, enter apple-asm as Client ID.

3. On the Capability config page, enter the settings from the following table.

   Table 5.1 Capabilities of the OIDC client for Apple School Manager

   Setting	Value
   Client authentication	On
   Authentication flow	Standard flow
   Require PKCE	Off
   SSF Receiver	On

   Apple doesn’t appear to support PKCE for OIDC federations, which is why the client turns it off. The page doesn’t offer SSF Receiver until Client authentication is on and you completed Enable the SSF feature and Turn the realm into an SSF transmitter.

4. On the Login settings page, enter the settings from the following table and click Save.

   Table 5.2 Login settings of the OIDC client for Apple School Manager

   Setting	Value
   Valid redirect URIs	https://gsa-ws.apple.com/grandslam/GsService2/acs
   Valid post logout redirect URIs	+

Copy the client secret from the Credentials tab. You need it in Connect the identity provider.

5.3.5. Configure the client as an SSF receiver

1. On the client’s Client scopes tab, add ssf.manage, ssf.read, and offline_access as Default.

2. On the Roles tab, add the client role ssf-admin.

3. On the SSF tab, enter the settings from the following table.

Table 5.3 SSF settings of the client

Setting	Value
Profile	SSE CAEP 1.0
Default Subjects	NONE
Subject format	iss_sub
Add subject on login	On
Auto verify stream	On
Verification delay	1500
Required role	Click Select role, select Client roles, and select ssf-admin.
Allowed delivery methods	Push Delivery only
Valid push URLs	https://federation.apple.com/feeds/school/caep/*
Supported Events	CaepCredentialChange, CaepSessionRevoked
Emit events enabled	On
Emit-only events	CaepSessionRevoked

Auto verify stream sends the verification event as soon as Apple creates the stream. Emit-only events lets you control through the Keycloak API when Keycloak sends a sign-out to Apple.

5.3.6. Create the administrative user

Apple School Manager establishes the connection to Keycloak with the authorization code flow. The resulting access token and refresh token belong to an offline session of one user, so that user must exist before you connect the two systems.

Create the user in Keycloak, not in UCS. Keycloak has only read access to the UCS users, so it can’t assign client roles to them.

1. In the realm ucs, create a user, for example asm.

2. Set the first name, the last name, and the email address.

3. On the Credentials tab, set a strong password. Two-factor authentication is optional but recommended.

4. Assign the client role ssf-admin of the client apple-asm.

5.4. Configure Apple School Manager

5.4.1. Connect the identity provider

1. Sign in to Apple School Manager.

2. Open Preferences ‣ Managed Apple Accounts.

3. Make sure that your domain is verified.

4. Under User sign-in and directory sync, click Configure. If another identity provider is connected, disconnect it first.

5. Select Custom Identity Provider and click Continue.

6. Enter a name for the identity provider, for example asmkc.

7. Enter the client ID and the client secret from Create the OIDC client, and the two URLs from Turn the realm into an SSF transmitter, as listed in the following table.

   Table 5.4 Settings of the custom identity provider in Apple School Manager

   Field	Value
   Client ID	apple-asm
   Client Secret	The client secret from the Credentials tab of the client
   SSF URL	https://ucs-sso-ng.DOMAIN/realms/ucs/.well-known/ssf-configuration
   OIDC URL	https://ucs-sso-ng.DOMAIN/realms/ucs/.well-known/openid-configuration

8. Click Continue.

9. In the window that opens, click the sign-in button for your identity provider, for example Sign in with asmkc.

10. Sign in with the administrative user from Create the administrative user.

Apple School Manager shows Authorizing Account and then confirms the connection. During the connection, Apple creates an SSF stream for the client, which you can see on the client’s SSF Streams tab in Keycloak.

5.4.2. Enable federation for the domain

1. Open Preferences ‣ Managed Apple Accounts.

2. Select your domain and click Manage.

3. At the bottom of the page, find the section for your identity provider and click Set up.

4. Switch the toggle that appears to On.

5. If the SFTP upload uses the domain, Apple School Manager asks you to choose another domain for the upload. Choose any other domain.

Apple School Manager enables federation for the domain and sends a confirmation email.

After that, every Managed Apple Account with an email address in the domain signs in through Keycloak. This includes accounts that existed before you enabled federation and accounts that you created manually in Apple School Manager.

The upload from the connector continues to work. Apple School Manager assigns the accounts by the domain of their email address, so the accounts from the upload belong to the federated domain, regardless of the domain that you chose for the SFTP upload.

5.5. Sign in on a device

After you enable federation for the domain, your users sign in to an Apple device with their UCS@school credentials. The following steps describe an unpaired device. See Apple Inc. [8] for the general procedure.

1. Open Settings ‣ Apple Account.

2. Tap Sign In Manually.

3. Enter the email address of the user in the federated domain and tap Proceed.

4. The device shows a hint that names your organization. Tap Proceed.

5. The Keycloak sign-in page opens with the user name already filled in. Enter the password.

6. Enter the device PIN when the device asks for it.

After the sign-in, Settings ‣ Apple Account shows the user with the email address from UCS@school.