Dokumentation
Anleitung

Externe Anwendungen über OpenID Connect anbinden

Externe Anwendungen über OpenID Connect anbinden.

Auf dieser Seite

Mit der OIDC-Konfiguration verbinden Sie ein Medium im Marketplace mit Ihrer externen Anwendung. OpenID Connect (OIDC) wird dabei für die Anmeldung verwendet. Die Anwendung muss diese Anbindung bereits unterstützen; die Einstellungen im Marketplace ersetzen keine technische Einrichtung auf Ihrer Seite.

Diese Anleitung richtet sich an Medienproduzenten gemeinsam mit der technischen Betreuung ihrer Anwendung. Die Einrichtungsschritte stehen hier; die konkrete Bedeutung der Scopes, Claims und JSON-Datenformate erklärt die technische Referenz OIDC-Scopes und Datenformate für externe Anwendungen.

Was Sie mit Ihrer technischen Betreuung vorbereiten

Lassen Sie sich vor dem Öffnen des Dialogs die Anmelde-Startadresse, die Rücksprungadressen, Basic/Post, benötigte Scopes und die öffentlichen Links zu Datenschutz und Nutzungsbedingungen bestätigen. Vereinbaren Sie außerdem die sichere Secret-Übergabe und ein berechtigtes Testkonto. Client-ID und Secret müssen auch in Ihrer Anwendung eingerichtet werden. Die Redaktion muss dafür weder Tokens auslesen noch Teilnehmerlisten verarbeiten.

Die Abbildungen zeigen die tatsächliche Oberfläche mit einer Beispielkonfiguration. Adressen unter example.com sind keine funktionsfähige Anbindung. Es werden keine echten Secrets oder personenbezogenen Daten gezeigt.

1. Voraussetzungen klären

  • Sie haben einen Zugang als Medienproduzent und können das betreffende Medium unter Meine Medien → Bearbeiten öffnen.
  • Das Medium ist bereits angelegt. Prüfen Sie die Anbindung zunächst an einem Testmedium, nicht an einem laufenden Angebot.
  • Eine technische Ansprechperson Ihrer Anwendung hat die Anmelde-Startadresse, die zulässigen Rücksprungadressen und die unterstützte Authentifizierungsmethode bereitgestellt.
  • Sie haben abgestimmt, welche Daten Ihre Anwendung benötigt und welche Scopes dafür ausgewählt werden sollen.
  • Die Links zu Datenschutzerklärung und Nutzungsbedingungen liegen vor. Verwenden Sie dafür öffentlich erreichbare HTTPS-Adressen.
  • Ein berechtigtes Testkonto steht für den anschließenden Aufruf des Mediums bereit.

Weitere technische Angaben zur OIDC-Gegenstelle, etwa eine gegebenenfalls benötigte Issuer- oder Discovery-Adresse, müssen Sie mit der technischen Betreuung klären. Der hier beschriebene Dialog zeigt dafür kein eigenes Feld.

Zuständigkeiten vor der Neuanlage abstimmen

Vereinbaren Sie, wer das Secret sicher bereitstellt, wer Client-ID und Gegenstellenwerte in Ihrer Anwendung übernimmt und wer den Abnahmetest durchführt. Halten Sie Anmelde-Startadresse, Rücksprungadressen, Methode und benötigte Scopes in einer gemeinsamen Checkliste fest; speichern Sie das Secret getrennt in der sicheren Ablage. Die automatisch erzeugte Client-ID allein richtet die Gegenstelle nicht ein. Wenn bei der ersten Einrichtung Angaben fehlen, klären Sie diese vor dem produktiven Einsatz mit der technischen Betreuung, statt auf eine automatische Secret-Ausgabe zu vertrauen.

2. Konfiguration des richtigen Mediums öffnen

  1. Öffnen Sie marketplace.edupool.de.
  2. Wählen Sie Gast → Anmelden → Medienproduzent, wählen Sie Ihren Produzenten und melden Sie sich mit Ihren Zugangsdaten an.
  3. Öffnen Sie Meine Medien und wechseln Sie von Ansicht zu Bearbeiten.
  4. Suchen Sie das Medium anhand seiner Mediennummer oder seines Titels.
  5. Öffnen Sie in der Spalte OIDC das Schloss-Symbol mit der Bezeichnung OIDC-Konfiguration.
  6. Kontrollieren Sie im Dialog OpenID Connect konfigurieren nochmals Titel und Mediennummer.

Bearbeitungsansicht mit der OIDC-Aktion in der Medienzeile

