Sign in with a personal key and a second factor

A personal key (starts with wkl_, 53 characters) is a person's sign-in to the data service that works everywhere – without a domain, without a VPN, and without a SQL password. If the service also requires a second factor, the driver asks once per session for a code from the authenticator app. This guide sets up both for Access.

The connection specifies AUTH=KEY and no key. The user enters the key once in the driver's sign-in form and has it saved in Windows Credential Manager; the Access file never contains it. If the service requires a second factor, the driver exchanges a code for a session that applies to all connections of the Access process.

1. Have a key issued to you. The data service's administration does that, as text or as a one-time link; with the service's self-service, the person can also do it themselves (see “Create a person and issue a key” (administration application documentation)).

2. Specify the connection without a key: when setting up the data source, select the entry Personal key under Authentication, or set by code

   ODBC;DRIVER={Wkl OData};URL=https://daten.example.com/odata/v4/fachdaten/dbo/;AUTH=KEY

   The address must start with https or point to your own computer; otherwise the driver doesn't send the key and rejects the connection before anything is sent (28000; see Connection string: Exceptions).

3. Enter the key when you connect for the first time. The Sign in form appears with the note “… Enter your personal key (it starts with wkl_).” Paste the key, select Save key (Windows credentials), and select Sign in. The driver stores the key under the target Wkl.Data.OData.Odbc:(persönlicher Schlüssel)@<service-root>, only for your Windows account, and from then on signs in without asking.

   

4. Enter the second factor if the service requires it: in the Second Factor dialog over the Access window, enter the six-digit code in the field Code from the authenticator app and select Sign in. If the code is wrong, the driver asks again with the service's message, at most three times.

   

Result: Access links and reads; the service names the person and the key ID in its log. Further links of the same Access process don't ask for a code again until the session expires. How long it's valid is determined by the service, not by the driver; for the data service Wkl.Data.Gateway, the default is 10 hours.

Applications without a dialog (scripts, services, ADO.NET without a window) pass the key in PWD and the code in TOTP – or a session that they opened themselves in SESSION:

DRIVER={Wkl OData};URL=https://daten.example.com/odata/v4/fachdaten/dbo/;AUTH=KEY;PWD=wkl_…;TOTP=123456

• The session lives in the process, not on disk. After Access restarts, the driver asks once again. If it ends while you're working, the dialog appears again.
• One code for the application and the driver. An Access application that has exchanged a code for a session itself (for example with the data service's VBA class WklGatewayClient) passes it with SESSION=; the driver then doesn't ask again.
• Reports in Excel and Power BI can't enter a code. For them, the administration issues a read-only key that's exempt from the second factor.
• After “Abbrechen” (Cancel), the driver doesn't ask again for the same service for five seconds.
• On failure, Access shows only “ODBC–connection to … failed” (3151). The reason – for example “Der persönliche Schlüssel ist abgelaufen.” (The personal key has expired.) – is shown by the driver's tracing and the service's log; other applications receive it as a message.
• Replace or remove a saved key: Open Control Panel > Credential Manager > Windows Credentials, and edit or remove the entry Wkl.Data.OData.Odbc:(persönlicher Schlüssel)@….

• Driver connection string: `AUTH`, `PWD`, `TOTP`, `SESSION`
• Link a table in Access
• The connection fails with 08S01 "UntrustedRoot"