CSC API

CSC API

Einführung

Willkommen bei der CSC API von SIGN8! Dieser Leitfaden soll Ihnen helfen, unsere CSC API nahtlos in Ihr System zu integrieren. Die CSC API kann verwendet werden, um digitale Signaturen auf Dokumenten und Daten zu erstellen. Sie folgt den vom Cloud Signature Consortium (CSC) festgelegten Standards.

Das CSC ist eine Gruppe von Organisationen, die zusammenarbeiten, um Standards für elektronische Signaturen in der Cloud zu definieren. Durch die Einhaltung dieser Standards ist unsere Lösung für elektronische Signaturen mit anderen CSC-kompatiblen Systemen interoperabel. Das bedeutet, dass Dokumente, die mit unserer API signiert wurden, von anderen elektronischen Signaturplattformen, die ebenfalls den CSC-Richtlinien folgen, erkannt und akzeptiert werden können.


Erste Schritte

Um auf unsere CSC API zugreifen zu können, müssen Sie ein Enterprise- oder Volumenbasiertes-Abonnement abschließen. Führen Sie nach dem Kauf die folgenden Schritte aus:

Zugriff auf die Dokumentation: Navigieren Sie in Ihrer SIGN8-App zum Bereich Administration. Dort finden Sie den API-Button, mit dem Sie Zugriff auf die technische Dokumentation für Ihre Entwickler erhalten.

Antrag auf Integrationszugang: Kontaktieren Sie unser Team und teilen Sie ihm mit, dass Sie unsere Lösung in Ihr System integrieren möchten. Unsere Entwickler werden Ihnen den erforderlichen Zugang zur Verfügung stellen.

Zugriff auf Systeme: Wenn Sie auf die Dokumentation zugreifen, erhalten Sie Zugriff auf das Produktivsystem und das Testsystem, die jeweils mit einer entsprechenden Lizenz ausgestattet sind. So können Sie Ihre Integration in einer kontrollierten Umgebung entwickeln und testen.

Begriffe und Definitionen

  • Signatur-App: Dies ist die Software oder der Dienst, der die SIGN8-API verwendet, um digitale Signaturen zu erstellen.

  • HTTPS: Dies ist eine sichere Methode, um Daten über das Internet zu versenden.

  • UUID: Dies ist eine eindeutige ID, die in Computersystemen verwendet wird.

  • Access Token: Dies ist ein spezieller Code, der es einem Computersystem ermöglicht, auf geschützte Ressourcen zuzugreifen. Es handelt sich um eine Zeichenfolge, die eine dem Client erteilte Autorisierung darstellt. Die Zeichenfolge ist für den Client normalerweise nicht sichtbar.

  • Authentication Factor: Dies sind Angaben, die verwendet werden, um die Identität eines Benutzers zu überprüfen.

  • Credential: Ein digitales Objekt, das zur Erstellung digitaler Signaturen im Internet verwendet wird.

  • Digital Signatur: Ein durch Verschlüsselung mit einem öffentlichen Schlüssel erzeugter digitaler Code, der an ein elektronisch übermitteltes Dokument angehängt wird, um dessen Inhalt und die Identität des Absenders zu verifizieren.

  • Signatur-Aktivierungsdaten: Dies sind Daten, die verwendet werden, um einen digitalen Signaturprozess zu steuern.

  • OAuth 2.0: Steht für "Open Authorization" und ist ein Standardprotokoll für die Autorisierung. Es ermöglicht einer Website oder Anwendung, im Namen eines Benutzers auf Ressourcen zuzugreifen, die von anderen Webanwendungen gehostet werden, ohne die langfristigen Anmeldedaten oder sogar die Identität des Benutzers preiszugeben.


