Abgekündigt

Das SDK verwendet den Hybrid Flow. Bestehende Anwendungen können den Hybrid Flow und das SDK weiterhin verwenden, aber neue Anwendungen sollten den Code Flow verwenden. Weitere Informationen unter OAuth2.0 & OpenID connect und OAuth2.0 Code Flow with PKCE .NET Sample.

Übersicht

Die DATEV Cloud Authentication Library (DCAL) ist ein Framework zur Authentifizierung des Benutzers und zur Autorisierung von .NET-Apps mit dem DATEV-Rechenzentrum zum Aufruf von DATEV APIs.

Zur Authentifizierung benötigt der Endanwender ein DATEV-Authentifizierungsmedium (SmartLogin, SmartCard, ..).

Lizenz

DATEV eG räumt dem Entwickler das Recht ein, die DATEV Cloud Authentication Library zu nutzen, zu vervielfältigen und als Teil einer eigenen App öffentlich zugänglich zu machen.

Registrierung bei DATEV für 3rd-Party .NET-Apps

Die Schritte zur Verwendung der DATEV-Authentifizierungsbibliothek für .NET-Apps sind:

• Laden Sie die Library herunter
• Registrieren Sie sich bei DATEV als Kunde (client)
  • Sie erhalten eine client_id
  • Sie erhalten einen client_secret

Um sich anzumelden, bereiten Sie bitte die folgenden Informationen für DATEV vor:

Sie erhalten von DATEV die folgenden Parameter für das Autorisierungsverfahren:

Laufzeit Umgebungen im DATEV-Rechenzentrum

Im DATEV-Rechenzentrum gibt es für Entwickler eine Sandbox und für Anwender eine reguläre produktive Umgebung. Mit einem Token, den man von der Sandbox-Authority bekommen hat, kann man keine API in der regulären produktiven Umgebung ansprechen- und umgekehrt: Mit einem Token aus der regulären produktiven Umgebung ist kein Zugriff auf eine API in der Sandbox möglich.

DATEV Endpoints

Informationen für die Implementierung

Download und Einrichtung

The DCAL .NET library is available for download via NuGet.

1. NuGet-Paket Datev.Cloud.Authentication herunterladen und entpacken von nugetpackage (selbstextrahierende Exe)
2. NuGet-Paket in Visual Studio einbinden:
   • In Visual Studio im Menü Tools | NuGet Package Manager | Package Manager Settingsauswählen.
   • Unter Options | NuGet Package Manager | Package Sources adas lokale Verzeichnis mit dem NuGet-Paket Datev.Cloud.Authentication als zusätzliche Package Source hinzufügen
   • In Visual Studio Tools | NuGet Package Manager | Manage NuGet Packages wählen.
   • Unter NuGet Solution das Paket Datev.Cloud.Authentication. markieren. Rechts das Projekt auswählen und die aktuelle Version über die Schaltfläche Install installieren. Dem Projekt werden alle nötigen Referenzen hinzugefügt.

Verwendung der Datev.Cloud.Authentication

3rd-Party-Apps verwenden das NuGet-Paket Datev.Cloud.Authentication mit der Datev.Cloud.Authentication.dll und der Abhängigkeit zum NuGet-Paket IdentityModel.OidcClient. Weitere Abhängigkeiten werden von der NuGet-Paketverwaltung automatisch aufgelöst. Sämtliche DLLs müssen mit der App ausgeliefert werden - im gleichen Verzeichnis wie die App.

Typen von Datev.Cloud.AuthenticationTypen direkt verwendbar machen:

    using Datev.Cloud.Authentication;
                   

Dann ClientOptions erzeugen:

    var options = new ClientOptions(
                    authority,
                    clientId,
                    clientSecret,
                    clientScopes,
                    clientRedirectPort);

• authority = Identity Provider, entweder https://login.datev.de/openidsandbox/ oder https://login.datev.de/openid/
• clientId = ID der App, muss bei DATEV beantragt werden
• clientSecret = Kennwort zur clientId, muss sicher im Client ablegt werden.
• clientScopes = Bereich, für welchen eine Berechtigung beantragt wird. Format: openid … Alle Parameter müssen in Kleinbuchstaben geschrieben und durch ein Leerzeichen getrennt sein

