Skip to content
/ app-vzd-cli Public

Tool for managing the Gematik Directory Service (VZD). The vzd-cli enables secure interactions with Directory Admin, Apo, and FHIR APIs via OAuth2, with options for configuration, search, entry management, and certificate handling.

License

EUPL-1.2 license
5 stars 3 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

gematik/app-vzd-cli

BranchesTags

Repository files navigation

🗂️ vzd-cli: Command Line Client für Verzeichnisdienst der TI

Table of Contents
vzd cli

Einführung

vzd-cli wurde in Vorbereitung der Migration des gematik Verzeichnisdienstes (VZD) von LDAP nach FHIR entwickelt. Über ein modernes CLI (Command Line Interface) können neue und alte Schnittstellen des VZD genutzt werden.

Seit version 2.1 bittet vzd-cli eine simple GUI.

Installation

Die neueste Version von vzd-cli herunterladen.

Für die Ausführung des vzd-cli soll die PATH Variable um den Pfad vzd-cli-<VERSION>/bin erweitert werden.

Sobald der Befehl vzd-cli ausgeführt werden kann sind wir start klar:

$ vzd-cli

Usage: vzd-cli [OPTIONS] COMMAND [ARGS]...

Options:
  -v          Display log, use -vv for even more details
  --version   Show the version and exit
  -h, --help  Show this message and exit

Commands:
  config               Manage configuration
  update               Updates this software
  login                Logins into all configured APIs
  admin                CLI for DirectoryAdministration API
  fhir                 CLI for FHIR Directory
  apo                  CLI for ApoVZD API
  gui                  Starts HTTP Server with GUI
  pers                 Process gematik SMC-B/HBA Exports
  generate-completion  Generate a tab-complete script for the given shell

Erste Schritte

Aufbau des vzd-cli folgt aktuellen Best-Practices analog z.B. zu Docker. Für alle Befehle (Commands) und Unter-Befehle (Subcommands) kann man mittels --help Option eine abschließende Liste aller Optionen und Argumente anzeigen lassen.

vzd-cli --help
vzd-cli config --help
vzd-cli config get --help
vzd-cli admin --help
vzd-cli admin ru --help

Konfiguration

Die Directory APIs werden über HTTPS erreicht. Falls für die Verbindung ein HTTP-Proxy erforderlich ist, muss es wie folgt konfiguriert werden:

# Beispiel Proxy (http://PROXY_HOST:PROXY_PORT)
vzd-cli config set httpProxy.proxyURL http://192.168.0.1:8080
vzd-cli config set httpProxy.enabled true

vzd-cli ermöglicht u.a. die Nutzung folgender APIs:

Für die Nutzung dieser APIs sind jeweils entsprechende Geheimnisse bzw. Credentials erforderlich. Diese werden von der gematik den bereichtigten Organistionen bereitgestellt.

Admin API Credentials

Directory Admin API benutzt für die Authentisierung das Oauth2 Client Credentials Flow. Um hierfür erforderlichen Credentials angemessen sicher aufbewahren zu können, stellt vzd-cli eine Vault (Tresor) Funktion bereit. Mithilfe der Vault werden alle Client IDs und Client Secrets verschlüsselt gespeichert. Um Vault aufmachen und darin enthaltenen Credentials nutzen zu können, wird der Nutzer aufgefordert einen Vault-Password zu vergeben. Dieser Password funktioniert analog zu den privaten Passwörtern bei den Password-Managern (z.B. Bitwarden, LastPass, 1Password). Die Vault Implementierung befinden sich in der Datei Vault.kt und verwendet von NIST emfohlene Verschlüsselung.

Falls das Speichern der Credentials nicht erwünscht ist, kann die Anmeldung direkt mit Client ID und Client Secret erfolgen, s. vzd-cli admin login-cred. Zusätzlich kann man einen vorhanden Token direkt setzen s. vzd-cli admin <tu|ru|pu> token.

# Vault zurücksetzen
vzd-cli admin vault purge

# Secret für die Referenzumgebung speichern
# es folgt eine Vault Passwortabfrage
vzd-cli admin vault store -e ru -c <CLIEND_ID> -s <CLIENT_SECRET>

