Keycloak als Identity Provider für ASM

5. Keycloak als Identity Provider für ASM#

Apple School Manager kann die Anmeldung seiner Managed Apple Accounts an einen externen Identity Provider föderieren. Ihre Benutzer melden sich dann an ihren Apple-Geräten mit dem Passwort aus Ihrer UCS@school-Domäne an statt mit einem Passwort, das Apple School Manager verwaltet.

Dieses Kapitel beschreibt, wie Sie die Keycloak-App von UCS als diesen Identity Provider einrichten.

Vorsicht

Die SSF-Unterstützung, die Apple School Manager voraussetzt, ist ein experimentelles Feature von Keycloak.

5.1. Warum Apple School Manager SSF benötigt#

Das Shared Signals Framework ist der Standard der OpenID Foundation für den Austausch von Sicherheitsereignissen, Zustandsänderungen und Risikosignalen zwischen einem Identity Provider und den Anwendungen, die sich auf ihn stützen. Siehe OpenID Foundation [5].

Apple School Manager nutzt SSF, um von Ereignissen in Ihrer Domäne zu erfahren, etwa von geänderten Anmeldedaten oder einer widerrufenen Sitzung. Deshalb akzeptiert es nur einen Identity Provider, der als SSF-Transmitter agiert. Ein einfacher OIDC-Client genügt nicht.

5.2. Voraussetzungen#

  • Eine UCS@school-Domäne mit dem Apple School Manager Connector und der Keycloak-App in Version 26.7.2-nubus1 oder neuer.

  • Eine Domain, die Sie in Apple School Manager verifiziert haben. Siehe Apple Inc. [6]. Ihre Benutzer benötigen eine primäre E-Mail-Adresse in dieser Domain, um sich anzumelden.

  • Ein Konto in Apple School Manager mit der Rolle Administrator, um den Identity Provider zu verbinden. Siehe Apple Inc. [7]. Dieses Konto kann sich selbst nicht über die Föderation anmelden.

  • Ein Apple-Gerät für die erste Anmeldung.

  • Deaktivierte Anonymisierung, weil Apple School Manager die E-Mail-Adresse als Apple Account benötigt:

    Quellcode 5.1 Anonymisierung in /etc/asm-connections.json ausschalten#
    "defaults": {
    "student": {"anonymize": false},
    "staff": {"anonymize": false}
}

    Siehe Anonymisierung.

5.3. Keycloak konfigurieren#

Nehmen Sie alle Einstellungen in der Keycloak-Administrationskonsole im Realm ucs vor, der die Benutzer Ihrer Domäne enthält. Die Administrationskonsole öffnet sich im Realm master. Wählen Sie den Realm ucs aus, bevor Sie etwas ändern, und prüfen Sie den ausgewählten Realm, wann immer Sie zur Administrationskonsole zurückkehren.

5.3.1. SSF-Feature aktivieren#

Setzen Sie die App-Einstellung keycloak/server/feature/ssf der Keycloak-App auf true.

  1. Öffnen Sie das App Center in der UMC und wählen Sie die Keycloak-App aus.

  2. Klicken Sie auf App settings.

  3. Wählen Sie keycloak/server/feature/ssf aus.

  4. Klicken Sie auf Apply changes.

Alternativ können Sie die Einstellung auf der Kommandozeile setzen:

Quellcode 5.2 SSF-Feature von Keycloak aktivieren#
$ univention-app configure keycloak --set keycloak/server/feature/ssf=true

Das App Center erstellt daraufhin den Keycloak-Container neu, der Keycloak mit dem SSF-Feature startet. Währenddessen ist Keycloak für kurze Zeit nicht erreichbar.

Bemerkung

Wenn Sie die Variable stattdessen mit ucr set setzen, übernehmen Sie sie mit univention-app configure keycloak. Ein Neustart der App mit univention-app restart keycloak reicht nicht aus, und die Seite Realm settings bietet SSF Transmitter nicht an.

5.3.2. Realm zum SSF-Transmitter machen#

  1. Öffnen Sie die Keycloak-Administrationskonsole unter https://ucs-sso-ng.DOMAIN/admin/ und wählen Sie den Realm ucs aus. Ersetzen Sie DOMAIN durch den Domänennamen Ihrer UCS-Domäne.

  2. Setzen Sie auf der Seite Realm settings die Option SSF Transmitter auf On.

