API-Clients (OAuth / OpenID Connect)

Über API-Clients binden Sie eigene oder fremde Anwendungen an Netxp-Verein an. Ein API-Client ist die Registrierung einer Anwendung beim Netxp-IdentityServer: er legt fest, wie sich die Anwendung anmeldet (Grant Type), wohin sie nach der Anmeldung zurückkehren soll (Redirect-URI) und worauf sie zugreifen darf (Scopes).

Für wen diese Seite gedacht ist

Diese Seite richtet sich an Personen, die eine Anbindung technisch umsetzen — Entwickler, Dienstleister, IT-Verantwortliche des Vereins. Grundkenntnisse zu OAuth 2.0 und OpenID Connect sind Voraussetzung; die Begriffe werden hier nur im Kontext der Netxp-Verein-Oberfläche erklärt.

Zweck

• Fremdanwendungen (Website, App, Middleware, Skripte) an die Netxp-Verein-API anbinden
• Pro Anwendungszweck einen eigenen Client mit eigenem Secret und eigenem Rechteumfang betreiben
• Zugriffe gezielt und einzeln gewähren und wieder entziehen

Voraussetzungen

• Das Recht API-Clients (Lesen / Schreiben / Löschen) — es steuert Anzeige, Bearbeitung und Löschung der Clients und wird über die Benutzerrollen vergeben.
• Mindestens ein API-Benutzer im Verein — über dessen Detailansicht führt der Button „API-Clients" in diese Verwaltung.
• Die Funktion setzt Netxp-Verein Pro voraus.

API-Clients und API-Benutzer sind unabhängig voneinander

Ein API-Client gehört nicht zu einem bestimmten API-Benutzer. Die Client-Liste ist vereinsweit: Haben Sie fünf API-Benutzer, sehen Sie bei jedem von ihnen dieselbe Liste.

Auch das Löschen aller API-Benutzer löscht keinen API-Client. Umgekehrt gilt aber: ohne mindestens einen API-Benutzer kommen Sie nicht an die Client-Verwaltung heran.

Die Client-Übersicht

Die Übersicht listet alle API-Clients des Vereins mit Anzeigename, Client-ID, Secret-Status und Änderungsdatum auf.

Aktion	Vorgehen
Client anlegen	Unten auf „Neuer Client"
Client öffnen	Zeile markieren → „Anzeigen", oder Doppelklick
Client löschen	Zeilen ankreuzen → „Löschen"

Löschen ist endgültig

Gelöschte Clients werden aus der Datenbank entfernt und lassen sich nicht wiederherstellen — es gibt keinen Papierkorb. Alle Anwendungen, die den Client verwenden, können sich danach nicht mehr anmelden. Zur Sicherheit verlangt nach dem Klick auf „Löschen" ein Rückfrage-Popup die Eingabe des Sicherheitsworts und listet die betroffenen Clients nochmal auf.

Der API-Client im Detail

Grunddaten

Feld	Bedeutung
Anzeigename*	Name der Anwendung, z. B. Website Anmeldeformular.
Client-ID	Wird automatisch gebildet aus {VereinsID}_{Anzeigename}.
Typ	Vertraulich oder öffentlich — siehe Typ.
Zustimmung	Verhalten des Zustimmungsdialogs — siehe Zustimmung.

* Pflichtangabe

Anzeigename ist nach dem Speichern gesperrt

Die Client-ID kann nachträglich nicht verändert werden, sobald der Client einmal gespeichert wurde. Zudem darf dieselbe Client-ID nicht mehrfach existieren.

Da sich die Client-ID aus dem Anzeigenamen ableitet, ist auch dieser danach gesperrt. Denken Sie daher vorher über den endgültigen künftigen Namen nach — soll ein Client anders heißen, müssen Sie einen neuen anlegen und den alten löschen.

Typ