• clientRedirectPort = Port, der vom Webbrowser nach der Authentifizierung angesprochen wird. Die Datev.Cloud.Authentication erzeugt daraus eine Redirect-URL: http://localhost:<port>/datev/authorize/<randomvalue> 

  Eine URLACL- Registrierung ist nicht notwendig. Der Port wird von der DLL per http.sys. abgehört.

Dann einen neuen Client anlegen:

    var client = new Datev.Cloud.Authentication.Client(options);

Die Methode LoginAsync aufrufen:

    var loginResult = await client.LoginAsync();

Der Webbrowser öffnet sich; die Anmeldung (über SmartCard oder anderes Medium) durchführen; ggf. auf der Consent Page auf OK klicken.

Der Redirect auf den vorher eingestellten Port wird ausgeführt. Webbrowser schließen (ggf. manuell).

Das LoginResult besteht aus 4 Strings und einem Bool:

• AccessToken = String, der für den Zugriff auf die API benötigt wird.
• RefreshToken = String, mit dem neue AccessToken erzeugt werden können.
• Error = String, der den Fehlertext enthält, wenn die Anmeldung fehlschlägt.
• IdentityToken = String, eindeutige ID des Users
• Success = true: die Anmeldung war erfolgreich, false: die Anmeldung war nicht erfolgreich

Ein RefreshTokenHandler und einen HTTP-Client anlegen:

    RefreshTokenHandler refreshTokenHandler = new RefreshTokenHandler(client, loginResult.RefreshToken, loginResult.AccessToken);
    
    var apiClient=new HttpClient(refreshTokenHandler);

Der RefreshTokenHandler setzt intern auch den Access Token. Der Refresh Token darf nur einmal verwendet werden.

ACHTUNG: Den einen HTTP-Client für alle HTTP-Verbindungen verwenden. Nicht mehrere HTTP-Clients mit gleichen Tokens erzeugen, Wird ein Refresh Token ein zweites Mal verwendet, werden alle Tokens dieser Anmeldung ungültig.

Mit dem apiClient die API aufrufen:

    var apiresult = await apiClient.GetAsync(new Uri("https://sandbox-api.datev.de/<required API>"));

Über den RefreshTokenHandler. wird automatisch ein neuer Access und Refresh Token abgeholt, wenn der Access Token abgelaufen ist. Dies funktioniert solange, bis der Refresh Token abgelaufen ist. Die Gültigkeitsdauer ist abhängig von der ClientID. Im Normalfall sind es 15 Minuten bei den Access Tokens und 11 Stunden bei den Refresh Tokens.

Danach liefert die API den Statuscode HTTP 401. Die App muss darauf mit einer neuen Anmeldung per LoginAsync reagieren. Danach erscheint erneut der Webbrowser mit der Anmeldung und der Consent Page

Spezialfall: Wenn das Senden (http put oder http post) mit einem System.Net.Http.StreamContent länger dauert als die Gültigkeitsdauer des Access Tokens (Statuscode HTTP 401), wird der Request nicht automatisch wiederholt (Streams können nur einmal gelesen werden). Wichtig ist, den Stream neu aufzubauen und nicht den gleichen Stream zweimal zu verwenden. Sonst gibt es eine Exception vom Typ System.InvalidOperationException mit dem Text „The stream was already consumed. It cannot be read again.” (bzw. deutsch: „Der Stream wurde bereits verbraucht. Er kann nicht noch einmal gelesen werden.“)

Der RefreshTokenHandler setzt auch einige DATEV-spezifische Header im HTTP-Request.

Webbrowser

Zur Anmeldung wird der Standardbrowser des Anwenders verwendet. Der Standardbrowser muss Chrome oder Edge (Chromium) oder Internet Explorer sein. Mit anderen Webbrowsern (z.B. Firefox) ist die DATEV-Anmeldung nicht möglich, dann wird stattdessen der Edge verwendet.

Diese Option RequireBrowserType wird ab V.1.5.1 nicht mehr unterstützt.

Anmeldemedium erzwingen

Mit

client.ConfigOptions.RequireAuthenticationMethod=AuthenticationMethod.SmartCard;