3. Client-Identifikation einrichten

Die Client-ID identifiziert die Anbindung Ihrer Anwendung. Das Secret ist die dazugehörige vertrauliche Zugangsinformation.

  1. Prüfen Sie das Feld Client-Id. Es ist schreibgeschützt und laut Oberfläche automatisch generiert. Tragen Sie hier keine eigene Kennung ein. Falls bei einer neuen Konfiguration noch keine ID angezeigt wird, prüfen Sie die Anzeige nach dem Speichern erneut.
  2. Tragen Sie unter Name einen verständlichen Namen für die Anwendung ein.
  3. Stimmen Sie für eine neue Anbindung das Setzen des Secret mit Ihrer technischen Ansprechperson ab. Verlassen Sie sich nicht darauf, dass der Dialog Ihnen ein neues Secret zum Kopieren erzeugt.
  4. Bei einer bestehenden Anbindung lassen Sie Secret leer, wenn Sie es nicht ändern möchten. Nur ein ausgefülltes Secret-Feld wird beim Speichern zur Änderung übermittelt.

Das Secret wird im Eingabefeld verdeckt dargestellt. Das Augen-Symbol macht eine Eingabe sichtbar; es ist keine Funktion zum Abrufen eines verlorenen Secrets. Ein vorhandenes Secret wird nicht im Klartext zur Verfügung gestellt.

Secret sicher behandeln

  • Legen Sie das vereinbarte Secret in einer dafür vorgesehenen sicheren Ablage ab, zum Beispiel einem Passwortmanager.
  • Übermitteln Sie es nur über einen mit der technischen Gegenstelle abgestimmten sicheren Kanal.
  • Nehmen Sie es nicht in CSV-Dateien, E-Mails, Tickets, Screenshots oder allgemein zugängliche Dokumente auf. Auch Zugangstokens gehören dort nicht hinein.
  • Stimmen Sie einen Secret-Wechsel zeitlich mit der Anwendung ab. Unterschiedliche Werte auf beiden Seiten können die Anmeldung unterbrechen.
  • Ist ein Secret offengelegt worden oder verloren gegangen, klären Sie einen kontrollierten Wechsel mit Ihrer technischen Betreuung. Löschen Sie dafür nicht vorschnell die gesamte OIDC-Konfiguration.

Client-Identifikation mit Beispielname, Client-ID und leerem Secret-Feld

4. Adressen richtig zuordnen

Die OpenID-URL und die Redirect-URIs haben unterschiedliche Aufgaben. Übernehmen Sie die Adressen vollständig von Ihrer technischen Gegenstelle. Die folgenden URLs sind nur Beispiele, keine funktionsfähigen Vorgaben.

Feld Was gehört hinein? Beispiel
OpenID-URL im Bereich Integration Die Seite Ihrer Anwendung, die den OIDC-Anmeldeablauf startet. Beim Öffnen des Mediums werden Nutzer dorthin weitergeleitet. Hier gehört nicht die Discovery-Adresse eines Identitätsdienstes hinein. https://example.com/login/edupool
Redirect-URIs Die vereinbarten Rücksprungadressen Ihrer Anwendung für den Anmeldeablauf. Diese sind nicht automatisch mit der Startadresse identisch. https://example.com/callback
Post-Logout-Redirect-URIs Erlaubte Zieladressen nach einer von der Anwendung angestoßenen Abmeldung (RP-initiiertes Logout). Stimmen Sie mit der technischen Gegenstelle ab, ob diese Funktion genutzt wird. https://example.com/logged-out
  1. Geben Sie jede Redirect-URI einzeln ein und bestätigen Sie sie mit Enter. Kontrollieren Sie, dass jede Adresse als eigener Eintrag erscheint.
  2. Ergänzen Sie entsprechend die vereinbarten Post-Logout-Redirect-URIs, sofern benötigt. Prüfen Sie auch hier, dass die Einträge übernommen wurden.
  3. Entfernen Sie falsche Einträge über das Schließen-Symbol am jeweiligen Eintrag.
  4. Tragen Sie unter Integration → OpenID-URL die Anmelde-Startadresse ein.

Verwenden Sie für produktive Adressen HTTPS und nur ausdrücklich vereinbarte Ziele. Achten Sie auf Schreibweise, Pfad und gegebenenfalls abschließende Schrägstriche. Ein erfolgreiches Speichern allein bestätigt noch nicht, dass die Adressen technisch richtig sind.

5. Scopes und Methode auswählen