Sobald SSF Transmitter aktiviert ist, bietet der Realm neben der OpenID-Endpunktkonfiguration einen Endpunkt für die SSF-Konfigurationsmetadaten an. Die URLs beider Endpunkte benötigen Sie in Identity Provider verbinden:

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

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

Die URLs verwenden die Standardwerte der Keycloak-App: den Host ucs-sso-ng.DOMAIN und den Realm ucs, der die Benutzer der Domäne enthält. Wenn Sie keycloak/server/sso/fqdn geändert haben oder einen anderen Realm verwenden, passen Sie die URLs entsprechend an.

5.3.3. Client Scopes anlegen#

Legen Sie auf der Seite Client scopes des Realms die Client Scopes ssf.manage und ssf.read an, jeweils mit aktivierter Option Include in token scope.

5.3.4. OIDC-Client anlegen#

  1. Klicken Sie auf der Seite Clients des Realms auf Create client.

  2. Geben Sie auf der Seite General settings apple-asm als Client ID ein.

  3. Tragen Sie auf der Seite Capability config die Einstellungen aus der folgenden Tabelle ein.

    Tab. 5.1 Fähigkeiten des OIDC-Clients für Apple School Manager#

    Einstellung

    Wert

    Client authentication

    On

    Authentication flow

    Standard flow

    Require PKCE

    Off

    SSF Receiver

    On

    Apple scheint PKCE für OIDC-Föderationen nicht zu unterstützen, weshalb der Client es deaktiviert. Die Seite bietet SSF Receiver erst an, wenn Client authentication aktiviert ist und Sie SSF-Feature aktivieren und Realm zum SSF-Transmitter machen abgeschlossen haben.

  4. Tragen Sie auf der Seite Login settings die Einstellungen aus der folgenden Tabelle ein und klicken Sie auf Save.

    Tab. 5.2 Anmeldeeinstellungen des OIDC-Clients für Apple School Manager#

    Einstellung

    Wert

    Valid redirect URIs

    https://gsa-ws.apple.com/grandslam/GsService2/acs

    Valid post logout redirect URIs

    +

Kopieren Sie das Client Secret aus dem Reiter Credentials. Sie benötigen es in Identity Provider verbinden.

5.3.5. Client als SSF-Receiver konfigurieren#

  1. Fügen Sie im Reiter Client scopes des Clients ssf.manage, ssf.read und offline_access als Default hinzu.

  2. Fügen Sie im Reiter Roles die Client-Rolle ssf-admin hinzu.

  3. Tragen Sie im Reiter SSF die Einstellungen aus der folgenden Tabelle ein.

Tab. 5.3 SSF-Einstellungen des Clients#

Einstellung

Wert

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

Klicken Sie auf Select role, wählen Sie Client roles und wählen Sie ssf-admin aus.

Allowed delivery methods

Nur Push Delivery

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 sendet das Verifizierungsereignis, sobald Apple den Stream anlegt. Mit Emit-only events steuern Sie über die Keycloak-API, wann Keycloak eine Abmeldung an Apple sendet.

5.3.6. Administrativen Benutzer anlegen#

Apple School Manager baut die Verbindung zu Keycloak mit dem Authorization Code Flow auf. Das resultierende Access Token und Refresh Token gehören zu einer Offline-Sitzung eines Benutzers, daher muss dieser Benutzer existieren, bevor Sie die beiden Systeme verbinden.

Legen Sie den Benutzer in Keycloak an, nicht in UCS. Keycloak hat nur Lesezugriff auf die Benutzer aus UCS und kann ihnen deshalb keine Client-Rollen zuweisen.

  1. Legen Sie im Realm ucs einen Benutzer an, zum Beispiel asm.

  2. Setzen Sie Vorname, Nachname und E-Mail-Adresse.

  3. Setzen Sie im Reiter Credentials ein starkes Passwort. Zwei-Faktor-Authentifizierung ist optional, aber empfohlen.

  4. Weisen Sie die Client-Rolle ssf-admin des Clients apple-asm zu.

