SAML für Entwickler (eigene Anwendungen anbinden)

Bereich: Einrichtung externer Dienste · Status: aktiv Verfügbar für: Entwickler angebundener Anwendungen

In einem Satz

Technische Referenz, wie eine eigene Anwendung (Service Provider) den Cofys-SAML-Identitätsanbieter nutzt und welche Daten sie erhält.

Wofür brauche ich das?

• Ein eigenes Tool (z. B. Spielleitungs-App) soll Cofys-Login, Charaktere und Buchungen nutzen.

Wo finde ich es?

Panel → System → SSO-Anwendungen (App registrieren, IdP-Daten, Zertifikat).

So funktioniert es

1. IdP-Konfiguration im Service Provider

• Entity ID (Issuer): https://saml.cofys.de
• SSO-Endpunkt: https://<Adresse der Instanz>/auth/saml/<ID der App>/ (GET oder POST, SAMLRequest/RelayState)
• Öffentliches X.509-Zertifikat zur Prüfung der Signatur (im Panel angezeigt)

2. Benutzeridentifikation

• <Subject><NameID>: Format unspecified, Wert = unveränderliche NanoID des Benutzers. Als primären Schlüssel verwenden, nicht Benutzername oder E-Mail.
• Zusätzlich als eigenes Attribut: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier (PPID) = NanoID.

3. Standard-Attribute

Attribut	Inhalt
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	E-Mail (Scope basic)
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	Benutzername (Scope basic)
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	Vorname (aus dem Namen abgeleitet)
http://schemas.xmlsoap.org/claims/CommonName	Nachname (aus dem Namen abgeleitet)
http://schemas.xmlsoap.org/claims/Group	Gruppennamen (mehrere Werte)
eigene Schlüssel	Benutzerdefinierte Parameter der App (z. B. Quota)

4. Scopes

• basic – immer aktiv: email, username (HTML-Entities dekodiert, UTF-8).
• characters, bookings – je Datensatz ein Attributwert, der als URL-kodierter JSON-String übertragen wird. Im Service Provider über die Werte iterieren, jeweils URL-dekodieren und JSON parsen.

characters:

{
  "nanoId": "string",
  "name": "string",
  "profilePicture": "url_oder_null",
  "faction": { "nanoId": "string", "name": "string", "description": "string" }
}

faction nur mit Modul Fraktionen.

bookings (alle Buchungen des Benutzers):

{
  "nanoId": "string",
  "date": 1730000000,
  "paymentState": "paid|unpaid|pending|partially_paid|disputed|refunded",
  "character": { "nanoId": "string", "name": "string" },
  "faction": { "nanoId": "string", "name": "string" },
  "event": { "nanoId": "string", "name": "string", "timeStart": 0, "timeEnd": 0, "place": "string" },
  "ticketOptions": [ { "nanoId": "string", "name": "string" } ]
}

character/faction modulabhängig.

Einstellungen und Optionen

Siehe SSO-Anwendungen.

Was passiert automatisch?

Neue oder geänderte Scopes lösen beim nächsten Login eine Zustimmungsseite aus.

Grenzen und Besonderheiten

• Ein Attribut uid wird – anders als in der alten Anleitung beschrieben – nicht gesendet; stattdessen PPID und NameID nutzen.
• Neu gegenüber der alten Anleitung: Objekt event im Scope bookings; paymentState ist ein Text.

Hängt zusammen mit

• SSO-Anwendungen, Nextcloud, Freescout