Scopes bezeichnen die angefragten Datenbereiche. Wählen Sie nur die mit Ihrer technischen Gegenstelle abgestimmten, tatsächlich benötigten Einträge aus.

Die Oberfläche bietet folgende Auswahl:

Anzeige Technischer Scope
Profilinformationen profile
E-Mail email
Telefonnummer phone
Context v2 – empfohlen antares.context.v2
Context v1 – veraltet, nur für bestehende Integrationen antares.context
Name der Institution antares.schoolname
ID des Mediums antares.product
Edu-Ids antares.classes
Liste der Lernenden antares.students
Liste der Lehrenden antares.teachers

Der Dialog weist darauf hin, dass openid und offline automatisch hinzugefügt werden. Diese stehen nicht als eigene Auswahloptionen bereit. Die Bezeichnung lautet hier ausdrücklich offline.

Für neue Integrationen wählen Sie den abgestimmten Context v2, nicht zusätzlich v1. Beide schreiben gleichnamige Felder und können unterschiedliche Schulnummern liefern. Ändern Sie eine bestehende v1-Anbindung nur nach Prüfung der gespeicherten Schulzuordnungen.

Die Auswahl im Editor ist nicht dasselbe wie eine garantierte Datenlieferung: antares.classes liefert Kurse und Gruppen, keine einzelnen EDU-Schlüssel. antares.students ist bei externen Gruppenquellen derzeit leer. antares.teachers wird zwar angeboten, erzeugt derzeit aber keine Lehrkräfteliste. Namen und E-Mail können je nach Konto leer sein. Welche Felder Sie zuverlässig verwenden können, prüfen Sie mit Ihrer technischen Betreuung anhand der Scope-Referenz OIDC-Scopes und Datenformate für externe Anwendungen und Ihrer Testkonten.

Wählen Sie unter Method die von Ihrer Anwendung unterstützte Methode zur Authentifizierung am Token-Endpunkt:

  • Basic (client_secret_basic)
  • Post (client_secret_post)

Bei einer neuen Konfiguration ist Basic voreingestellt. Übernehmen Sie die Methode nicht ungeprüft: Sie muss zu Ihrer Anwendung passen.

OAuth-Einstellungen mit bestätigten Beispieladressen, ausgewählten Scopes und Methode

OpenID-URL als Startadresse des Anmeldeablaufs

6. Rechtliche Informationen ergänzen

  1. Tragen Sie unter Datenschutzerklärung die zu Ihrer Anwendung gehörende Adresse ein.
  2. Ergänzen Sie unter Nutzungsbedingungen die entsprechende Adresse.
  3. Öffnen Sie beide Links zur Kontrolle separat. Sie sollten ohne Anmeldung über HTTPS erreichbar sein und zum richtigen Angebot gehören.

Öffentliche Links zu Datenschutzerklärung und Nutzungsbedingungen

7. Speichern und kontrollieren

  1. Prüfen Sie Titel und Mediennummer sowie alle eingegebenen Adressen, Scopes und die Methode.
  2. Wählen Sie Speichern im OIDC-Dialog. Die OIDC-Konfiguration wird separat gespeichert, nicht über das Speichern-Symbol für die Metadaten der Tabelle.
  3. Warten Sie auf OIDC-Konfiguration gespeichert. Der Dialog bleibt geöffnet und lädt die Konfiguration erneut.
  4. Prüfen Sie die geladenen Angaben und die Client-ID. Das Secret-Feld wird nach erfolgreichem Speichern geleert; geben Sie es nicht allein deshalb erneut ein.
  5. Übernehmen Sie die Client-ID und die abgestimmten Einstellungen in Ihre Anwendung beziehungsweise geben Sie sie an die zuständige technische Betreuung weiter. Übermitteln Sie das Secret getrennt über den sicheren Kanal.
  6. Schließen Sie den Dialog erst nach der Kontrolle.

Abbrechen oder das Schließen-Symbol schließen den Dialog ohne Speichern der noch offenen Eingaben. Bereits erfolgreich gespeicherte Änderungen werden dadurch nicht zurückgenommen.

Speicherrückmeldung einer Beispielkonfiguration mit leerem Secret-Feld

8. Anbindung mit einem Testkonto prüfen

