SecSign ID Server API

Erfahren Sie, warum unsere Zwei-Faktor Authentifizierung die Beste ist und Sie die Sicherheit Ihres Unternehmens upgraden sollten. Für Entwickler haben wirhier Informationen zusammengetragen.

Erfahren Sie mehr über Inhouse-Installationen und Ihre individuelle Firmen-App mit Ihrem Corporate Design.

Downloaden Sie das Plugin kostenlos in der Cloud für bequemen und sicheren Schutz.

Dokumentation der Schnittstelle zum SecSignID Identity Server für eine Zwei-Faktor Authentifizierung

WAS IST ZWEI-FAKTOR AUTHENTIFIZIERUNG?

Inhaltsverzeichnis

    Fragen?Kontaktieren Sie uns, wenn Sie Hilfe beim Setup des SecSign ID Plugins brauchen oder Ihnen ein Plugin für eine andere Programmierumgebung fehlt.

    CONTACT US

    1. SecSign ID API Server

    SecSign schützt Ihre Benutzerkonten vor Phishing-, Brute-Force und Hacker-Angriffen sowie vor dem Diebstahl oder Mitschneiden Ihrer Authentifizierungs-Credentials. Die SecSign ID Zwei-Faktor-Authentifizierung (2FA) fügt eine zusätzliche Sicherheitsschicht hinzu, indem es das mobile Gerät des Nutzers als zusätzlichen physischen Token mit in die Authentifizierung einbindet.

    Die SecSign ID Sitzungsauthentifizierung beruht auf 2048-Bit-RSA-Schlüsselpaaren. Die SecSign ID App enthält den privaten Schlüssel des Nutzers (verschlüsselt mit einer PIN), und der SecSign ID Server kennt den öffentlichen Schlüssel des Nutzers.

    Während der Sitzungsauthentifizierung für eine Anmeldung überprüft der SecSign ID Server den Besitz des privaten Schlüssels und die Kenntnis der PIN. Der SecSign ID Server wertet daraufhin die Authentifizierungsanfrage aus und informiert den anfragenden Dienst über die SecSignID API, ob Zugriff gewährt werden darf.

    Der SecSignID Server kann neben der öffentlichen Cloud Lösung auch als Inhouse Lösung umgesetzt werden. Die Kontrolle über Ihre Systeme und Daten, die über Internet oder Intranet laufen, bleibt ganz in Ihren Händen. Die Inhouse-Lösungen werden entweder auf Ihren Servern installiert, oder Sie wählen eine Inhouse-Konfiguration über eine hybride Cloud.

    2. Ablauf der Authentifizierung

    server api authentication

    • Der Nutzer gibt die SecSign ID über den Internetdienst ein, welcher eine Authentifizierungsanfrage für die eingegebene SecSign ID an den SecSign ID Server sendet.
    • Der ID Server sendet die Push Notification an das Mobilgerät des Nutzer
    • Der ID Server sendet ein Zugangssymbol an den Internetdienst
    • Der Internetdienst zeigt das erforderliche Zugangssymbol an
    • Der Nutzer wählt die SecSign ID auf dem Smartphone aus und gibt eine PIN ein. Die mobile App bestätigt, dass der Nutzer auch der Besitzer der SecSign ID ist
    • Der ID Server sendet das Zugangssymbol an die mobile App
    • Der Nutzer bestätigt das richtige Zugangssymbol und die mobile App sendet dieses an den ID Server
    • Der Internetdienst überprüft den Status der Authentifizierungssitzung
    • Der ID Server bestätigt die Zugangserlaubnis
    • Der Webdienst gewährt dem Nutzer den Zugriff

    3. Endpunkte

    Endpunkte der SecSignID API sind folgende URLs:

    Die Schnittstelle erwartet HTTP-POST Anfragen und URL-kodierte Parameterlisten als Antwort.Die Antwort des Servers liegt ebenfalls im URL-kodierten Format vor.

    Das URL-kodierte Format ist in einigen Sprachen wie Perl und C einfacher zu parsen. In Zukunft wird es aber so sein, dass über die Request-Header das Format mitgegeben wird und dann JSON auch unterstützt wird, so dass man JSON zum Server hinschicken kann und JSON zurückbekommt.

    Beim öffentlichen ID-Server wird lediglich diese Art der Kommunikation genutzt. Der vor dem öffentlichen Server vorgeschaltete SecSign Routing Server verhindert andere Anfragen. Bei einer Inhouse-Installation sind jedoch auch andere Möglichkeiten der Kommunikation wie z.B. Webservice und SOAP möglich.

    Im ID-Server befindet sich eine Web Application Firewall, die kontrolliert, ob die Anzahl der erforderlichen Parameter übereinstimmt. Außerdem wird das Format der Parameter-Werte überprüft. Wenn die API zum Beispiel entweder true oder false erwartet, aber ein anderer Wert gesendet wird, dann wird ein Bad-Request-Fehler zurück gegeben (siehe 7. Fehlermeldungen).

    4. Authentifizierung starten

    Um einen Nutzer authentifizieren zu können, muss zuerst eine Authentifizierungs-Sitzung gestartet werden. Wird vom Client die Authentifizierungsanfrage gesendet, erhält der Client den Accesspass zurück und das Smartphone des Nutzers zeigt an, dass ein neuer Login bestätigt werden kann

    Anfrage

    Der Client sendet eine POST Anfrage zum SecSignID API Server um eine AuthSession anzufragen. Die zu übertragenden Parameter sind URL codiert, d.h. alle Schlüssel-Wertpaare sind durch ein „=“ getrennt und werden mit „&“ konkateniert: ParameterName1=Wert1&ParameterName2=Wert2…

    “&”:ParameterName1=Value&ParameterName2=Value2…

    PARAMETER NAME STATUS VALUE
    request erforderlich ReqRequestAuthSession
    Teilt dem Server mit, dass es sich hierbei um eine Anfrage zu einer Authentifizierungs-Sitzung handelt.
    secsignid erforderlich Die SecSignID des Users
    servicename erforderlich Der Name des Projektes bzw. der Webseite (dieser Wert wird dem Nutzer auf dem Smartphone angezeigt)
    serviceaddress erforderlich Die IP-Adresse oder URL des Projektes bzw der Webseite (dieser Wert wird dem Nutzer auf dem Smartphone angezeigt)
    pluginname erforderlich Wird verwendet, wenn ein Plugin, wie zum Beispiel das WordPress oder Joomla Plugin die API nutzt.
    apimethod erforderlich Dieser Parameter beschreibt die Umgebung in der die Authentifizierung stattfindet:, bzw welche API verwendet wird
    SecSignIDApi_PHP, SecSignIDApi_C, SecSignIDApi_Ruby, SecSignIDApi_Python, SecSignIDApi_Perl
    showaccesspass erforderlich true or false
    Die SecSign ID kann mit und ohne AccessPass genutzt werden. Die Variante ohne AccessPass wird allerdings nur empfohlen, wenn es sich um eine 2-step Authentifizierung handelt.

    Die Antwort der Anfrage wird in jedem Fall den Parameter accesspassicondata senden, welcher den Accesspass beinhaltet. Ist der Wert „false“, zeigt die App des Nutzers aber keinen Accesspass an, accesspassicondata kann in diesem Fall vom Client ignoriert werden.

    Standartwert: true (der Accesspass wird angezeigt)
    Standard value: true (the AccessPass is displayed).

    Beispiel für einen Request zur Authentifizierung der SecSignID „johndoe“, auf einer Website mit Accesspass:

    ANTWORT

    Wenn die zuvor gesendete Anfrage akzeptiert wird, sendet der Server eine Antwort mit HTTP Statuscode 200 und folgende url-kodierte Parameter im Nachrichtenrumpf. Kommt es zu einem Fehler, wird der entsprechende Statuscode übergeben und die übertragene Parameterliste enthält Fehlerbeschreibungen (siehe 6. Fehlermeldungen).

    PARAMETER NAME STATUS VALUE
    authsessionid immer 19-stellige Zahl – die ID der angeforderten Sitzung
    servicename immer Der Servicename der Anfrage
    SecSignID immer Die SecSignID des Users
    authsessionstate immer Session Status
    Status der Sitzung
    0 No-State: Sitzungsstatus ist undefiniert
    1 Pending: Die AuthSession wurde weder bestätigt noch abgelehnt
    2 Expired: Die AuthSession ist abgelaufen (Zeitlimit ist 2 Minuten)
    3 Accepted: Die Sitzung wurde vom Nutzer auf seinem Smartphone akzeptiert
    4 Denied: Die Sitzung wurde vom Nutzer zurück gewiesen
    5 Suspended: Der ID-Server hat die Sitzung abgebrochen. Zum Beispiel bei einem mehrfachen Loginversuch ohne dass der Nutzer die Sitzung ablehnt oder akzeptiert
    6 Canceled: Der Loginprozess wurde durch den Nutzer auf der Website/dem Client abgebrochen
    7 Fetched: Der Nutzer hat die Smartphone App geöffnet und bekommt den Accesspass angezeigt, hat aber noch nichts bestätigt oder abgewiesen
    8 Invalid: Die Sitzung ist ungültig
    serviceaddress immer Die Serviceadresse der Anfrage
    requestid immer ID der aktuell angeforderten Sitzung. Über diese ID werden weitere Abfragen z.B. über den Sitzungs-Status zugeordnet.
    authsessionicondata immer Der AccessPass wird als ein Base64-kodiertes PNG-Bild zurückgegeben und muss dem Nutzer, der sich anmelden möchte, angezeigt werden. Die gleiche Grafik wird vom ID-Server an dessen Smartphone geschickt, wo er dann durch Vergleich der Grafik die AuthSession auf dem Smartphone akzeptiert.

    Der Accesspass befindet sich unter authsessionicondata und kann im Falle von HTML direkt in das img Element eingebunden werden:

    5. Status der Authentifizierung abfragen

    Um zu erfahren, ob der Nutzer die Authentifizierungs-Sitzung bereits auf dem Smartphone akzeptiert oder abgelehnt hat, muss der Client den Status der Authentifizierung abfragen. Dies kann je nach Client in regelmäßigen Abständen (Polling) erfolgen, bis ein Statuscode geliefert wird, wo entsprechend reagiert werden kann (zum Beispiel bei Bestätigung des Logins kann der Nutzer eingeloggt werden).

    ANFRAGE

    Wie schon zuvor beim Starten der Authentifizierungs-Sitzung, muss der Client eine POST Anfrage zum SecSignID API Server stellen um in diesem Falle den Status abzufragen. Die zu übertragenden Parameter sind URL codiert.

    PARAMETER NAME STATUS VALUE
    request erforderlich ReqGetAuthSessionState
    ReqGetAuthSessionState
    Teilt dem Server mit, dass es sich hierbei um eine Anfrage zu einem Sitzungsstatus handelt. Um welche Sitzung es sich handelt wird in der authsessionid und requestid angegeben
    secsignid erforderlich Die SecSignID des Users
    authsessionid erforderlich Session ID
    requestid erforderlich ID der aktuell angeforderten Sitzung. Über diese ID werden weitere Abfragen z.B. über den Sitzungs-Status zugeordnet.
    apimethod erforderlich
    (bald optional)
    Dieser Parameter beschreibt die Umgebung in der die Authentifizierung stattfindet:, bzw welche API verwendet wird SecSignIDApi_PHP
    SecSignIDApi_C

    Beispiel für die Anfrage des Sitzungs-Status:

    ANTWORT

    Die Antwort vom SecSignID Server enthält den Parameter „authsessionstate“, welcher den Status der Authentifizierungs-Sitzung beschreibt. Je nach Status kann entsprechend beim Client reagiert werden. Gilt der Status als bestätigt (3), kann der Nutzer eingeloggt werden. Wurde die Authentifizierung suspendiert (5) oder abgelehnt (4) kann der Nutzer zurück zum Login geführt werden. Wird noch auf die Bestätigung oder Abbruch gewartet (1) sollte der Status nach kurzer Zeit noch einmal abgefragt werden.

    PARAMETER NAME STATUS VALUE
    message optional Statusmeldung wenn der Nutzer nicht authentifiziert werden konnte und kein technischer Fehler auftrat, zum Beispiel beim Ablehnen der Authentifizierung: „You have denied the access pass.“
    authsessionid immer The session ID
    secsignid optional Die SecSignID des Users wird gesendet, wenn der Nutzer korrekt authentifiziert wurde. Diese SecSignID sollte für weitere Loginschritte beim Client genutzt werden, denn vorherige Angaben der SecSignID können statt der richtigen SecSignID den Priority Code beinhalten (siehe 8).
    authsessionstate immer Status der Sitzung
    0 No-State: Sitzungsstatus ist undefiniert
    1 Pending: Die AuthSession wurde weder bestätigt noch abgelehnt
    2 Expired: Die AuthSession ist abgelaufen (Zeitlimit ist 2 Minuten)
    3 Accepted: Die Sitzung wurde vom Nutzer auf seinem Smartphone akzeptiert
    4 Denied: Die Sitzung wurde vom Nutzer zurück gewiesen
    5 Suspended: Der ID-Server hat die Sitzung abgebrochen. Zum Beispiel bei einem mehrfachen Loginversuch ohne dass der Nutzer die Sitzung ablehnt oder akzeptiert
    6 Canceled: Der Loginprozess wurde durch den Nutzer auf der Website/dem Client abgebrochen
    7 Fetched: Der Nutzer hat die Smartphone App geöffnet und bekommt den Accesspass angezeigt, hat aber noch nichts bestätigt oder abgewiesen
    8 Invalid: Die Sitzung ist ungültig

    Beispiel für die Antwort zur Abfrage des Sitzungs-Status:

    Beispiel für die Antwort zur Abfrage des Sitzungs-Status, wenn der Nutzer die Authentifizierung abgelehnt hat:

    6. Authentifizierung freigeben oder abbrechen

    Eine Authentifizierung kann jederzeit abgebrochen werden, solange der Nutzer noch nicht den Login auf seinem Smartphone bestätigt hat. Eine Sitzung kann freigegeben werden, wenn der Nutzer korrekt angemeldet wurde und die Sitzungsinformationen nicht noch einmal vom Server abgerufen werden müssen.

    REQUEST
    PARAMETER NAME STATUS VALUE
    request erforderlich ReqReleaseAuthSession
    Teilt dem Server mit, dass die Sitzung, zum Beispiel bei einer erfolgreichen Authentifizierung freigegeben werden soll

    ReqCancelAuthSession

    Teilt dem Server mit, dass die Sitzung abgebrochen werden sollReqCancelAuthSession
    Informs the server to cancel the session.

    secsignid erforderlich Die SecSignID des Users
    authsessionid erforderlich ID der Sitzung
    requestid erforderlich ID der aktuell angeforderten Sitzung. Über diese ID werden weitere Abfragen z.B. über den Sitzungs-Status zugeordnet.
    apimethod erforderlich
    (bald optional)
    Dieser Parameter beschreibt die Umgebung in der die Authentifizierung stattfindet:, bzw welche API verwendet wird
    SecSignIDApi_Ruby, SecSignIDApi_Python, …

    Beispiel für den Abbruch der Authentifizierungs-Sitzungs:

    ANTWORT

    Die Antwort des Servers enthält die ID der Sitzung, welche beendet wurde, sowie noch einmal den Status der Sitzung. Wird nach Freigabe oder Beendigung der Sitzung noch eine Statusanfrage gesendet, so wird ein Fehler zurück gesendet, da die Sitzung nicht mehr existiert.

    PARAMETER NAME STATUS VALUE
    authsessionid erforderlich The session ID
    authsessionstate erforderlich Status der Sitzung
    0 No-State: Sitzungsstatus ist undefiniert
    1 Pending: Die AuthSession wurde weder bestätigt noch abgelehnt
    2 Expired: Die AuthSession ist abgelaufen (Zeitlimit ist 2 Minuten)
    3 Accepted: Die Sitzung wurde vom Nutzer auf seinem Smartphone akzeptiert
    4 Denied: Die Sitzung wurde vom Nutzer zurück gewiesen
    5 Suspended: Der ID-Server hat die Sitzung abgebrochen. Zum Beispiel bei einem mehrfachen Loginversuch ohne dassd er Nutzer die Sitzung ablehnt oder akzeptiert
    6 Canceled: Der Loginprozess wurde durch den Nutzer auf der Website/dem Client abgebrochen
    7 Fetched: Der Nutzer hat die Smartphone App geöffnet und bekommt den Accesspass angezeigt, hat aber noch nichts bestätigt oder abgewiesen
    8 Invalid: Die Sitzung ist ungültig

    Beispiel für die Antwort zur Freigabe der Sitzung nach erfolgreicher Authentifizierung:

    7. Fehlermeldungen

    Es gibt zwei verschiedene Arten von Fehlermeldungen:

    1. Technische Fehler können zum Beispiel durch fehlerhafte Syntax der Parameterlisten entstehen. Diese Fehlermeldungen werden mit einem HTTP Statuscode 400 zurückgegeben und enthalten einen HTML Nachrichtenrumpf, z.B.:

    2. Kontextfehler können auftreten wenn es Probleme mit der Authentifizierung an sich gibt, das heißt wenn die angegebene SecSignID nicht existiert oder die Sitzung abgelaufen ist.

    PARAMETER NAME STATUS VALUE
    error immer HTTP Statuscode des Fehlers
    errormsg immer Beschreibung des Fehlers
    errormsg immer Beschreibung des Fehlers als Zahl

    8. Priority Codes

    Ein Nutzer kann sich nicht gleichzeitig bei mehreren Diensten mit seiner SecSignID authentifizieren ohne die vorherige zu bestätigen oder abzulehnen. Dieser Fall ist sicherheitsrelevant, denn so kann es nicht zu Verwechslungen oder versehentlich bestätigten Logins führen.

    Werden zwei Login Sessions (mittels ReqRequestAuthSession) hintereinander angefragt, ohne dass der Nutzer die Authentifizierung auf seinem Smartphone bestätigt, werden alle Logins suspendiert und ein entsprechender Fehler kommt zurück.

    Der Nutzer kann die Suspendierung aufheben, indem er auf seinem Smartphone seine SecSignID antippt.

    Besteht das Problem weiterhin, wird auf dem Smartphone ein Priority Code angezeigt, welcher statt der SecSignID für ein Login genutzt werden kann. Wird der Login auf dem Smartphone bestätigt, liefert „ReqGetAuthSessionState“ die echte SecSignID des Nutzers zurück.

    9. Unsere APIS

    Wir haben eine stetig wachsende Liste an APIs und Plugins um die SecSign ID Zwei-Faktor Authentifizierung einfach und schnell in jedes Projekt zu integrieren.
    Wir bieten nicht nur APIs in zahlreichen Programmiersprachen, sondern auch Plugins für CMS, Server und VPN Umgebungen, oAuth2 und zahlreiche mehr. Die Plugins nutzen unsere APIs und bieten zusätzliche Funktionen, zum Beispiel Nutzer Management, einfache und native Installation, Logging oder die Integration in Firewalls oder Active Directories.

    Das JIRA Plugin beispielsweise nutzt die JAVA-API. Die PHP-API und JS-API wird von WordPress, Joomla, Drupal, Typo3 und vielen anderen genutzt. Die ASP.net/C#-API wird für die Windows und Cisco VPN genutzt und die C-API findet Verwendung um Unix SSH Services zu schützen. Die Objective-C API wird für unsere AppleTV und iPhone und iPad Apps genutzt.

    available_apis

    10. Erfahren Sie mehr

    Sie können die SecSign ID Zwei-Faktor Authentifizierung und den Zwei-Faktor Login durch eine einfach Integration des Plugins in Ihre Website oder Ihre Testumgebung kennenlernen. Oder testen Sie den Login auf unserer Website, ohne sich vorher zu registrieren. Sie haben bereits eine SecSign ID oder hätten gerne eine? Loggen Sie sich jetzt ein und nutzen Sie das Portal oder registrieren Sie sich ganz unkompliziert.

    Erfahren Sie selbst, wie schnell und unkompliziert der Login Prozess mit der Challenge-Response Authentifizierung mit 2048-bit Schlüsselpaaren ist. Sie brauchen keine Passwörter, und es werden keine vertraulichen Logindaten übertragen. Einfache Integration und unkomplizierte Nutzung.

    Für mehr Informationen zum patentierten SafeKey Verfahren finden Sie hier.

    Falls Sie eine API für eine Programmiersprache vermissen kontaktieren Sie uns unverbindlich. Falls Sie Hilfe mit der Integration in ein existierendes System brauchen oder kein passendes Plugin für Ihr Content Management System finden, kontaktieren Sie unser Support Team und wir helfen Ihnen gerne weiter.

    Ihr eigener ID-Server

    Die Inhouse Installation der SecSign ID bietet Ihnen die Flexibilität, sich mit Ihren bevorzugten Server, Services und Geräten zu verbinden. Passen Sie die SecSign ID Ihrer Unternehmensmarke an!

    your_own_id

    Warum sollte ich SecSign nutzen?

    Inhouse oder Cloud Lösungen

    Unsere Lösungen lassen sich leicht anpassen: Wählen Sie zwischen der durch uns betriebenen SecSign Cloud oder betreiben Sie selber den SecSign Authentifizierungsserver Inhouse oder in einem Rechenzentrum Ihrer Wahl. Mehr zum Inhouse Zwei-Faktor Authentifizierungsserver

    Einfache Anpassung an Ihre Bedürfnisse

    Wir passen die App an ihre Unternehmens Look-and-Feel an. Zwei-Faktor Authentifizierung angepasst an Ihre Bedürfnisse, für Ihre Kunden.

    Anwendungsfertiges SDK

    Integrieren Sie die SecSign Zwei-Faktor Authentifizierung in existierende Apps mit unserem SDK. Es könnte nicht einfacher gehen.

    Unkompliziertes Nutzer-Management

    Nutzen sie den Zwei-Faktor Authentifizierungsserver zum Schutz Ihres Active Directory/LDAP. Ihr individuelles Identity and Access Management System, beispielsweise mit verpflichtenden Updates und zahlreichen Sicherheitseinstellungen.

    Schützen Sie ALLE Logins

    Integration in sämtliche Login-Umgebungen: Web, Local, VPN, Remote Desktop, Mobile Logins und viele mehr.

    Plugins für alle Anwendungsgebiete

    Komplexe Integrationen gehören der Vergangenheit an: SecSign bietet Ihnen Plugins für nahezu alle Umgebungen.

    Letzte Blog Einträge, Neuigkeiten & Funktionen

    Crowd SSO

    21.09.2017

    Read More
    Do NOT follow this link or you will be banned from the site!