# Secret für die Produktivumgebung speichern
# es folgt eine Vault Passwortabfrage
vzd-cli admin vault store -e pu -c <CLIEND_ID> -s <CLIENT_SECRET>

Vault Password kann alternativ über die Umgebungsvariable VAULT_PASSWORD (empfohlen) oder über --password Parameter angegeben werden (nicht empfohlen).

Apo API API-Keys

Zugriff auf Apo API (ApoVZD) wird mittels API-KEYs geschützt. Die API-KEYs werden durch die gematik an die berechtigte Anwendungen vergeben.

# API Key für die Testinstanz
vzd-cli apo config set apiKeys.test <API_KEY_TEST>
# API Key für die Produktivinstanz
vzd-cli apo config set apiKeys.prod <API_KEY_PROD>

(Neu) FHIR FDV Search API Credentials

Zugriff auf FHIR FDV Search API wird mittels OAuth2 Client Credentials Flow geschützt. Die berechtige Dienstanbieter erhalten die Client ID und Client Secret von der gematik.

# Secret für die Referenzumgebung speichern
# es folgt eine Vault Passwortabfrage für persönliche Vault
vzd-cli fhir fdv-vault store -e ru -c <CLIEND_ID> -s <CLIENT_SECRET>

# Secret für die Produktivumgebung speichern
# es folgt eine Vault Passwortabfrage für persönliche Vault
vzd-cli fhir fdv-vault store -e pu -c <CLIEND_ID> -s <CLIENT_SECRET>

Erste Schritte

Befor die Directory Admin API genutzt werden kann, muss eine Anmeldung erfolgen. Die Anmeldung muss alle 6 Stunden wiederholt werden.

# Anmelden in die Referenzumgebung (ru)
# es folgt eine Vault-Passwortabfrage
vzd-cli login ru
# Anmelden in die Referenzumgebung (pu)
# es folgt eine Vault-Passwortabfrage
vzd-cli login pu

Für vollautomatisierte Nutzung des vzd-cli, auch bei der Anmeldung, wird das setzten der Umgebungsvariable VAULT_PASSWORD empfohlen. Dabei soll die Umgebungsvarianle den während der Konfiguration angegeben Vault Passwort enthalten.

Beispiel: Suche nach allen Eintragen mit Müller im Namen in der Referenzumgebung (ru)
vzd-cli admin ru search Müller
Beispiel: Suche nach den Einträgen in Berlin in der Produktivumgebung (pu)
vzd-cli admin pu search Berlin
Beispiel: Suche nach allen Eintragen in Berlin mit dem Namen Müller in der Referenzumgebung (ru)
vzd-cli admin ru search Müller Berlin
Beispiel: Anzeige der Detailinformationen für die angegebene telematikID in der Referenzumgebung (ru)
vzd-cli admin ru show 1-SMC-B-Testkarte-883110000117729
(Neu) Beispiel: Suche nach einträgen in der FHIR FDV Search API in der Produktivumgebung (pu)
vzd-cli fhir pu fdv search healthcare-service -t <TelematikID>
vzd-cli fhir pu fdv search practitioner-role -t <TelematikID>
# oder in Kurzform
vzd-cli fhir pu fdv search hs -t <TelematikID>
vzd-cli fhir pu fdv search pr -t <TelematikID>

Übergreifende Befehle

vzd-cli config

Befehle für Konfiguration des vzd-cli. Folgende Konfigurationsparameter können geändert werden (s. vzd-cli config set --help)

  • httpProxy.enabled - wenn true, wird Proxy-Server bei allen Anfragen genutzt. Wenn false werden HTTP-Requests direkt ohne Proxy durchgeführt

  • httpProxy.proxyURL: URL des HTTP-Proxy Servers ggf. mit Port, z.B.: http://192.168.0.1:8080

  • updates.preReleasesEnabled: wenn true, werden beim vzd-cli update die Pre-Releses installiert

