OneSpan Developer: Endpunkt für die Ereignisvalidierung

OneSpan Team,

Die Sicherung von nicht-monetären Ereignissen ist entscheidend für die geschäftliche Integrität in jeder Organisation. Über den Endpunkt Events/Validate empfängt OneSpan Intelligent Adaptive Authentication (IAA ) nicht-monetäre Ereignisse, die in einer Benutzeranwendung ausgelöst werden. Risk Analytics (RA) bewertet dann die Ethnizität dieser Ereignisse und fordert den Endbenutzer je nach dem mit einem Ereignis verbundenen Risiko auf, die geeignete Authentifizierungsmethode anzugeben. In diesem Blog veranschaulichen wir die Validierung von nicht-monetären Ereignissen mithilfe der Sandbox Interactive API und zeigen die möglichen RA-Antworten auf ein Ereignis

Bevor wir beginnen

Bevor Sie den Endpunkt zur Ereignisvalidierung erkunden können, müssen Sie zunächst Mitglied der OneSpan-Community sein und sich für ein kostenloses Intelligent Adaptive Authentication-Sandbox-Konto anmelden. Hier finden Sie eine Schritt-für-Schritt-Anleitung, wie Sie dabei vorgehen.

Sie sollten auch sicher sein, dass mindestens ein registrierter Benutzer vorhanden ist, bevor Sie diesen Aufruf versuchen. Wie Sie einen Benutzer registrieren können, erfahren Sie in diesem ausführlichen Blog zur Benutzerregistrierung.

Endpunkt-URL

Die Anfrage-URL für diesen API-Aufruf wird dem unten stehenden Beispiel ähneln:

https://{Ihre_Mieter_ID}.sdb.tid.onespan.cloud/v1/users/{userID@domain}/events/validate

Sie müssen diese URL während des Tutorials nicht angeben. Sie dient nur dazu, die Struktur der URL zu zeigen. Die URL wird in der Interaktiven API beim Aufruf des Webdienstes automatisch zugewiesen

Probieren Sie es aus

Um mit der Ereignisvalidierungs-API zu experimentieren, navigieren Sie in Ihrem OneSpan-Community-Konto zum Dokument IAA Sandbox Interactive API. Erweitern Sie im Open API Swagger-Editor die Ressource "Ereignisse". Sie finden dann einen Eintrag für die Methode Events /Validate HTTP Post, wie in der folgenden Abbildung dargestellt

OneSpan-BlogImage[EventValidation-Endpunkt]1

URL-Pfad-Parameter:

Für den Zweck des API-Aufrufs "Events/Validate" gibt es einen erforderlichen Pfadparameter für die eindeutige Benutzerkennung. Sie wird als userID@domain formatiert. Ein Beispiel für die UserID ist "iaa_user". Es ist die UserID, die auf dem vertrauenswürdigen Gerät aktiviert wurde. Der Teil des Parameters, der auf das "@"-Zeichen folgt, ist die Benutzerdomäne. Dieser Eintrag sollte durch die unten gezeigte Zeichenfolge "Sandbox-Benutzer" ersetzt werden, die Sie im Abschnitt "Sandbox-Details" unter der Registerkarte "Intelligente adaptive Authentifizierung" auf Ihrer Sandbox-Homepage finden.

OneSpan-BlogImage[EventValidation-Endpunkt]2

Ereignisse Validierungsanfrage Körper

Hinweis: Die API zur Ereignisvalidierung ist spezifisch für die OneSpan Intelligent Adaptive Authentication-Lösung. Sein Zweck ist es, Risk Analytics über ein Ereignis zu informieren und die notwendigen Daten zu übermitteln, um eine eindeutige Entscheidung bezüglich des Ereignisses zu treffen. Aus diesem Grund ist es nicht erforderlich, im Request Body des RESTful-Aufrufs einen Objekttyp auszuwählen, wie es bei API-Aufrufen in früheren Blogs der Fall war

Der Anfragerumpf sieht wie das folgende Beispiel für die erforderlichen Felder des Endpunkts "Events/Validate" aus.

{ "eventType": "LoginSuccess", "relationshipRef": "iaa_enduser", "sessionID": "4ed23ea44f23", "cddc": { "browserCDDC": { "fingerprintRaw": "{browser:{\"userAgent\":Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36},support:{\"ajax\":true,\"boxModel\":undefined,\"changeBubbles\":undefined,\"checkClone\":true,\"checkOn\":true,\"cors\":true,\"cssFloat\":undefined,\"hrefNormalized\":undefined,\"htmlSerialize\":undefined,\"leadingWhitespace\":undefined,\"noCloneChecked\":true,\"noCloneEvent\":undefined,\"opacity\":undefined,\"optDisabled\":undefined,\"style\":undefined,\"submitBubbles\":undefined,\"tbody\":undefined},computer:{\"screenWidth\":2560,\"screenHeight\":1440,\"OS\":\"Microsoft Windows\",\"platform\":\"Win32\"},additional:{}}", "fingerprintHash": "e96dadc9651f5fe8f071110eb174fe8e7a17a9d7a96b3b1980c13e5b4af3a4d7" } }, "clientIP": "192.168.0.1" }

Nutzlast anfordern

Sie enthält die in der Tabelle gezeigten obligatorischen JSON-Objekte:

