OAuth2.0 & OpenID connect

Login with DATEV (Login mit DATEV)

"Log in with DATEV" enables users within the DATEV ecosystem to easily register and sign in using their familiar access credentials ("Zugangsmedium"). To get started, users will need to register with DATEV and provide consent for their profile information to be utilized on your website. Furthermore, you can request authorization to access data within the DATEV ecosystem that is relevant for your application.

You must adhere to the Design Guidelines and comply with the Terms of Use.

Prerequisites

• Conclusion of a user contract
• Implementation of OAuth2.0/OpenID Connect Authorization Code Flow with PKCE

Interface requirements Login mit DATEV

Authentication Methods

The following authentication methods are available for “Login with DATEV”:

• DATEV SmartCard: This authentication method involves logging in with a hardware-based certificate, specifically the DATEV SmartCard or DATEV mIDentity. The SmartCard must be inserted into a USB slot on the user's computer.
• DATEV SmartLogin: Users can log in by scanning a QR code using the DATEV SmartLogin mobile app.
• DATEV Benutzer (WindowsSso): Users with DATEV RZ-Kommunikation and DATEV Kommunikationsserver installed can be authenticated with their Windows accounts. Note that this authentication method is automatically applied and not displayed to the user. Requires the parameter "enableWindowsSso=true" in the authorization request.
• DATEV-Benutzerkonto: In our sandbox environment, there is an additional DATEV authentication method known as "DATEV-Benutzerkonto." This method is exclusive to our APIs in the sandbox. DATEV provides a dedicated "DATEV-Benutzerkonto" for development purposes in the sandbox. 

Communication with the DATEV data center

"Login with DATEV" is our implementation of the OpenID Connect Authorization Code Flow with PKCE, allowing third-party applications to gain authorization for accessing the DATEV data center. To configure DATEV authentication for using our Online APIs, please follow these steps:

1. Register your application to establish communication with our APIs.
2. At present, only DATEV partners or "DATEV Schnittstellenanbieter" have access to our Online APIs. Your DATEV partner manager will handle your application registration. After completing this registration process, you will be provided with a Client ID and a Client Secret.
3. Implement the standard Authorization Code Flow with PKCE, as specified in OAuth 2.0 and OpenID Connect.

Authentication

The login process adheres to the OAuth/OIDC Authentication Code Flow with PKCE, as outlined in RFC 6749 Section 4.1.

Upon successful completion of the login process, the access token becomes available for making calls to the DATEV APIs. Any error codes for requests will follow the standard HTTP and error code definitions specified in OAuth 2.0, as per RFC 6749.

Within the specification, some adjustments are necessary for DATEV login:

You can utilize any available OAuth/OIDC library in your development environment that supports the authorization code grant (with PKCE). Here is an example of a implementation in C#: OAuth2.0 Code Flow with PKCE Sample

OAuth/OIDC Endpoints

OIDC Discovery Endpoint for the Sandbox environment:

https://login.datev.de/openidsandbox/.well-known/openid-configuration

OIDC Discovery Endpoint for the Productive environment:

https://login.datev.de/openid/.well-known/openid-configuration          

You can obtain information about other OAuth endpoints (such as token, authorize, jwks) via the discovery endpoint.

Enable Windows SSO with DATEV Identity (DID)

The optional authorization request parameter, "enableWindowsSso=true," facilitates single sign-on using Windows credentials, commonly referred to as DATEV Identity (DID). When this option is activated and Windows single sign-on is available, it will be employed automatically. The user will not be presented with the method choice if "EnableWindowsSso" is set to "true" and single sign-on (DID) is accessible within the current environment.

In cases where the user's environment is not configured for single sign-on, the user can select an authentication method, such as DATEV SmartCard or DATEV SmartLogin.

Token validity

The first access token is requested using the authorization code. Each access token is valid for 15 minutes. A refresh token is issued with each access token. The refresh token is valid for a maximum of 11 hours and can be used to request a new access token. If a refresh token is redeemed, this refresh token and the existing access token will be invalidated.

An unlimited number of refresh tokens can be redeemed in the 11-hour period after the first access token is issued. If the client submits the final refresh token 11 hours after the first access token is generated, the user can carry on working for a maximum of 15 minutes (the lifetime of the access token). After this time period, the user must reauthenticate himself, and the entire authentication process needs to be repeated.

The aim is for every user to be able to work for 11 hours without signing in again, as they only have to reauthenticate themselves after this period. In other words, it should be possible to work for one workday without reauthentication.

If you make a request with scope offline_access, the generated refresh token can be used for at least 2 years to request a new access tokens. Requests with scope offline_access are restricted to a single client. 

The refresh tokens provided are "single-use refresh tokens." It's essential to ensure that each refresh token is used only once. If a refresh token is mistakenly used more than once, it will result in the invalidation of all access and refresh tokens for that session, necessitating the user to go through the authentication process once more. 

Request with offline access

When you include the additional scope "offline_access," you can request a refresh token with a duration of 2 years. Each time you refresh the token, obtaining a new access and refresh token, the refresh token's expiration will be extended to 2 years from that point. As long as you refresh it within this 2-year window, the refresh token remains valid. However, if 2 years pass without refreshing, the user will need to reauthenticate.

Our 2-year refresh token comes with specific requirements. It is tied to a single consultant and client number (referred to as the {client-id}). As a result, you must request an additional scope formatted as follows: datev:iam:client:<consultant_number>-<client_number>.

Please note that due to the restriction to a single {client-id}, this token will only function with APIs where the {client-id} is part of the URL path.

• Won't work: ...api.datev.de/accounting/v1/clients
• Works: ...api.datev.de/accounting/v1/clients/{client-id}

In addition to these technical aspects, DATEV has specific requirements for the use of this token:

1. Before you request the token with offline access, you have to check the accessibility to the single client. Therefore you can request the list of the accessible clients or a list of basic data about a given client. Example for the API Accounting – Documents (1.0).
2. If you integrate this token into your app, you must also implement token revocation, allowing users to disconnect their accounts from your app.
3. Users can also revoke tokens using the DATEV app "Verbundene Anwendungen" at https://apps.datev.de/tokrevui. Ensure that your app prominently features a link to this DATEV app so that users can easily access it. Also see further information for that.

Request User Info from the UserInfo Endpoint

You can obtain user information about the currently logged-in user by making a request to the UserInfo endpoint. This step is optional and occurs at the conclusion of the login process.

The UserInfo endpoint is implemented in accordance with the OpenID Connect Core 1.0 specification.

The Access Token must be sent as a Bearer Token using the Authorization Header.

The UserInfo Endpoint Claims are provided as members within a JSON object. The specific Claims included in the response JSON object are determined by the OAuth 2.0 Scopes, as outlined in the following table.

Allowed Scopes:

Token revocation

To revoke previously granted access authorizations, DATEV provides support for the request revocation mechanism as outlined in RFC7009. Therefore, it is necessary that your application submits two revocation requests: one for the access token and one for the refresh token. These token revocation requests should be sent to the revocation endpoint.