Der Dialog enthält keine eigene Test-Schaltfläche. Testen Sie deshalb anschließend den tatsächlichen Aufruf des Mediums über den für Ihre Nutzer vorgesehenen Zugang.

  1. Verwenden Sie ein Testkonto, das für das Medium berechtigt ist. Der Produzenten-Editor allein ist kein Nachweis für den erfolgreichen Nutzerzugriff.
  2. Öffnen Sie das Medium und kontrollieren Sie, ob die erwartete externe Anwendung erreicht wird.
  3. Prüfen Sie mit Ihrer technischen Gegenstelle, ob die Anmeldung abgeschlossen wird und der richtige Inhalt zugänglich ist.
  4. Prüfen Sie die tatsächlich benötigten Daten mit geeigneten Testdaten. Dokumentieren Sie keine vollständigen Tokens oder personenbezogenen Listen als Testnachweis.
  5. Falls die Anwendung RP-initiiertes Logout nutzt, testen Sie auch die Abmeldung und das vereinbarte Rücksprungziel. Die bloße Eingabe einer Post-Logout-URI richtet diese Funktion nicht in Ihrer Anwendung ein.
  6. Geben Sie die Anbindung erst nach erfolgreichem Test für den vorgesehenen Einsatz frei. Das Speichern der OIDC-Einstellungen ist kein gesonderter Veröffentlichungsschritt.

9. Fehler eingrenzen

Beobachtung Nächster Schritt
Fehler beim Laden Prüfen Sie Anmeldung und Verbindung. Laden Sie den Dialog erneut. Speichern Sie bei unklar oder unvollständig geladenen Daten nicht vorschnell.
Fehler beim Speichern Lesen Sie die vollständige Meldung und prüfen Sie die vereinbarten Angaben. Bei einer Verbindungsunterbrechung öffnen Sie die Konfiguration erneut und kontrollieren den gespeicherten Stand, bevor Sie die Änderung wiederholen.
Eine Redirect-Adresse fehlt nach dem Speichern Prüfen Sie, ob die Eingabe vor dem Speichern mit Enter als eigener Eintrag bestätigt war.
Der Medium-Aufruf erreicht die falsche Seite oder startet keine Anmeldung Prüfen Sie die OpenID-URL. Sie muss auf die Startseite des OIDC-Anmeldeablaufs Ihrer Anwendung zeigen, nicht versehentlich auf eine Callback- oder Discovery-Adresse.
Die Anmeldung scheitert beim Rücksprung Lassen Sie die verwendete Rücksprungadresse mit den gespeicherten Redirect-URIs vergleichen. Prüfen Sie die vollständige Adresse.
Die Anwendung meldet einen Client- oder Authentifizierungsfehler Lassen Sie Client-ID, das auf beiden Seiten vereinbarte Secret und Method vergleichen. Geben Sie das Secret nicht in die Fehlerbeschreibung ein.
Erwartete Daten fehlen Prüfen Sie die Scope-Auswahl gemeinsam mit der technischen Gegenstelle. Fordern Sie nicht pauschal alle Scopes an; auch die Verfügbarkeit der Angaben für das Testkonto ist zu klären.
Nach Abmeldung wird ein falsches Ziel geöffnet Prüfen Sie die Post-Logout-Redirect-URIs und ob die Anwendung die vereinbarte Abmeldung tatsächlich unterstützt und verwendet.
Die Client-ID fehlt auch nach dem Speichern oder der Fehler bleibt unklar Wenden Sie sich mit Mediennummer, Zeitpunkt, betroffener Aktion und bereinigter Fehlermeldung an die technische Betreuung. Teilen Sie keine Secrets, Tokens oder vollständigen Anmelde-URLs mit vertraulichen Parametern.

Die genannten Prüfungen sind mögliche Ursachen, keine garantierte Diagnose. Für Fehler der externen Anwendung benötigt deren technische Betreuung gegebenenfalls eigene, bereinigte Protokolle.

10. Bestehende Anbindung ändern oder entfernen

Öffnen Sie für Änderungen wieder die OIDC-Konfiguration desselben Mediums. Stimmen Sie insbesondere Änderungen an Secret, Rücksprungadressen, Methode und Scopes vorab ab und wiederholen Sie danach den Funktionstest.

Löschen wird angezeigt, wenn eine Client-ID vorhanden ist. Nach einer Sicherheitsabfrage entfernt diese Aktion den OIDC-Client; laut Dialog ist dies nicht rückgängig zu machen. Bestehende Zugriffe können dadurch ausfallen. Nutzen Sie Löschen nicht als allgemeine Fehlerbehebung und nicht zum bloßen Zurücknehmen ungespeicherter Eingaben.

Weitere Arbeitsschritte: Übersicht Medien und Pakete Marketplace für Medienproduzenten – Medien und Pakete.