Beispiel: Aktuelle Konfiguration anzeigen
vzd-cli config get
Beispiel: Konfigurationsparameter ändern
vzd-cli config set httpProxy.proxyURL "http://example.com:8080"
vzd-cli config set httpProxy.enabled true
vzd-cli config set updates.preReleasesEnabled true
Beispiel: Konfiguration zurücksetzen
vzd-cli admin config reset

vzd-cli update

Aktualisiert das vzd-cli auf die neusete (oder angegebene Version). Anmerkung: Self-Updates werden erst ab der Version 2.1 unterstützt.

Beispiel: Falls eine neuere Version verfügbar ist, wird diese von github.com heruntergeladen und installiert
vzd-cli update
Beispiel: Installiert eine bestimmte Version (auch Downgrade ist möglich):
vzd-cli update 2.1.0-beta4

vzd-cli admin: Directory Administration

vzd-cli admin vault

Befehle zur Verwaltung von OAuth2 Geheimnissen

Usage: vzd-cli admin vault [OPTIONS] COMMAND [ARGS]...

  Manage OAuth credentials in the Vault

Options:
  -h, --help  Show this message and exit

Commands:
  purge   Remove Vault
  list    List configured OAuth2 credentials
  store   Store OAuth2 client credentials
  export  Export Vault to a file for backup or transfer.
  import  Import credentials from another Vault

vzd-cli admin status

Zeigt die Information über den aktuellen Zustand des Clients. Insb. wird angezeigt in welche Umgebungen man angemeldet ist, OAuth2 Token Informationen und die Informationen über Backend APIs.

vzd-cli admin status

vzd-cli admin <tu|ru|pu> login

Anmelden beim OAuth2 Server mit Client-Credentials aus dem Vault.

Beispiel: In alle drei Umgebungen einloggen (vorausgesetzt alle drei ClientIDs sind über vzd-cli admin vault hinterlegt)
vzd-cli admin tu login
vzd-cli admin ru login
vzd-cli admin pu login
Anmerkungen
 Im Gegensatz zu Vault und darin enthaltenen Client-Credentials, werden die zeitlich befristete ACCESS_TOKEN unverschlüsselt im Ordner $HOME/.telematik/ gespeichert. Die Tokens sind 6 Stunden gültig.

vzd-cli admin <tu|ru|pu> login-cred

Anmelden beim OAuth2 Server mit explizit angegeben Client-Credentials

Beispiel: Client-Id und Client-Secret werden über Parameter übergeben, Referenzumgebung (ru)
vzd-cli admin ru login-cred -c myclient -s mysecret
Beispiel: Client-Id wird über Parameter übergeben, Client-Secret wird aus der Umgebungsvariable CLIENT_SECRET ausgelesen, Referenzumgebung (ru)
export CLIENT_SECRET=mysecret
vzd-cli admin ru login-cred -c myclient

vzd-cli admin <tu|ru|pu> token

Zeigt oder setzt den ACCESS_TOKEN für die angegebene Umgebung.

Beispiel: Speichert den ACCESS_TOKEN in die Umgebungsvariable und führt anschließend eine Query mit curl.
vzd-cli admin ru login
export ADMIN_ACCESS_TOKEN=$(vzd-cli admin ru token)
curl -H "Accept: application/json" \
  -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  https://vzdpflege-ref.vzd.ti-dienste.de:9543/DirectoryEntries?baseEntryOnly=true
Beispiel: Setzt den ACCESS_TOKEN
vzd-cli admin ru token -s <ACCESS_TOKEN>

vzd-cli admin <tu|ru|pu> search

Führt eine benutzerfreundliche Suche nach Einträgen. Dabei werden Natural Language Processing Algorithmen verwenden um angegebene Suchkriterien zu ermitteln. Derzeit werden folgende Kriterien unterstützt:

  • Orte in Deutschland, z.B. Berlin, Bad Homburg, Frankfurt am Main

  • Deutsche Postleitzahlen

  • TelematikIDs

  • Betriebsstätten / IK-Nummer