wird die Authentifizierung per SmartCard erzwungen. Das ist dann erforderlich, wenn andere Medien nicht unterstützt werden.

Mit

client.ConfigOptions.RequireAuthenticationMethod=AuthenticationMethod.SmartLogin;

wird die Authentifizierung per SmartLogin erzwungen.

Unterstützung von HTTP-Proxys beim Anwender

Soll ein HTTP-Proxy verwendet werden, muss beim Erzeugen des Clients ein IWebProxy übergeben werden.

Beispiel mit der WebProxy-Klasse für einen Proxy mit Basic-Authentifizierung:

var cred = new NetworkCredential(<user name>, <password>);
var proxy = new WebProxy(<proxy name>:<port number>, false, new string[] { }, cred);
var client = new Client(options, proxy);

Unterstützt der Proxy Windows-Authentifizierung (NTLM oder Kerberos), können auch die aktuellen Anmeldedaten des Anwenders übernommen werden.

Der gleiche Proxy muss auch beim HTTP-Client für die API verwendet werden. Dafür wird ein HttpClientHandler benötigt, der beim RefreshTokenHandler als InnerHandler übergeben wird:

    var proxyHandler = new HttpClientHandler 
                    {
                        Proxy = proxy,
                        UseProxy = true,
                    };
    var refreshTokenHandler = new RefreshTokenHandler(client, 
                                   result.RefreshToken,
                                   result.AccessToken,
                                   proxyHandler);
    using (HttpClient httpClient = new HttpClient(refreshTokenHandler))
    {
       // use httpClient ->
    }
    

Im LAN ohne direkten Internetzugang muss auch im verwendeten Webbrowser ein Proxy hinterlegt sein.

Medium "DATEV-Benutzer" bei Anwendern mit DATEV-Kommunikationsserver

Die Anmeldung mit einem DATEV-Benutzer in Verbindung mit einem DATEV-Kommunikationsserver wird unterstützt. Voraussetzung ist, das im LAN an einem PC die Software DATEV Kommunikationsserver in der Version 2.0 oder höher installiert ist (kostenpflichtiges DATEV-Produkt) und am LAN-Arbeitsplatz die RZ-Kommunikation in der Version 2.0 oder höher installiert ist. Das DFÜ-Profil am LAN-Arbeitsplatz muss DFÜ im Netzbetrieb sein, dann wird als Anmeldemedium der DATEV-Benutzer in Verbindung mit der zentralen SmartCard am Kommunikationsservers-PC verwendet. Der DATEV-Benutzer muss mit einer Person im DATEV-Rechenzentrum verknüpft sein. Weitere Informationen finden Sie in folgenden Dokumenten:

• Bestehenden DATEV-Benutzer mit Person im DATEV-Rechenzentrum verknüpfen:
  https://apps.datev.de/help-center/documents/1001465
• Voraussetzungen für die RZ-Webservicekommunikation:
  https://apps.datev.de/help-center/documents/1080471

Wenn man per client.ConfigOptions.RequireAuthenticationMethod das Anmeldemedium SmartCard oder SmartLogin erzwingt, wird die Anmeldung per DATEV-Benutzer nicht verwendet.

Logging

Die Datev.Cloud.Authentication und auch der darunter liegende IdentityModel.OidcClient bieten einen Logging-Mechanismus per Liblog, Informationen dazu siehe http://www.nuget.org/packages/LibLog/.

Auf diese Log-Informationen kann mit dem NuGet-Paket Serilog zugegriffen werden, siehe https://serilog.net/.

Für das Logging auf der Konsole das NuGet-Paket Serilog sowie Serilog.Sinks.Console installieren und das Logging aktivieren:

Log.Logger = new LoggerConfiguration() .MinimumLevel.Information().WriteTo.Console().CreateLogger();

Ausführliches Logging kann über

MinimumLevel.Debug()

erzeugt werden. Informationen zu weiteren Logging-Varianten siehe https://github.com/serilog/serilog/wiki/Provided-Sinks.

Beispiel für eine Konsolen-Anwendung siehe https://download.datev.de/download/developer-portal/dcal/datev.cloud.authentication.sample.zip