Option	Bedeutung	Wann verwenden?
Vertraulich (Server, mit Secret)	Die Anwendung kann ein Secret sicher aufbewahren und weist sich damit aus.	Serverdienste, Backend-Anwendungen, Middleware, Skripte auf einem von Ihnen kontrollierten Server. Standard bei Neuanlage.
Öffentlich (App/Browser, ohne Secret)	Die Anwendung kann kein Secret schützen — der Code ist beim Anwender einsehbar.	Single-Page-Apps im Browser, native Mobile-Apps, Desktop-Anwendungen beim Anwender.

Beim Umschalten auf öffentlich passt die Oberfläche sich automatisch an:

• Client Credentials wird deaktiviert und abgewählt — ein öffentlicher Client kann sich mangels Secret nicht selbst authentifizieren. Der Server weist das zusätzlich ab.
• PKCE erforderlich wird gesetzt und gesperrt — ohne Secret ist PKCE der einzige wirksame Schutz des Authorization-Code-Ablaufs.
• Der Bereich Secret wird gesperrt.

Bereits erzeugtes Secret bleibt erhalten

Stellen Sie einen vertraulichen Client auf öffentlich um, bleibt ein vorhandenes Secret zwar gespeichert, wird aber nicht mehr verwendet. Die Oberfläche weist darauf hin.

Zustimmung