Beispiele:
# Name und Ort
vzd-cli admin ru search Müller Berlin
# Ort und längerer Name
vzd-cli admin ru search Berlin Praxis Müller
# nur Name
vzd-cli admin ru search Praxis Müller
# Name und PLZ
vzd-cli admin ru search Praxis Müller 45144
# Erste Nummern der TelematikID (niedergelassene Arztpraxen)
vzd-cli admin ru search 1-20

vzd-cli admin <tu|ru|pu> show <telematikID>

Zeigt ausführliche Details zu dem Eintrag. Durch --ocsp Option kann die Online-Zertifikatsprüfung mittels OCSP-Responder eingefordert werden.

Beispiele
vzd-cli admin ru show 1-SMC-B-Testkarte-883110000102893
vzd-cli admin ru show 1-SMC-B-Testkarte-883110000102893 --ocsp

vzd-cli admin <tu|ru|pu> list

Suche und Anzeige von Verzeichnisdiensteinträgen durch eingabe einzelner Query-Parameter

Usage: vzd-cli admin ru list [OPTIONS]

  List directory entries

Query parameters:
  --name TEXT
  --uid TEXT
  --givenName TEXT
  --sn TEXT
  --cn TEXT
  --displayName TEXT
  --streetAddress TEXT
  --postalCode TEXT
  --countryCode TEXT
  --localityName TEXT
  --stateOrProvinceName TEXT
  --title TEXT
  --organization TEXT
  --otherName TEXT
  -t, --telematikID TEXT
  --specialization TEXT
  --domainID TEXT
  --holder TEXT
  --personalEntry [true|false]
  --dataFromAuthority [true|false]
  --professionOID TEXT
  --entryType INT
  --maxKOMLEadr INT
  --changeDateTimeFrom ISODATE
  --changeDateTimeTo ISODATE
  --baseEntryOnly [true|false]

OCSP options:
  --ocsp  Validate certificates using OCSP

Options:
  --human, --json, --yaml, --csv, --table
                                   (default: HUMAN)
  -f, --param-file PARAM FILENAME...
                                   Read parameter values from file
  -p, --param NAME=VALUE           Specify query parameters to find matching
                                   entries
  -o, --outfile PATH               Write output to file
  --sync                           use Sync mode
  -h, --help                       Show this message and exit

Optionen

  • --param-file oder -f
    Liest Werte eines Parameters aus der Datei und fragt für jeden Wert nach Eintrag im VZD ab. Die Datei soll den gewünschten Wert einmal pro Zeile enthalten:

Beispiel: Findet alle Einträge mit angegeben TelematikID
vzd-cli admin ru list -t 1-SMC-B-Testkarte-883110000102893
Beispiel: Findet alle Einträge aus Berlin, bei welchen die TelematikID mit 5- beginnt (Krankenhäuser).
vzd-cli admin ru list -t "5-*" --localityName Berlin
Beispiel: Findet alle Einträge mit TelematikID aus telematik.txt
vzd-cli admin ru list -f telematikID telematik.txt --table
Inhalt der telematik.txt
4-SMC-B-Testkarte-883110000093329
3-SMC-B-Testkarte-883110000093294
2-SMC-B-Testkarte-883110000093645
3-SMCB-Testkarte-883110000092193

vzd-cli admin <tu|ru|pu> template

Generiert die Dateivorlagen für Entry, BaseEntry und UserCertificate.

Beispiel: Erzeugt eine Vorlage und schreibt es in eine YAML-Datei
vzd-cli admin ru template base > Eintrag.yaml
Beispiel: Erzeugt eine Vorlage und schreibt es in eine JSON-Datei
vzd-cli admin template base --json > Eintrag.json

vzd-cli admin <tu|ru|pu> add-base

Neuen Verzeichnisdiensteintrag erstellen.

Beispiel: einen leeren Eintrag mit angegebenen telematikID erstellen:

vzd-cli admin ru add-base -s telematikID=9-TEST -s entryType=4

vzd-cli admin <tu|ru|pu> load-base

Lädt einen Basiseintrag. Die geladene Struktur kann als Datei gespeichert werden, in einem Text-Editor bearbeitet und anschließend mit vzd-cli admin modify-base modifiziert werden.

