Die meisten API-Methoden liefern Ergebnisse im JSON-Format (application/json) zurück. Des Weiteren wird die Rückgabe von Ergebnissen in den Formaten CSV und PDF unterstützt, soweit das Ergebnis der entsprechenden API-Methode als exportierbar deklariert ist (über das Flag AllowExport). Grundsätzlich kann eine API-Methode Ergebnisse in beliebigen Formaten zurückgeben, die mit HTTP kompatibel sind.
Um Ergebnisse im CSV-Format zu erhalten
Um Ergebnisse im PDF-Format zu erhalten
Die Authentifizierung von Benutzern am API Server erfolgt pro API-Projekt.
Die Ausführung einer API-Methode erfordert die vorherige Authentifizierung an einem API-Projekt. Ist die API-Methode als AllowUnauthenticated markiert (Beispiele finden Sie im SDK), ist keine Authentifizierung nötig.
Die Authentifizierung erfolgt in zwei Schritten:
-
Erforderliche primäre Authentifizierung: Standard-Authentifizierung über ein Authentifizierungsmodul
-
Optionale sekundäre Authentifizierung: Multifaktor-Authentifizierung (über OneLogin)
Weitere Informationen zur Konfiguration der Authentifizierung finden Sie im One Identity Manager Konfigurationshandbuch für Webanwendungen.
Detaillierte Informationen zum Thema
Sie können festlegen, wie sich Benutzer an Ihrer API authentifizieren. Sie konfigurieren die Authentifizierung am API-Projekt.
Um die Authentifizierung zu konfigurieren
-
Bearbeiten Sie Ihr API-Projekt.
-
Erstellen Sie die Klasse SessionAuthDbConfig und geben Sie dabei folgende Eigenschaften an:
-
Product: Legen Sie die Anwendung fest, deren Authentifizierungsmodule Sie verwenden möchten (beispielsweise Portal oder Manager).
-
SsoAuthentifiers: Legen Sie die Single-Sign-on-Authentifizierungsmodule fest, die verwendet werden sollen.
-
ExcludedAuthentifiers: Legen Sie Authentifizierungsmodule fest, die nicht verwendet werden sollen.
Die primäre Authentifizierung am API-Projekt wird mithilfe der API-Methode imx/login/<Name des API-Projektes> ermöglicht.
Senden Sie dazu eine Anfrage mit der HTTP-Methode POST mit folgendem Inhalt:
{ "Module": "RoleBasedPerson", "User": "<Benutzername>", "Password": "<Passwort>" }
TIPP: Beispiele dazu finden Sie im SDK.
Sicherheitsmechanismen
Der API Server verwendet einen Sicherheitsmechanismus, um Cross-Site-Request-Forgery-Angriffe (CSRF) zu unterbinden. Dafür wird bei der Anmeldung ein zufällig generiertes Token in einem Cookie (XSRF-TOKEN) an den Client gesendet. Der Client muss danach in jeder Anfrage an den Server den Wert dieses Tokens in einem HTTP-Header (X-XSRF-TOKEN) übermitteln. Fehlt dieser Header, wird die Anfrage mit dem Fehlercode 400 beendet.
HINWEIS: Wenn eine API-Anfrage mit einem Fehler und Hinweis auf einen falschen CSRF-Schutz-Cookie abgebrochen wird, prüfen Sie, ob Ihr Browser die vom Browser gesendeten Cookies akzeptiert.
TIPP: Sie können den Namen und den Pfad des Cookies und den Namen des HTTP-Headers über das Administrationsportal anpassen. Verwenden Sie dazu die Konfigurationsschlüssel Name des Cookies, der das vom Server ausgestellte CSRF-Schutz-Token enthält (XsrfProtectionCookieName) und Pfad für den CSRF-Schutz-Cookie (XsrfProtectionCookiePath).
Sie können zudem den CSRF-Schutz im Administrationsportal deaktivieren (Konfigurationsschlüssel CSRF-Schutz-Token global deaktivieren (XsrfProtectionDisabled)). One Identity empfiehlt jedoch, dies nicht zu tun.
Wie Sie Konfigurationsschlüssel bearbeiten, erfahren Sie im One Identity Manager Konfigurationshandbuch für Webanwendungen.