Hier sind einige wichtige Konzepte im Zusammenhang mit OAuth 2.0:


  1. Resource Owner: Der Benutzer oder das System, das Eigentümer der geschützten Ressource ist und Zugriff darauf gewähren kann.
  2. Client:  Das System, das Zugriff auf die geschützten Ressourcen benötigt. Um auf die Ressourcen zugreifen zu können, muss der Client im Besitz des entsprechenden Access Tokens sein.
  3. Authorization Server: Dieser Server nimmt Anfragen des Clients nach Access Tokens entgegen und stellt diese nach erfolgreicher Authentifizierung und Zustimmung des Ressourcenbesitzers aus.
  4. Resource Server: Ein Server, der die Ressourcen des Nutzers schützt und die Zugriffsanfragen des Clients entgegennimmt.
  5. Access Tokens: Dies sind Daten, die die Berechtigung zum Zugriff auf Ressourcen im Namen des Endnutzers repräsentieren.
  6. Scopes: Sie werden verwendet, um genau festzulegen, aus welchem Grund der Zugriff auf Ressourcen gewährt werden darf.
OAuth 2.0 ist in erster Linie als Mittel zur Gewährung des Zugriffs auf eine Reihe von Ressourcen wie Remote-APIs gedacht. Es führt eine Autorisierungsschicht ein und trennt die Rolle des Clients von der des Ressourcenbesitzers.
Abkürzungen

Abkürzungen

  • API: application programming interface

  • CSC: Cloud Signature Consortium

  • HSM: hardware security module

  • RSCD: remote signature creation device

  • RSSP: remote signing service provider

  • SAD: signature activation data SAM: signature activation module

  • SCAL1: sole control assurance level 1

  • SCAL2: sole control assurance level 2


Architektur



Für weitere Informationen finden Sie hier den Standard des Cloud Signature Consortiums.

Der Prozess der Fernsignierung besteht aus vier Hauptschritten:


Schritt 1: Beschaffung des Dokuments: Die Signaturanwendung erhält das zu signierende Dokument vom Benutzer. Gegebenenfalls erhält sie auch Zertifikate, Sperrinformationen und Zeitstempel von einem Vertrauensdiensteanbieter


Schritt 2: Requesting a Signature: Die Signaturanwendung fordert einen Remote Signing Service Provider (RSSP) auf, eine Signatur für den Hashwert des Dokuments (ein eindeutiger Code, der aus dem Dokument generiert wird) zu erstellen


Schritt 3: Binding Credentials: Der RSSP arbeitet mit einer Zertifizierungsstelle (CA) zusammen, um die Anmeldeinformationen zu binden. Manchmal hilft die CA auch bei der Erzeugung des Signaturschlüssels


Schritt 4: Authorization: Die Autorisierung des Dienstes oder des Zugriffs auf die Anmeldeinformationen kann auf zwei Arten erfolgen. Er kann entweder über die Signaturanwendung oder über eine Umleitung zu einem externen OAuth 2.0 Autorisierungsserver erfolgen. In vielen Fällen ist dieser Autorisierungsserver Teil der RSSP


Dieser Prozess stellt sicher, dass das Dokument sicher signiert ist und dass die Anmeldeinformationen des Benutzers ordnungsgemäß autorisiert sind.


Flows

Es gibt zwei verschiedene Möglichkeiten, die SIGN8 CSC API zu verwenden. Bei der ersten Möglichkeit muss die signierende Anwendung den Benutzer zweimal umleiten. Die zweite Methode erfordert nur einen Redirect. Beide Methoden beinhalten verschiedene Schritte, wie das Anfordern von Autorisierungscodes, den Austausch von Codes gegen Accesstoken, das Anfordern von Signaturen und das Widerrufen von Accesstoken.


Flow 1

Der erste Flow verwendet die Autorisierung durch Service und Credential. Daher muss die signierende Anwendung den Benutzer zweimal umleiten. 

Das Diagramm zeigt den Prozess, an dem ein User, eine Signaturanwendung (Signature Application), ein Autorisierungsserver und ein Remote Service beteiligt sind.

Es folgt eine vereinfachte Erklärung:

User: Dies ist die Person, die den Prozess initiiert. Er interagiert mit der Signaturanwendung, um ein Dokument zu signieren