Steuert, ob der angemeldete Nutzer der Anwendung den Zugriff ausdrücklich erlauben muss („Möchten Sie App X Zugriff auf Ihre Daten geben?").

Option	Bedeutung
Ausdrücklich – Nutzer muss zustimmen	Beim ersten Mal erscheint ein Zustimmungsdialog; die Entscheidung wird gemerkt. Der sichere Regelfall für Anwendungen Dritter.
Implizit – keine Zustimmung nötig	Es wird nie gefragt. Sinnvoll für eigene, vollständig vertrauenswürdige Anwendungen des Vereins.
Extern – außerhalb verwaltet	Die Zustimmung wird außerhalb des IdentityServers erteilt und dort nur vorausgesetzt. Nur verwenden, wenn Ihre Integration das ausdrücklich vorsieht.
Systematisch – bei jeder Anfrage	Es wird jedes Mal erneut gefragt, auch wenn zuvor zugestimmt wurde. Für besonders schutzbedürftige Zugriffe.

Ohne Anwender-Login keine Zustimmung

Bei Client Credentials handelt kein Mensch, sondern die Anwendung selbst — ein Zustimmungsdialog kommt dort gar nicht vor. Die Einstellung wirkt praktisch nur bei Abläufen mit Benutzeranmeldung (Authorization Code, Device Code).

Secret

Das Secret ist das Passwort bzw. der Sicherheitsschlüssel des Clients. Ein vertraulicher Client benötigt es zwingend.

1. Client zuerst speichern — vorher ist der Button gesperrt.
2. „Neues Secret erzeugen" klicken.
3. Das Secret wird einmalig im Klartext angezeigt.
4. Sofort kopieren und in der anbindenden Anwendung hinterlegen.

Das Secret wird nie wieder angezeigt

Nach dem Schließen der Ansicht ist das Secret nicht mehr einsehbar — es liegt am Server nur verschlüsselt vor. Die Oberfläche zeigt danach lediglich „Ein Secret ist gesetzt.".

Es gibt genau ein Secret pro Client. Erzeugen Sie ein neues, wird das bisherige ungültig; alle damit eingerichteten Zugriffe funktionieren nicht mehr, bis Sie das neue Secret überall eingetragen haben. Das lässt sich nicht rückgängig machen.

Vorgehen bei Kompromittierung

Besteht der Verdacht, dass ein Secret an Unberechtigte gelangt ist: Neues Secret erzeugen (das alte ist damit ungültig) und in der Anwendung austauschen. Da jeder Client sein eigenes Secret hat, betrifft das nur diese eine Integration — deswegen sollte pro Anwendungszweck einen eigenen Client geführen werden.

Flows und Endpunkte

Hier legen Sie fest, welche OAuth-Abläufe der Client nutzen darf. Je nach Auswahl werden gegebenfalls automatisch Endpunkte und Response Types gesetzt.

Grant Types

Grant Type	Bedeutung	Typischer Einsatz	Zieht automatisch nach sich
Authorization Code	Anmeldung im Browser mit Weiterleitung; der Code wird anschließend gegen ein Token getauscht. Der sichere Standardablauf mit Benutzeranmeldung.	Web-Anwendungen und Apps, die im Namen eines Nutzers handeln.	Endpunkte Authorization + Token, Response Type code, mindestens eine Redirect-URI
Client Credentials	Die Anwendung meldet sich mit Client-ID + Secret an — ohne Benutzer.	Server-zu-Server-Integrationen, nächtliche Abgleiche, Skripte. Voreinstellung bei Neuanlage.	Endpunkt Token
Refresh Token	Erlaubt, ein abgelaufenes Access-Token ohne erneute Anmeldung zu erneuern.	Langlaufende Anwendungen mit Benutzeranmeldung.	Scope offline_access (wird beim Speichern automatisch ergänzt)
Device Code	Anmeldung an Geräten ohne Tastatur/Browser: das Gerät zeigt einen Code, die Freigabe erfolgt am Smartphone oder PC.	Info-Displays, Terminals, Kiosk-Geräte.	Endpunkte Device Authorization + Token

Password und API Key — Altverfahren

Die Ankreuzfelder Password und API Key decken bestehende Anbindungen ab und sollten für neue Clients nicht verwendet werden:

• Password — die Anwendung nimmt Benutzername und Passwort direkt entgegen und reicht sie an den Server weiter. Das Verfahren gilt in OAuth 2.1 als abgekündigt, weil die Anwendung dabei das Klartext-Passwort des Nutzers sieht.
• API Key — ein Netxp-eigenes Verfahren mit dem API-Key des API-Benutzers. Es ist kein Standard-OAuth-Grant und nur für bestehende Netxp-Verein-Anbindungen gedacht.

Beide setzen den Endpunkt Token voraus. Verwenden Sie für neue Anbindungen Client Credentials (ohne Benutzer) oder Authorization Code (mit Benutzer).

Mindestens ein Grant Type ist Pflicht

Ohne angekreuzten Grant Type lässt sich der Client nicht speichern. Kreuzen Sie nur an, was die Anwendung tatsächlich benötigt.

Endpunkte

Die Endpunkte bestimmen, welche Adressen des IdentityServers der Client überhaupt ansprechen darf.

Endpunkt	Wofür
Authorization	Startpunkt der Benutzeranmeldung im Browser. Nur für Authorization Code nötig.
Token	Ausgabe der Access-/Refresh-Tokens. Praktisch immer erforderlich.
Logout	Abmeldung samt Beenden der Sitzung beim IdentityServer. Voraussetzung für Post-Logout-URIs.
Revocation	Der Client kann ein Token aktiv für ungültig erklären — z. B. beim Abmelden des Nutzers. Empfohlen.
Introspection	Der Client kann prüfen lassen, ob ein Token noch gültig ist und was darin steht. Für Ressourcen-Server, die fremde Tokens annehmen.
Device Authorization	Einstieg des Device-Code-Ablaufs. Nur bei Device Code nötig.

Automatisch gesetzte Haken nicht wieder entfernen

Setzt das System in der Oberfläche einen Endpunkt beim Ankreuzen eines Grant Types selbst, ist er für diesen Ablauf zwingend erforderlich. Entfernen Sie ihn wieder, schlägt die Anmeldung der Anwendung fehl.

Response Types

Response Type	Bedeutung
code	Der Authorization-Endpunkt liefert einen Autorisierungscode zurück, der gegen ein Token getauscht wird. Wird bei Authorization Code automatisch gesetzt.
id_token	Zusätzlich wird ein ID-Token mit Angaben zum angemeldeten Nutzer ausgegeben (OpenID Connect). Sinnvoll, wenn Ihre Anwendung wissen muss, wer angemeldet ist. Erfordert den Scope openid.

Anforderungen

Anforderung	Bedeutung
PKCE erforderlich	Proof Key for Code Exchange: Der Client sichert den Authorization-Code zusätzlich kryptografisch ab, sodass ein abgefangener Code allein nutzlos ist. Bei öffentlichen Clients zwingend gesetzt und nicht abwählbar. Bei vertraulichen Clients optional — aber empfohlen, sobald Authorization Code verwendet wird.

„Zusätzlich hinterlegt und unverändert übernommen"

Erscheint dieser Hinweis unter den Ankreuzfeldern, enthält der Client Einstellungen, die diese Oberfläche nicht darstellt — etwa aus einer älteren Konfiguration. Diese Werte bleiben beim Speichern unverändert erhalten und gehen nicht verloren.

URIs

Beide Listen werden mit dem Eingabefeld und „Hinzufügen" gepflegt; zum Entfernen markieren Sie einen Eintrag und klicken „Entfernen".

Liste	Wofür
Redirect-URIs	Adressen, an die der IdentityServer den Browser nach erfolgreicher Anmeldung zurückschickt. Nur relevant beim Ablauf Authorization Code — ohne diesen Grant Type ist der Bereich gesperrt.
Post-Logout-URIs	Adressen, an die nach der Abmeldung zurückgeleitet werden darf. Sinnvoll in Verbindung mit dem Endpunkt Logout.

Die Anwendung muss die verwendete Adresse bei jeder Anfrage mitschicken; der IdentityServer akzeptiert ausschließlich exakt hier eingetragene Adressen. Das verhindert, dass jemand die Anmeldung auf eine fremde Seite umleitet.

Regeln für beide Listen:

Regel	Grund
Vollständige, absolute Adresse — z. B. https://app.example.de/callback	Teiladressen werden vom IdentityServer stillschweigend verworfen.
https:// ist Pflicht — Ausnahme: localhost für Testzwecke	Über http wäre der Rückweg mitlesbar.
Keine Platzhalter (*)	Es gibt keine Musterauflösung; jede Adresse wird einzeln eingetragen.
Kein Fragment (#…)	Von OpenID Connect nicht zugelassen.
Kein Komma	Das Komma trennt die gespeicherten Adressen voneinander.

Authorization Code ohne Redirect-URI lässt sich nicht speichern

Ist Authorization Code angekreuzt, muss mindestens eine Redirect-URI eingetragen sein — sonst bricht das Speichern mit einem Hinweis ab.

Test- und Produktivadresse gemeinsam eintragen

Es können mehrere Adressen hinterlegt werden, z. B. https://app.example.de/callback und https://localhost:5001/callback für die Entwicklung. Entfernen Sie die Testadressen, sobald die Anbindung produktiv ist.

Scopes

Die Scopes bilden die Berechtigungen des Clients ab: sie begrenzen, welche Daten und Funktionen ein mit diesem Client ausgestelltes Token überhaupt erreichen kann.

Über „Hinzufügen" öffnet sich eine durchsuchbare Auswahlliste aller zuweisbaren Scopes (Mehrfachauswahl über die Ankreuzspalte). Bereits zugewiesene Scopes erscheinen dort nicht mehr. Zum Entfernen markieren Sie die betreffenden Zeilen im Raster (Mehrfachauswahl möglich) und klicken „Entfernen" — die Rückfrage nennt die betroffenen Scopes namentlich.

Die Spalte „Standard"

Der Hinweistext über dem Raster lautet:

Zugewiesene Scopes. In der Spalte „Standard" markierte Scopes erhält der Client auch dann, wenn er sie nicht ausdrücklich anfordert.

Damit gibt es zwei Stufen:

Zustand	Wirkung
Zugewiesen, Standard nicht markiert	Der Client darf diesen Scope anfordern. Tut er es bei der Anmeldung nicht, ist er im Token nicht enthalten.
Zugewiesen und Standard markiert	Der Scope ist immer im Token enthalten, auch ohne ausdrückliche Anforderung.
Nicht zugewiesen	Der Scope wird abgelehnt, selbst wenn die Anwendung ihn anfordert.

Wann und wie Standard setzen

Wenn Standard aktiviert ist, wird dieser Scope immer automatisch mitgesendet, ohne dass er explizit angefordert werden muss. Zur Wahrung der Datensicherheit sollte diese Option nur sparsam eingesetzt werden.

Welche Scopes gibt es?

1. Standard-Scopes von OpenID Connect — immer verfügbar:

Scope	Berechtigt zu
openid	Schaltet OpenID Connect ein: der Client erhält ein ID-Token mit der Identität des angemeldeten Nutzers. Voraussetzung für den Response Type id_token.
profile	Angaben zur Person des angemeldeten Nutzers, z. B. Name.
email	Die E-Mail-Adresse des angemeldeten Nutzers.
offline_access	Erlaubt die Ausgabe eines Refresh Tokens, also den Zugriff, während der Nutzer nicht aktiv angemeldet ist.

offline_access wird automatisch ergänzt

Ist der Grant Type Refresh Token angekreuzt, fügt Netxp-Verein beim Speichern offline_access selbstständig hinzu — ohne diesen Scope gibt der IdentityServer kein Refresh Token aus.

2. Netxp-Verein-Fachscopes — sie bilden die Rechte-Bereiche von Netxp-Verein ab und stammen aus folgenden Ressourcen-Bereichen:

Bereich	Umfang	Scope
MitgliederOnline	Funktionen des Mitgliederportals	mo_*
VereinOnline	Funktionen der Web-Vereinsverwaltung	vo_*
Verein-API	Die allgemeine Netxp-Verein-API	va_*

Welche Scopes davon konkret zur Auswahl stehen, hängt von den freigeschalteten Modulen und der Konfiguration Ihres Vereins ab — die Auswahlliste zeigt jeweils den für Sie gültigen Stand. Jeder Eintrag trägt einen sprechenden Anzeigenamen, der den Rechtebereich benennt.

Nur zuweisen, was gebraucht wird

Prüfen Sie vor der Zuweisung mit dem Anbieter der Anwendung, welche Scopes sie tatsächlich anfordert. Es sollten Scopes nur dann gesetzt werden, wenn diese wirklich benötigt werden.

„Standard-Scopes hinterlegt, die ihm nicht zugewiesen sind"

Diese Meldung beim Öffnen stammt aus Altdaten: es sind Standard-Scopes hinterlegt, die dem Client gar nicht zugewiesen sind. Beim nächsten Speichern werden sie entfernt — Sie müssen nichts weiter tun. Prüfen Sie danach, ob alle benötigten Scopes noch in der Liste stehen.

Speichern und Wirksamwerden

Änderungen wirken nicht sofort

Alle Änderungen an einem API-Client werden zeitverzögert übernommen — Anlegen, Bearbeiten, ein neues Secret ebenso wie das Löschen. Es dauert oft einige Minuten, bis der Client mit den gespeicherten Einstellungen arbeitet.

Schlägt ein Test unmittelbar nach dem Speichern fehl, warten Sie kurz und wiederholen ihn. Umgekehrt gilt: Ein gelöschter oder eingeschränkter Zugriff kann in dieser Zeitspanne noch funktionieren.

Beim Verlassen der Ansicht mit ungespeicherten Änderungen fragt Netxp-Verein nach, ob diese verworfen werden sollen.

Typische Einrichtungen

Server-zu-Server-Anbindung (häufigster Fall)

Eine Middleware ruft nachts Mitgliederdaten ab — ohne Benutzeranmeldung.

• Typ: Vertraulich
• Zustimmung: Implizit (es ist kein Nutzer beteiligt)
• Grant Type: Client Credentials
• Endpunkte: Token (automatisch), zusätzlich Revocation
• URIs: keine
• Scopes: die benötigten Fachscopes
• Secret: nach dem ersten Speichern erzeugen

Web-Anwendung mit Benutzeranmeldung

Nutzer melden sich über Netxp-Verein an einer Vereinswebsite an.

• Typ: Vertraulich
• Zustimmung: Ausdrücklich
• Grant Types: Authorization Code, Refresh Token
• Endpunkte: Authorization + Token (automatisch), Logout, Revocation
• Response Types: code (automatisch), id_token
• Anforderungen: PKCE erforderlich
• Redirect-URI: https://…/signin-oidc
• Post-Logout-URI: https://…/signout-callback-oidc
• Scopes: openid, profile, email (+ Fachscopes); offline_access kommt automatisch dazu

Mobile App oder Single-Page-App

• Typ: Öffentlich (Client Credentials und PKCE-Abwahl sind gesperrt)
• Zustimmung: Ausdrücklich
• Grant Types: Authorization Code, Refresh Token
• Redirect-URI: die Rückkehradresse der App
• Secret: entfällt

Häufige Fehler

„Diese Client-ID ist bereits vergeben."

Die Client-ID wird aus {VereinsID}_{Anzeigename} gebildet und darf nicht mehrfach existieren. Wählen Sie einen anderen Anzeigenamen — z. B. mit Zusatz _v2 oder dem Einsatzzweck.

Anmeldung schlägt mit „invalid redirect_uri" fehl

Die von der Anwendung gemeldete Adresse muss exakt einem Eintrag entsprechen — inklusive Protokoll, Groß-/Kleinschreibung des Pfades und abschließendem /. Vergleichen Sie beides zeichengenau.

Kein Refresh Token trotz angekreuztem Grant Type

Prüfen Sie, ob offline_access unter den Scopes steht (wird beim Speichern automatisch ergänzt) und ob die Anwendung diesen Scope bei der Anmeldung tatsächlich anfordert — oder markieren Sie ihn als Standard.

Anmeldung schlägt direkt nach dem Speichern fehl

Gespeicherte Änderungen werden erst nach einigen Minuten aktiv (siehe Speichern und Wirksamwerden). Kurz warten und erneut testen.

Secret verloren

Das Secret lässt sich nicht erneut anzeigen. Erzeugen Sie ein neues und tragen Sie es in der Anwendung nach — das alte wird dabei ungültig.

Button „API-Clients" fehlt

Mögliche Ursachen: fehlendes Recht API-Clients (mindestens Lesen, siehe Benutzerrollen), oder die Funktion ist im Vertrag Ihres Vereins nicht freigeschaltet (siehe Vertrag verwalten).

„Die Client-Verwaltung ist nur für Vereinsbenutzer verfügbar."

Die Verwaltung setzt einen Benutzer mit Vereinszuordnung voraus. Melden Sie sich mit einem regulären Benutzer Ihres Vereins an.

Tipps & Hinweise

Ein Client pro Anwendungszweck

Legen Sie nicht einen Sammelclient für alles an, sondern je einen pro Anwendung — Website, App, Middleware. So lassen sich Rechte gezielt zuschneiden und eine einzelne Integration abschalten, ohne die anderen zu stören.

Anzeigenamen sprechend wählen

Der Anzeigename ist später nicht mehr änderbar und bestimmt die Client-ID. Bewährt hat sich ein Muster wie Website Anmeldung Produktiv oder Middleware Beitragsabgleich.

Zugriffe regelmäßig prüfen

Gehen Sie die Client-Liste regelmäßig, mindestens einmal jährlich durch und löschen Sie Clients, deren Anwendung nicht mehr betrieben wird. Vor dem Löschen unbedingt prüfen, ob dieser noch verwendet wird: gelöschte Clients können nicht wiederhergestellt werden.

Verwandte Themen

• API-Benutzer — Voraussetzung und Einstieg in diese Verwaltung
• Benutzerliste — Einstieg zum Anlegen von Benutzern
• Benutzerrollen — Rechtevergabe, u. a. für das Recht API-Clients
• Netxp-Verein Pro — Voraussetzung für die Client-Verwaltung
• Zwei-Faktor (2FA) — Absicherung interaktiver Benutzerzugänge
• Ereignisprotokoll — Nachvollziehen von Änderungen