JSON Erforderliche Datenfelder Beschreibung Feld Datentyp
eventType * Der Typ des nicht-monetären Ereignisses, das validiert werden soll.Typ: Zeichenkette Beispiel: "LoginSuccess", "NewBeneficiaryAttempt"
beziehungRef* Die Beziehungsreferenz der Benutzer-ID.

Typ: string
minLength: 1
maxLength: 150
Beispiel: iaa_user

sessionID* Kennung der Anwendungssitzung, formatiert als hexadezimale Zeichenfolge; gemeinsam für alle Ereignisse, die sich auf dieselbe Sitzung beziehen. Typ: String
Muster: ^[0-9a-fA-F]+$
minLength: 2
maxLength: 100
Beispiel: 4ed23ea44f23
cddc* Client Device Data Collector-Metadaten. Die beiden Felder browserCDDC und mobileCDDC schließen sich gegenseitig aus und sind gemeinsam erschöpfend. Typ: String
Beispiel: "browserCDDC" oder "mobileCDDC"
clientIP IP-Adresse, von der das Ereignis ausgeht, formatiert in Punkt-Dezimal-Schreibweise. Dieses Feld wird dringend empfohlen, wenn das Ereignis aus einer Webbanking-Anwendung stammt. Typ: String
Beispiel: "192.168.0.1"

Aufrufen des Endpunkts

Jetzt sind wir bereit, einen RESTful-Aufruf an den Endpunkt "Events/Validate" unter Verwendung der interaktiven IAA-Sandbox-API durchzuführen. Um den Aufruf durchzuführen, klicken Sie auf die Schaltfläche "Try it out", die im Screenshot unten gezeigt wird und sich rechts neben dem Abschnitt zur HTTP-POST-Methode befindet. Nach der Anfrage erhalten Sie den Antwortkörper in einem JSON-Format zurück. Sie ähnelt der Antwort-Payload, die im folgenden Abschnitt beschrieben wird.

OneSpan-BlogImage[EventValidation-Endpunkt]3

Antwort-Nutzlast

Nachfolgend sehen Sie ein Beispiel für den zurückgegebenen Antwortkörper mit einem 200-Antwortcode, der eine erfolgreiche Anfrage anzeigt.

{ "requestID": "413b2c39-2d67-4293-9adb-25601731b062", "riskResponseCode": 0, "sessionStatus": "accepted", "requestMessage": "0000F8B81D" }

Beschreibung der Felder des Antwortkörpers

Die "requestID" ist das erste Feld in der Antwort. Es ist eine Zeichenkette mit 36 Zeichen, die verwendet wird, um einen Verweis auf den vorhergehenden API-Aufruf zu behalten. Diese ID kann für die Fehlersuche und Referenzierung nützlich sein.

Das Feld "riskResponseCode" ist der Antwortcode von Risk Analytics. Der Wert "0" in der obigen Antwort zeigt an, dass die Anfrage akzeptiert wurde und der Benutzer erfolgreich authentifiziert wurde, ohne dass zusätzliche Maßnahmen erforderlich waren. Der Reaktionstyp auf die verschiedenen Aktivitäten konnte von Risk Analytics erkannt werden.

Nachfolgend finden Sie eine Liste anderer möglicher Werte, die von Risk Analytics zurückgegeben werden können. Außerdem können zusätzliche Werte über den Risk Analytics Presentation Service konfiguriert werden.

Risikoanalyse Verhalten Risiko-Reaktions-Code (Ganzzahl)
Akzeptieren 0
Abnehmen 1
Herausforderung 2
HerausforderungSMS 3
ChallengeDevice2FA 5
HerausforderungEmail 8
HerausforderungCronto 11
ChallengeNoPIN 21
HerausforderungPIN 22
HerausforderungFingerabdruck 23
HerausforderungGesicht 24

Das Feld "sessionStatus" in der JSON-Antwort stellt den aktuellen Status der Sitzung dar, nachdem die Anfrage gesendet wurde. In der folgenden Tabelle sind die möglichen Statuswerte aufgeführt:

Session-Status Status Beschreibung
unbekannt Der Status ist nicht bekannt und die Antwort wird extern gehandhabt
anhängig Warten auf eine Aktion des Endbenutzers
akzeptiert Erfolgreich abgeschlossen
abgelehnt Vom Endbenutzer abgelehnt
timeout Zeitüberschreitung, nachdem innerhalb des Zeitrahmens keine Antwort empfangen wurde
gescheitert Die OTP-Validierung schlägt fehl

Das Feld "requestMessage" ist vom Typ String. Es wird verwendet, um einen Orchestrierungsbefehl an das vertrauenswürdige Endbenutzergerät zu übertragen.

Heute haben wir behandelt, wie man ein nicht-monetäres Ereignis über die OneSpan Interactive API erstellt. Im nächsten Blog zeigen wir, wie Sie eine Risk Analytics-Regel für nicht-monetäre Ereignisse erstellen. Wenn Sie in der Zwischenzeit Fragen haben, wenden Sie sich bitte an die OneSpan Community Portal Foren.

OneSpan Sign-Entwickler-Community

OneSpan Sign-Entwickler-Community

Treten Sie der OneSpan Sign Developer Community bei! Foren, Blogs, Dokumentationen, SDK-Downloads und mehr.

Tritt heute bei

The OneSpan Team is dedicated to delivering the best content to help you secure tomorrow's potential. From blogs to white papers, ebooks, webinars, and more, our content will help you make informed decisions related to cybersecurity and digital agreements.

Popup default