Signature Application: Dies ist die Software oder der Dienst, mit dem der Benutzer interagiert. Sie kommuniziert mit dem Autorisierungsserver und dem entfernten Dienst, um das Signieren des Dokuments zu ermöglichen

Authorization Server: Dies ist das System, mit dem die Signature Application kommuniziert. Er ist für die Autorisierung des Users und der Signature Application zur Durchführung des Signaturvorgangs verantwortlich

Remote Service: Diese Komponente ist für die Durchführung des Signaturprozesses unter Verwendung der vom Benutzer angegebenen Anmeldedaten verantwortlich. Sie empfängt Anfragen von der Signaturanwendung, um den Signaturprozess zu initiieren, verarbeitet diese Anfragen und interagiert mit den vom User angegebenen Anmeldedaten, um die elektronische Signatur zu erzeugen.

Was passiert Schritt für Schritt


Schritt 1: Initiierung durch den User:

Der elektronische Signaturprozess beginnt, wenn ein User beschließt, ein Dokument mit der Signaturanwendung, die von Unternehmen X bereitgestellt wird, zu signieren. Dies kann durch den Benutzer initiiert werden, der einen Vertrag, eine Vereinbarung oder ein anderes Dokument unterzeichnen muss, das seine elektronische Signatur erfordert.

Schritt 2: Autorisierungscode anfordern (Initial):

Die Signaturanwendung kommuniziert nach Erhalt der Anforderung des Benutzers, ein Dokument zu signieren, mit dem Autorisierungsserver, um einen Autorisierungscode zu erhalten. Dieser Code dient als temporärer Token, der es der Signaturanwendung ermöglicht, die Identität des Benutzers zu authentifizieren.

Schritt 3: Benutzeranmeldung:

Um den Benutzer zu authentifizieren, fordert die Signaturanwendung ihn auf, sich bei seinem Konto anzumelden oder seine Zustimmung zum Zugriff auf seine Signatur zu geben. Dieser Prozess umfasst in der Regel ein Popup oder eine weitergeleitete Seite, auf der der Benutzer seine Anmeldedaten eingibt oder seine Autorisierung erteilt.

Schritt 4: Rückgabe des Autorisierungscodes (Initial):

Nach erfolgreicher Authentifizierung oder Zustimmung erzeugt der Autorisierungsserver einen Autorisierungscode und sendet ihn an die Signaturanwendung zurück. Dieser Code dient als Nachweis, dass der Benutzer authentifiziert und autorisiert wurde, auf seine Signatur zuzugreifen.

Schritt 5: Austausch des Codes gegen ein Zugriffstoken (Initial):

Mit dem erhaltenen Autorisierungscode sendet die Signaturanwendung eine Anfrage an den Autorisierungsserver, um ihn gegen ein Access Token auszutauschen. Dieses Access Token dient als langfristiger Berechtigungsnachweis, der es der Signaturanwendung erlaubt, auf die Signatur des Benutzers zuzugreifen, ohne dass dieser sich wiederholt anmelden muss.

Schritt 6: Rückgabe des Zugriffstokens (Initial):

Nach erfolgreichem Austausch gibt der Autorisierungsserver das Zugriffstoken an die Signaturanwendung zurück. Dieses Token wird sicher gespeichert und bei späteren Anfragen zum Zugriff auf die Signaturdaten des Benutzers verwendet.

Schritt 7: Anforderung von Credential-Informationen:

Um den Signaturprozess zu erleichtern, benötigt die Signaturanwendung Informationen über die verfügbaren Anmeldeinformationen des Benutzers. Sie sendet eine Anfrage an einen entfernten Server, um diese Informationen zu erhalten, einschließlich Details über die Arten von Berechtigungsnachweisen, die der Benutzer zum Signieren verwenden kann.

Schritt 8: Rückgabe der Berechtigungsnachweisinformationen:

Der Remote-Server antwortet auf die Anfrage der Signaturanwendung, indem er Informationen über die verfügbaren Anmeldeinformationen für den Benutzer bereitstellt. Anhand dieser Informationen kann die Signaturanwendung feststellen, welche Berechtigungsnachweise für den Signiervorgang zu verwenden sind.

Schritt 9: Berechtigungscode anfordern (Scope=Credential):

In manchen Fällen benötigt die Signaturanwendung eine spezielle Berechtigung, um auf bestimmte Credentials für den Signiervorgang zuzugreifen. Sie fordert einen weiteren Autorisierungscode vom Autorisierungsserver an, wobei sie den Geltungsbereich als „Credential“ angibt.

Schritt 10: Berechtigungsnachweis mit OTP autorisieren:

Wenn für bestimmte Anmeldeinformationen eine zusätzliche Autorisierung erforderlich ist, z. B. durch ein Einmalpasswort (OTP), folgt der Benutzer den Aufforderungen auf einer Popup-Seite oder einer weitergeleiteten Seite, um die Anmeldeinformationen beim Autorisierungsserver zu autorisieren.

Schritt 11: Austausch des Codes für das Zugangs-Token (Credential Scope):

Nachdem die Signaturanwendung die erforderliche Autorisierung erhalten hat, tauscht sie den für bestimmte Berechtigungsnachweise erhaltenen Autorisierungscode gegen ein anderes Zugriffstoken aus. Dieses Token ist spezifisch für das/die autorisierte(n) Credential(s) und gewährt den Zugriff auf diese.

Schritt 12: Rückgabe des Zugriffstokens (Credential Scope):

Der Autorisierungsserver gibt das Zugriffstoken für den/die autorisierten Berechtigungsnachweis(e) an die Signaturanwendung zurück. Dieses Token wird ausschließlich für den Zugriff auf das/die angegebene(n) Credential(s) während des Signiervorgangs verwendet.

Schritt 13: Anforderung der Signatur:

Mit dem erhaltenen Access Token und den Credential-Informationen sendet die Signaturanwendung eine Anfrage an den Remote-Server, um den Signiervorgang zu starten. Diese Anfrage enthält das zu signierende Dokument und alle erforderlichen Metadaten.

Schritt 14: Rücksignatur:

Der entfernte Server verarbeitet die Signaturanforderung der Signaturanwendung, unterstützt den Signaturprozess unter Verwendung der angegebenen Anmeldeinformationen und sendet das signierte Dokument oder die Bestätigung der Signatur an die Signaturanwendung zurück.

Schritt 15: Token-Zugriff widerrufen (optional):

Nach Abschluss des Signiervorgangs kann die Signaturanwendung das/die ihr gewährte(n) Zugriffstoken widerrufen, indem sie eine Anfrage an den Autorisierungsserver sendet. Dieser Schritt stellt sicher, dass die Anwendung nicht mehr ohne ausdrückliche Zustimmung auf die Anmeldedaten des Benutzers zugreifen kann, was die Sicherheit und den Datenschutz erhöht.


    Sie benötigen weitere Unterstützung?

      • Related Articles

      • Workflow API

        Einführung Willkommen bei der Workflow-API von SIGN8! Dieser Leitfaden soll Ihnen helfen, unsere Workflow-API nahtlos in Ihr System zu integrieren. Die Workflow API bietet Kernfunktionalität für die Verwaltung von Workflows innerhalb von ...

      • Integration für Ihr System

        Hier finden Sie umfassende Informationen zu unseren API-Lösungen für digitale Signaturen. Als führender Anbieter bieten wir zwei Arten von APIs an, die Ihnen eine nahtlose Integration und effiziente Arbeitsabläufe ermöglichen: Workflow API Die ...

      • API Changelog

        September 2024 New Features Breaking Changes Zeitpunkt der Signatur (Datum) wird nun im Signaturbild der QES angezeigt. Bug Fixing August 2024 New Features Breaking Changes Bug Fixing Juli 2024 New Features Breaking Changes Bug Fixing Juni 2024 New ...