vzd-cli admin <tu|ru|pu> modify-base

Modifiziert den gesamten Basiseintrag im Verzeichnisdienst.

vzd-cli admin <tu|ru|pu> modify-base-attr

Modifiziert einzelne Attribute des Basiseintrags

vzd-cli admin <tu|ru|pu> delete

Löscht Einträge aus dem Verzeichnisdienst.

vzd-cli admin cert-info

Zeigt informationen aus Zertifikate (DER-Format) und führt OCSP-Abfragen durch.

vzd-cli admin cert-info cert1.der cert2.der --ocsp

vzd-cli admin <tu|ru|pu> list-cert

Suche und Anzeige von X509-Zertifikaten.

vzd-cli admin <tu|ru|pu> add-cert

Fügt einen neuen X509-Zertifikat zu existierenden Verzeichnisdiensteintrag hinzu.

# zuerst einen leeren Basiseintrag erzeugen
vzd-cli admin ru add-base -s telematikID=1-123123 -s entryType=1
# danach Zertifikat hinzufügen
# Achtung: TelematikID beim Befehl admin add-base und im Zertifikat müssen identisch sein
vzd-cli admin ru add-cert 1-123123.der
# Fügt alle Zertifikate aus dem aktuellen Ordner das VZD
# TelematikID und BasisEintrag werden automatisch aus dem Zertifikat
# ermittelt (Admission Statement -> Registration Number)
vzd-cli admin ru add-cert *.der

vzd-cli admin <tu|ru|pu> clear-cert

Löscht alle Zertifikate aus dem angegeben Eintrag.

vzd-cli admin ru clear-cert -t 1-123123

vzd-cli admin <tu|ru|pu> save-cert

Speichert alle gefundene Zertifikate in ein Verzeichnis

vzd-cli admin <tu|ru|pu> delete-cert

Warning
 Nicht implementiert. Bitte vzd-cli admin clear-cert verwenden.

Löscht einen X509-Zertifikat.

vzd-cli admin <tu|ru|pu> dump create

Lädt große Mengen von Einträgen und schreibt sie in STDOUT, eine Zeile per Eintrag als JSON. So erzeugte Dumps können durch weitere Tools verarbeitet werden, z.B. GnuPG oder FX.

vzd-cli admin <tu|ru|pu> dump ocsp

Liest die Einträge aus STDIN, stellt für jeden gefundenen Zertifikat eine OCSP-Abfrage.

Es gibt zwei Parameter für diesen Command:

# Setzt den delay zwischen Anfragen auf 500 Millisekunden
vzd-cli admin ru dump ocsp --delay 500

# Setzt die Anzahl an gleichzeitig Request versendenden Coroutines
vzd-cli admin ru dump ocsp --concurrency 5

Es sind auch beide Parameter gleichzeitig setzbar.

vzd-cli admin <tu|ru|pu> log

Zeigt die Änderungshistorie der Einträge im VZD. Die Änderungen können nach UID, TelematikID (inkl. Pattern) abgefragt werden sowie nach ClientID oder Operation. Zusätzlich können die Ergebnisse nach Zeitperiode gefiltert werden:

# zeigt alle Änderungen für die Einträge mit Prefix 9-
vzd-cli admin ru log -t "9-*"
# zeigt alle Änderungen für die Einträge mit Prefix 9-,
# die sich seit 1.02.2023 geändert haben
vzd-cli admin ru log -t "9-*" --logTimeFrom 2023-02-01T00:00:00Z

vzd-cli admin <tu|ru|pu> activate

Aktiviert den Eintrag in dem das Attribut active auf true gesetzt wird

vzd-cli admin ru activate -t "9-12345678"

vzd-cli admin <tu|ru|pu> deactivate

Deaktiviert den Eintrag in dem das Attribut active auf false gesetzt wird

vzd-cli admin ru deactivate -t "9-12345678"

vzd-cli apo: ApoVZD API

vzd-cli apo config

Konfiguration der ApoVZD Clients.