5.4. Apple School Manager konfigurieren#

5.4.1. Identity Provider verbinden#

  1. Melden Sie sich bei Apple School Manager an.

  2. Öffnen Sie Preferences ‣ Managed Apple Accounts.

  3. Stellen Sie sicher, dass Ihre Domain verifiziert ist.

  4. Klicken Sie unter User sign-in and directory sync auf Configure. Wenn bereits ein anderer Identity Provider verbunden ist, trennen Sie diesen zuerst.

  5. Wählen Sie Custom Identity Provider aus und klicken Sie auf Continue.

  6. Geben Sie einen Namen für den Identity Provider ein, zum Beispiel asmkc.

  7. Geben Sie die Client-ID und das Client Secret aus OIDC-Client anlegen sowie die beiden URLs aus Realm zum SSF-Transmitter machen ein, wie in der folgenden Tabelle aufgeführt.

    Tab. 5.4 Einstellungen des benutzerdefinierten Identity Providers in Apple School Manager#

    Feld

    Wert

    Client ID

    apple-asm

    Client Secret

    Das Client Secret aus dem Reiter Credentials des Clients

    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. Klicken Sie auf Continue.

  9. Klicken Sie im sich öffnenden Fenster auf die Anmeldeschaltfläche Ihres Identity Providers, zum Beispiel Sign in with asmkc.

  10. Melden Sie sich mit dem administrativen Benutzer aus Administrativen Benutzer anlegen an.

Apple School Manager zeigt Authorizing Account an und bestätigt dann die Verbindung. Beim Verbinden legt Apple einen SSF-Stream für den Client an, den Sie in Keycloak im Reiter SSF Streams des Clients sehen.

5.4.2. Föderation für die Domain aktivieren#

  1. Öffnen Sie Preferences ‣ Managed Apple Accounts.

  2. Wählen Sie Ihre Domain aus und klicken Sie auf Manage.

  3. Suchen Sie unten auf der Seite den Abschnitt für Ihren Identity Provider und klicken Sie auf Set up.

  4. Stellen Sie den erscheinenden Schalter auf On.

  5. Wenn der SFTP-Upload die Domain verwendet, fordert Apple School Manager Sie auf, eine andere Domain für den Upload zu wählen. Wählen Sie eine beliebige andere Domain.

Apple School Manager aktiviert die Föderation für die Domain und sendet eine Bestätigungs-E-Mail.

Danach meldet sich jeder Managed Apple Account mit einer E-Mail-Adresse in der Domain über Keycloak an. Das gilt auch für Konten, die es bereits vor der Aktivierung der Föderation gab, und für Konten, die Sie in Apple School Manager manuell angelegt haben.

Der Upload des Connectors funktioniert weiterhin. Apple School Manager ordnet die Konten anhand der Domain ihrer E-Mail-Adresse zu, sodass die Konten aus dem Upload zur föderierten Domain gehören, unabhängig von der Domain, die Sie für den SFTP-Upload gewählt haben.

5.5. Auf einem Gerät anmelden#

Nachdem Sie die Föderation für die Domain aktiviert haben, melden sich Ihre Benutzer mit ihren UCS@school-Anmeldedaten an einem Apple-Gerät an. Die folgenden Schritte beschreiben ein nicht gekoppeltes Gerät. Das allgemeine Vorgehen beschreibt Apple Inc. [8].

  1. Öffnen Sie Settings ‣ Apple Account.

  2. Tippen Sie auf Sign In Manually.

  3. Geben Sie die E-Mail-Adresse des Benutzers in der föderierten Domain ein und tippen Sie auf Proceed.

  4. Das Gerät zeigt einen Hinweis an, der Ihre Organisation nennt. Tippen Sie auf Proceed.

  5. Die Keycloak-Anmeldeseite öffnet sich mit bereits ausgefülltem Benutzernamen. Geben Sie das Passwort ein.

  6. Geben Sie die Geräte-PIN ein, wenn das Gerät danach fragt.

Nach der Anmeldung zeigt Settings ‣ Apple Account den Benutzer mit der E-Mail-Adresse aus UCS@school an.

Auf dieser Seite