Diese Referenz richtet sich an die technische Betreuung einer externen Anwendung. Die Einrichtung im Marketplace beschreibt Externe Anwendungen über OpenID Connect anbinden. Hier geht es darum, welche Daten Ihre Anwendung aus dem ID-Token lesen kann und welche Annahmen sie dabei vermeiden muss.
Ein Scope bezeichnet einen angefragten Datenbereich. Ein Claim ist ein einzelnes Feld im Token, etwa schoolid. Die Anwendung muss die benötigten Scopes anfragen; ihre Freischaltung in der Client-Konfiguration allein ist kein Nachweis, dass sie bei einem konkreten Anmeldevorgang gewährt wurden.
Die Beispiele sind erfundene, gekürzte JSON-Ausschnitte, keine gültigen Tokens und keine Kundendaten. Prüfen Sie vor Inbetriebnahme die tatsächlich gewährten Scopes und Daten Ihrer Gegenstelle mit vereinbarten Testkonten. Die Referenz beschreibt den geprüften Implementierungsstand; ältere Installationen können davon abweichen.
Welche Scopes brauchen Sie?
| Zweck | Scope | Ergebnis und Grenze |
|---|---|---|
| Anmeldung | openid |
OIDC-ID-Token mit der Benutzerkennung sub; keine Schul- oder Klassenliste allein durch diesen Scope. |
| Name und Rolle anzeigen | profile |
name, family_name, given_name, role; Namen können leer sein. |
| E-Mail verwenden | email |
email; kann leer sein. Keine Zusicherung einer bestätigten E-Mail-Adresse. |
| Telefonnummer verwenden | phone |
phone_number für Lehrkräfte, soweit hinterlegt; für Lernende wird dieses Feld nicht ausgegeben. |
| Aktive Schule und Medienzentrum zuordnen | antares.context.v2 |
Kontext, aufgelöste Schulkennung und Rolle. Für neue Integrationen empfohlen. |
| Bestehende Kontextintegration weiterführen | antares.context |
Älteres Kontextformat. Nicht zusammen mit v2 anfordern. |
| Schulnamen anzeigen | antares.schoolname |
schoolname; kein Ersatz für die Schulkennung. |
| Gestartetes Medium bestimmen | antares.product |
product, die technische Medienkennung der Anbindung. |
| Verfügbare Kurse/Gruppen lesen | antares.classes |
classes, eine Liste der für den angemeldeten Benutzer verfügbaren Gruppen. Keine vollständige Schulliste zugesichert. |
| Lernendenzuordnungen zu Edupool-Kursen lesen | antares.students |
students, nach Kurskennung gruppiert; bei externen Gruppenquellen derzeit leer. |
| Lehrkräfteliste lesen | antares.teachers |
Derzeit deaktiviert: Der Scope erzeugt keine teachers-Liste, obwohl er im Editor angeboten wird. |
Der Marketplace-Editor weist darauf hin, dass openid und offline automatisch hinzugefügt werden. Die Bezeichnung dort lautet ausdrücklich offline, nicht offline_access. Daraus folgt keine Garantie, dass jeder Anmeldeablauf einen Refresh-Token liefert. Stimmen Sie dessen Verwendung und Aufbewahrung gesondert ab.
Für eine reine Anmeldung mit Schulzuordnung benötigen Sie nicht automatisch Lernendenlisten, Telefonnummern oder E-Mail-Adressen. Wählen Sie Daten nach dem tatsächlichen Zweck und klären Sie die Verarbeitung personenbezogener Angaben vorab.
ID-Token sicher auswerten
Verwenden Sie eine OIDC-Bibliothek, um Signatur, erwarteten Aussteller (iss), Client-Zielgruppe (aud), Ablauf (exp) und die für Ihren Ablauf erforderliche Nonce zu prüfen. Ein bloß dekodiertes JSON ist noch kein vertrauenswürdiger Anmeldenachweis. Die Discovery-/Issuer-Adresse liefert Ihre technische Gegenstelle; sie ist nicht die OpenID-URL im Marketplace-Editor.
| Feld | Bedeutung |
|---|---|
sub |
Benutzerkennung beim Aussteller. Behandeln Sie sie als undurchsichtigen String. Verwenden Sie zusammen mit iss eine stabile Benutzerzuordnung, nicht den Namen oder die E-Mail. |
iss |
Aussteller des Tokens; muss zur vereinbarten Gegenstelle passen. |
aud |
Zielgruppe des Tokens, als String oder Liste; muss Ihre Client-ID enthalten. |
exp, iat |
Ablauf- und Ausstellungszeit als Unix-Zeitstempel in Sekunden. |
auth_time, nonce, sid, jti |
Je nach Ablauf zusätzliche Angaben zur Anmeldung, Sitzung oder Tokenkennung. Nicht als immer vorhanden voraussetzen. |
Scopes vergeben keine eigenständigen Medienlizenzen. Die Daten einer Schule oder Gruppe sind auch keine Zusage, dass Ihre Anwendung damit beliebige Inhalte oder Verwaltungsaktionen freigeben darf. Prüfen Sie die vorgesehenen Rechte zusätzlich.
Profil, E-Mail und Telefonnummer
Bei profile wird die Rolle ausgegeben. L bezeichnet Lehrkräfte, S Lernende. Behandeln Sie unbekannte Rollen nicht automatisch als Lehrkraft oder Administration.
{
"name": "Alex Beispiel",
"family_name": "Beispiel",
"given_name": "Alex",
"role": "L",
"email": "alex@example.com",
"phone_number": ""
}
Dieser Ausschnitt setzt die Scopes profile, email und phone voraus. Namen und E-Mail werden für Lehrkräfte und bestimmte kontobasierte Lernendenanmeldungen bereitgestellt, soweit hinterlegt. Bei einer reinen EDU-ID-Anmeldung können die Namensfelder und die E-Mail leer sein. phone_number wird nur für die Rolle L gesetzt und kann ebenfalls leer sein. Eine gewählte Datenfreigabe erzeugt keine fehlenden Stammdaten; die Implementierung ergänzt hier auch kein email_verified.
Context v2: die aktive Schule erkennen
antares.context.v2 liefert:
| Claim | Bedeutung |
|---|---|
context |
String im Format land/standort/schoolid, mit der aufgelösten Kennung der aktiven Schule. |
land |
Edupool-Landes-/Systemkennung, beispielsweise NRW oder BW; kein ISO-Ländercode wie DE. |
standort |
Technische Standortkennung innerhalb dieses Landes-/Systemkontexts. |
sitename |
Lesbarer Standortname, etwa der Name des Medienzentrums; kann fehlen beziehungsweise leer sein. |
schoolid |
Aufgelöste Kennung der aktiven Schule. Als String behandeln, führende Nullen erhalten. |
role |
Rolle des angemeldeten Benutzers, beispielsweise L oder S. |
central_school_number |
Zusätzliche zentrale Schulnummer aus den Stammdaten; kann leer oder null sein und muss nicht mit schoolid übereinstimmen. |
context_signature |
Zusätzlich signierter Kontextwert. Kein Ersatz für die OIDC-Tokenprüfung; ein separates Prüfverfahren mit Antares abstimmen, falls Ihre Anwendung ihn verwenden soll. |
schoolid und context beziehen sich auf die aktive Schule. central_school_number, schoolname und die beschreibenden Felder des school-Objekts stammen dagegen aus dem vom Benutzerobjekt gelieferten Schuldatensatz. Setzen Sie insbesondere bei einem Schulwechsel nicht ungeprüft voraus, dass diese Angaben zur aktiven Schule gehören; prüfen Sie das mit der Gegenstelle. Eine andere Nummer derselben Schule und Angaben zu einer anderen Schule sind unterschiedliche Fälle.
{
"context": "NRW/DEMO/001234",
"land": "NRW",
"standort": "DEMO",
"sitename": "Beispiel-Medienzentrum",
"schoolid": "001234",
"central_school_number": "009999",
"role": "L"
}
context_signature ist in diesem Ausschnitt weggelassen. Das Beispiel zeigt bewusst unterschiedliche Schulnummern. Für die Kontextzuordnung ist hier 001234 maßgeblich, nicht 009999. Verwenden Sie die Schulkennung zusammen mit Landes-/Standortkontext, statt globale Eindeutigkeit einer Nummer vorauszusetzen.
Wechselt ein Benutzer die aktive Schule, können sich Kontext und Schulkennung ändern, ohne dass ein anderer Mensch angemeldet ist. Trennen Sie deshalb die Benutzeridentität (iss und sub) von der aktuellen Einrichtung. Bei kontobasierten Lernenden können einzelne Gruppen außerdem zu anderen Schulkontexten gehören; beachten Sie die Angaben pro Gruppe.
Warum v1 und v2 nicht austauschbar sind
Bei antares.context lautet context weiterhin land/standort/customer: Die letzte Komponente stammt aus der Sitzung und kann eine Aliasnummer sein. schoolid wird dagegen bereits auf die aktive Schulkennung aufgelöst. In v1 muss die letzte Kontextkomponente deshalb nicht mit schoolid übereinstimmen. V2 verwendet für beide dieselbe aufgelöste Kennung.
Beide Scopes schreiben gleichnamige Claims. Fordern Sie nur einen an; bei gemeinsamer Anfrage kann die Verarbeitungsreihenfolge bestimmen, welcher Wert übrig bleibt. Eine Umstellung auf v2 kann gespeicherte Schulzuordnungen verändern. Vergleichen und migrieren Sie diese Zuordnungen vor dem Wechsel, besonders bei Schulen mit Aliasnummern.
Schulname, Schulstammdaten und Produkt
antares.schoolname liefert den String schoolname. antares.product liefert den String product, etwa demo-000123. Weder Schulname noch Produktkennung ersetzen die Benutzerkennung. Ein Schulname kann sich ändern oder mehrfach vorkommen.
Die Gegenstelle unterstützt zusätzlich antares.school mit einem strukturierten school-Objekt. Dieser Scope ist in der hier beschriebenen Marketplace-Auswahl derzeit nicht angeboten. Verwechseln Sie ihn nicht mit antares.schoolname. Wenn Ihre Integration ihn benötigt, stimmen Sie seine Freischaltung gesondert ab.
{
"school": {
"id": "001234",
"name": "Beispielschule",
"kkz": "",
"website": "https://example.com/schule",
"street": "Beispielweg 1",
"city": "Beispielstadt",
"zip": "01234",
"updatedAt": "2026-10-01T08:30:00Z"
},
"schoolid": "001234",
"schoolname": "Beispielschule"
}
kkz ist ein Kennzeichen aus den Schulstammdaten. Nicht vorhandene Stammdaten werden als leere Strings ausgegeben. updatedAt ist bei vorhandenem, lesbarem Änderungsdatum eine UTC-Zeit im gezeigten Format, sonst leer. Postleitzahl und Schulkennung sind Strings, keine Zahlen.
Auch im school-Objekt wird id auf die aktive Schulkennung aufgelöst; die beschreibenden Angaben werden aber nicht eigens anhand dieser Kennung neu geladen. Beachten Sie die oben erklärte Datenherkunft, bevor Sie vorhandene Schulstammdaten damit überschreiben.
antares.classes: Kurse und Gruppen
classes ist eine JSON-Liste. Der Name des Scopes bedeutet nicht, dass alle Einträge Schulklassen sind: Es können auch Kurse, Arbeitsgemeinschaften und synchronisierte Gruppen sein.
{
"classes": [
{
"identifier": "42",
"titel": "Naturwissenschaften 7a",
"class": "7",
"start": "2026-08-01",
"end": "2027-07-31",
"enddeu": "31.07.2027",
"info": "Beispielkurs",
"source": "edupool",
"school_id": "001234",
"school_context": "NRW/DEMO"
}
]
}
| Feld | Bedeutung und Verarbeitung |
|---|---|
identifier |
Gruppenkennung; nicht als weltweit eindeutig voraussetzen. Bei externen Gruppen kann sie auch numerisch geliefert werden; für Vergleiche verlustfrei als Kennung normalisieren. |
titel |
Anzeigename. Der Feldname lautet tatsächlich titel, nicht title. |
class |
Klassenstufe, etwa 7, S für Sonstige oder ein leerer Wert. |
start, end |
Kursdaten im Format YYYY-MM-DD. Bei synchronisierten Gruppen können dies technische Platzhalter sein, kein tatsächliches Schuljahresintervall. |
enddeu |
Optionaler, deutsch formatierter Anzeigewert; kann leer sein oder fehlen. Verwenden Sie für Verarbeitung nicht dieses Anzeigefeld. |
info |
Beschreibung beziehungsweise quellenspezifische Information. Nicht als unveränderliche Kennung verwenden. |
source |
Herkunft: derzeit edupool, iserv oder schulportal_berlin. Auch Moin.Schule wird in dieser Verarbeitung als iserv gekennzeichnet. |
school_id, school_context |
Schulkennung und Landes-/Standortkontext der jeweiligen Gruppe. Bei schulübergreifender kontobasierter Teilnahme können sie vom aktiven Anmeldekontext abweichen. |
Bilden Sie Gruppenzuordnungen aus Herkunft, Schulkontext, Schulkennung und Gruppenkennung, nicht allein aus dem Titel oder einer Nummer. Zusätzliche Felder können vorkommen; ignorieren Sie unbekannte Felder, statt das gesamte Token deshalb abzulehnen.
Die Auswahl hängt vom angemeldeten Benutzer und dessen Gruppenberechtigungen ab. Lernende erhalten keine Zusicherung einer vollständigen Kurs- oder Schulliste. Auch abgelaufene Edupool-Kurse können in classes vorkommen; bei externen Gruppen sind Datumsfelder teilweise Platzhalter. Verwenden Sie die bloße Anwesenheit eines Eintrags deshalb nicht als alleinige Zugangsprüfung.
Eine leere Liste kann bedeuten, dass keine Gruppen verfügbar sind; die Gegenstelle liefert sie auch bei bestimmten Fehlern beim Gruppenabruf. classes: [] ist somit kein verlässlicher Anlass, zuvor gespeicherte Gruppen und Mitgliedschaften unwiderruflich zu löschen.
antares.students: Lernendenzuordnungen
Bei Edupool-Kursen werden Lernende nach Gruppenkennung zusammengefasst. Eine Lehrkraft erhält die nach ihren Kursberechtigungen verfügbaren Einträge; bei Lernenden wird die Auswahl auf die eigene EDU-ID beziehungsweise die eigene kontobasierte Teilnahme eingeschränkt. Der Scope ist keine vollständige Schülerverwaltung.
Für externe Produzenten werden EDU-Schlüssel vor der Ausgabe in Großbuchstaben umgewandelt und anschließend mit SHA-256 gehasht. edukey ist daher ein 64-stelliger hexadezimaler Hash, kein einlösbarer EDU-Schlüssel. name ist die beim Kurs hinterlegte Bezeichnung und nicht zwingend ein amtlicher vollständiger Name.
{
"students": {
"42": [
{
"name": "Beispielteilnahme",
"edukey": "229f2b9d607e4b6e19f36c922821c8284693e0d31b8a7a68b0c03fbd88a62c5d"
}
]
}
}
Die Kennung 42 verweist auf die Gruppe. Die technische PHP-Ausgabe kann bei leerem Bestand [] statt {} liefern; abhängig von numerischen Gruppenschlüsseln ist auch eine Listenform möglich. Verarbeiten Sie die Antwort als Zuordnung von Gruppenkennungen zu Teilnehmerlisten und prüfen Sie den tatsächlich gelieferten JSON-Typ. Ein fehlendes students-Feld ist von einer gewährten, aber leeren Ausgabe zu unterscheiden.
Bei den externen Gruppenquellen IServ, Moin.Schule und Schulportal Berlin liefert antares.students derzeit []. Gruppen können also vorhanden sein, ohne dass dieser Scope Teilnehmer dazu liefert. Die Ausgabe ist ebenfalls bei bestimmten Abruffehlern leer; sie beweist nicht, dass eine Gruppe keine Lernenden hat.
Wann passt edukey zu sub?
Bei einer EDU-ID-Anmeldung kann der gehashte Schlüssel mit sub übereinstimmen. Das gilt nicht allgemein für jede Lernendenanmeldung. Bei einem mit einem Benutzerkonto verknüpften Kurszugang kann sub eine eigene stabile Kontokennung sein. Führen Sie Benutzer und Lernendenlisten deshalb nicht ungeprüft über students[*].edukey == sub zusammen.
Interne, gesondert behandelte Antares-Clients können zusätzliche subject-Angaben und ungehashte Schlüssel erhalten. Externe Produzenten dürfen diese Sonderbehandlung nicht voraussetzen; bei ihnen wird subject aus den Teilnehmerdaten entfernt. Eine Umbenennung des Clients ist kein Verfahren, um diese internen Daten anzufordern.
Auch gehashte Kennungen und kursbezogene Namen sind schutzbedürftige Daten. Begrenzen Sie Speicherung, Zugriffe und Protokollierung. Veröffentlichen Sie keine vollständigen Tokens oder Teilnehmerlisten als Fehlerbeleg.
Abnahme und typische Fallstricke
- Testen Sie Anmeldung und Tokenprüfung mit der abgestimmten OIDC-Gegenstelle. Prüfen Sie zusätzlich fehlende, leere und unbekannte Claims.
- Vergleichen Sie bei einer Schule mit Aliasnummer die v2-Schulkennung mit dem aktiven Kontext. Testen Sie, soweit vorgesehen, auch einen Schulwechsel desselben Kontos.
- Prüfen Sie Gruppenherkunft und die Kennungen jeder Gruppe. Ein Gruppenname allein darf keine vorhandene Gruppe einer anderen Schule überschreiben.
- Testen Sie getrennt eine Lehrkraft, eine EDU-ID-Teilnahme und eine kontobasierte Lernendenanmeldung, soweit Ihre Anwendung diese Zugänge unterstützt.
- Prüfen Sie bei externen Gruppenquellen den erwarteten Fall „Gruppen vorhanden,
studentsleer“. Stellen Sie eine fehlende Teilnehmerliste nicht als technische Zusage einer leeren Klasse dar. - Verwenden Sie
antares.teachersnicht als Grundlage einer erforderlichen Funktion, solange die Gegenstelle keine entsprechende Ausgabe ausdrücklich bestätigt.
Die frühere Helpcenter-Referenz dokumentiert v1 und eine Lehrkräfteliste. Für neue Integrationen sind insbesondere v2, Gruppenherkunft und die oben beschriebenen Einschränkungen maßgeblich. Klären Sie abweichende Antworten mit Antares anhand von Client-ID, betroffenen Scopes, Zeitpunkt und bereinigter Fehlermeldung; senden Sie keine Secrets oder vollständigen Tokens.