Beispiele
# aktuelle konfiguration anzeigen:
vzd-cli apo config get
# Api-Key für Testinstanz setzen:
vzd-cli apo config set apiKeys.test <Api-Key>
# Api-Key für Produktivinstanz setzen:
vzd-cli apo config set apiKeys.prod <Api-Key>

vzd-cli apo <test|prod> search

Beispeil: Suche nach allen Apotheken mit Namen Linden
vzd-cli apo prod search Linden

vzd-cli apo <test|prod> show

Beispeil: Zeige die Informationen über Apotheke mit angegebenen TelematikID
vzd-cli apo prod show 3-1234567890

vzd-cli gui: Directory GUI

Durch den Befehl vzd-cli gui wird ein HTTP Server gestartet und ein neuer Browser-Tab mit GUI geöffnet.

(Neu) vzd-cli fhir: FHIR Directory APIs

vzd-cli fhir <tu|ru|pu> fdv search

Suche nach Einträgen in der FHIR FDV Search API.

Beispiel: Suche nach Einträgen mit TelematikID
vzd-cli fhir pu fdv search hs -t 1-1234567890

vzd-cli fhir fdv-vault

Befehle zur Verwaltung von OAuth2 Geheimnissen für die FHIR FDV Search API. Aufbau ist analog zu vzd-cli admin vault.

vzd-cli fhir <tu|ru|pu> token

Lesen und Setzen eines ACCESS_TOKEN für die FHIR Search API.

# Setzen des ACCESS_TOKEN für Referenzumgebung (ru)
vzd-cli fhir ru token -s <ACCESS_TOKEN>
# Lesen des ACCESS_TOKEN für Referenzumgebung (ru)
vzd-cli fhir ru token

vzd-cli fhir <tu|ru|pu> search

Suche nach Einträgen in der FHIR Search API.

Beispiel: Suche nach Einträgen mit TelematikID
# Suche nach HealthcareService Einträgen
vzd-cli fhir ru search hs -t 1-2234567890
# Suche nach PractitionerRole Einträgen
vzd-cli fhir ru search pr -t 1-1234567890

License

Copyright 2022-2025 gematik GmbH

EUROPEAN UNION PUBLIC LICENCE v. 1.2

EUPL © the European Union 2007, 2016

See the LICENSE for the specific language governing permissions and limitations under the License

Additional Notes and Disclaimer from gematik GmbH

  1. Copyright notice: Each published work result is accompanied by an explicit statement of the license conditions for use. These are regularly typical conditions in connection with open source or free software. Programs described/provided/linked here are free software, unless otherwise stated.

  2. Permission notice: Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    1. The copyright notice (Item 1) and the permission notice (Item 2) shall be included in all copies or substantial portions of the Software.

    2. The software is provided "as is" without warranty of any kind, either express or implied, including, but not limited to, the warranties of fitness for a particular purpose, merchantability, and/or non-infringement. The authors or copyright holders shall not be liable in any manner whatsoever for any damages or other claims arising from, out of or in connection with the software or the use or other dealings with the software, whether in an action of contract, tort, or otherwise.

    3. The software is the result of research and development activities, therefore not necessarily quality assured and without the character of a liable product. For this reason, gematik does not provide any support or other user assistance (unless otherwise stated in individual cases and without justification of a legal obligation). Furthermore, there is no claim to further development and adaptation of the results to a more current state of the art.

  3. Gematik may remove published results temporarily or permanently from the place of publication at any time without prior notice or justification.

  4. Please note: Parts of this code may have been generated using AI-supported technology. Please take this into account, especially when troubleshooting, for security analyses and possible adjustments.

About

Tool for managing the Gematik Directory Service (VZD). The vzd-cli enables secure interactions with Directory Admin, Apo, and FHIR APIs via OAuth2, with options for configuration, search, entry management, and certificate handling.

Topics

app directory vzd

Resources

Readme

License

EUPL-1.2 license

Security policy

Security policy
Activity
Custom properties

Stars

5 stars

Watchers

6 watching

Forks

3 forks
Report repository

Releases 68

3.2.2 Latest
Nov 22, 2025
+ 67 releases

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages