Benutzerdefinierte Endpunkte in Azure Confidential Ledger

Benutzerdefinierte Endpunkte (USER Defined Endpoints, UDEs) ermöglichen die Ausführung von benutzerdefiniertem Code in derselben Trusted Execution Environment (TEE) wie das Hauptbuch. Dieses Feature erweitert die Vorteile der Vertraulichkeit und Integritätsgarantie auf den benutzerdefinierten Code. Außerdem unterstützt es benutzerdefinierte rollenbasierte Zugriffssteuerung (Role Based Access Control, RBAC) für die Autorisierung. UDEs wurden zuvor als erweiterte benutzerdefinierte Funktionen bezeichnet.

Hinweis

Verwenden Sie die REST-API-Version 2026-02-23 oder höher, um mit UDEs zu arbeiten.

Tipp

Für einfachere Szenarien, z. B. leichtgewichtige benutzerdefinierte Logik oder direkte Integration mit der Ledger-API, siehe benutzerdefinierte Funktionen in Azure Confidential Ledger.

Anwendungsfälle

Hier sind einige Szenarien, in denen benutzerdefinierte Endpunkte von Vorteil sein können:

  • Datenanalyse und Aggregation: Vertrauliche Informationen können im TEE verarbeitet und aggregierte Informationen an die Beteiligten weitergegeben werden.
  • Schutz vertraulicher Informationen: Vertrauliche Informationen wie personenbezogene Daten, Kredit-Score und Gesundheitsinformationen können nach der Beglaubigung mit anderen vertraulichen Arbeitslasten geteilt werden.

Voraussetzungen

In diesem Lernprogramm wird davon ausgegangen, dass Sie eine Ledger-Instanz erstellt haben. Sie können eine erstellen, indem Sie das Azure-Portal, die Azure CLI oder Azure PowerShell verwenden.

Entwickeln von Anwendungen

Ledger-Anwendungen werden mit TypeScript entwickelt und in ein JavaScript-Bundle eingeführt. Weitere Informationen zum Entwicklungsprozess finden Sie in der CCF-Dokumentation (Confidential Consortium Framework).

Von Bedeutung

Nur Administratorbenutzende können Anwendungen bereitstellen und benutzerdefinierte RBAC in Confidential Ledger verwalten. Im restlichen Abschnitt wird davon ausgegangen, dass ein Administrator die Befehle ausführt.

Wir verwenden die Banking-Anwendung, die im Azureconfidentialledger-App-Samples-Repository (https://github.com/microsoft/azureconfidentialledger-app-samples) verfügbar ist, um das Feature zu veranschaulichen.

Hinweis

Die Banking-Anwendung macht APIs für häufig verwendete Bankingszenarien wie Eröffnungskonten, Einlagen und Überweisungen mit benutzerdefinierten Rollen und Aktionen verfügbar.

Anmelden bei Azure

Hinweis

Das Azure-Vertrauungsbuch unterstützt Microsoft Entra ID von Haus aus. Wenn Ihre Anwendung mit anderen Identitätsanbietern integriert ist, wenden Sie sich an den Kundensupport, um sie im Ledger-System zu konfigurieren.

Rufen Sie ein Microsoft Entra-ID-Token ab.

az login --use-device-code
az account get-access-token --resource https://confidential-ledger.azure.com

Kopieren Sie den Rohtokenwert aus der Ausgabe.

Herunterladen der Ledger-Identität

Ein Hauptbuch wird durch ein Zertifikat, das als Dienstzertifikat bekannt ist, eindeutig identifiziert. Es wird verwendet, um eine sichere Verbindung zum Ledger herzustellen. Laden Sie ihn von einem bekannten Endpunkt herunter, und speichern Sie ihn auf servicer_cert.pem.

Hinweis

contoso ist der Name des Ledgers. Ersetzen Sie ihn durch den entsprechenden Ledgernamen.

curl https://identity.confidential-ledger.core.azure.com/ledgerIdentity/contoso --silent | jq ' .ledgerTlsCertificate' | xargs echo -e > service_cert.pem

Bereitstellen der Anwendung

Stellen Sie das JavaScript-Anwendungsbundle bereit, indem Sie den /app/userDefinedEndpoints-Endpunkt aufrufen.

apiVersion="2026-02-23"
content_type_application_json="Content-Type: application/json"
bundle="/path/to/bundle.json"
authorization="Authorization: Bearer raw_token_value"
server_identity="--cacert service_cert.pem"

# Deploy the application
#
curl $server_identity -X PUT "https://contoso.confidential-ledger.azure.com/app/userDefinedEndpoints?api-version=$apiVersion" -H "$content_type_application_json" -H "$authorization" -d @$bundle

# View the application
#
curl $server_identity "https://contoso.confidential-ledger.azure.com/app/userDefinedEndpoints?api-version=$apiVersion" -H "$authorization"

Hinweis

Benutzerdefinierte Endpunkte und Benutzerdefinierte Funktionen (UDFs) schließen sich gegenseitig aus. Sie können UDFs nicht erstellen oder ausführen, wenn UDEs definiert sind und umgekehrt. Um zwischen den beiden zu wechseln, befolgen Sie die Anweisungen beim Wechseln zwischen UDFs und UDEs.

Erstellen von Rollen und Benutzern

Die Bankanwendung verwendet zwei Personas, nämlich einen Vorgesetzten und einen Geldzähler. Wir erstellen Rollen und Benutzer, um sie darzustellen.

Hinweis

Jeder Benutzer wird durch ein eindeutiges Zertifikat dargestellt.

Hinweis

Anwendungsbenutzenden können die integrierten Rollen zugewiesen werden, nämlich Administrator, Mitwirkender und Leser. Bei benutzerdefinierten Rollen wird zwischen Groß- und Kleinschreibung unterschieden, und bei integrierten Rollen wird die Groß- und Kleinschreibung nicht beachtet. Einem Benutzenden können mehrere Rollen zugewiesen werden.

apiVersion="2026-02-23"
content_type_application_json="Content-Type: application/json"
content_type_merge_patch_json="Content-Type: application/merge-patch+json"
authorization="Authorization: Bearer raw_token_value"
curve="secp384r1"
server_identity="--cacert service_cert.pem"

# These actions must match (case-sensitive) the values defined in the application.
#
role_actions='{"roles":[{"role_name":"manager","role_actions":["/banking/accounts/post","/banking/accounts/put","/banking/accounts/get","/banking/accounts/patch"]},{"role_name":"teller","role_actions":["/banking/accounts/put","/banking/accounts/get","/banking/accounts/patch"]}]}'

# Create the roles.
#
curl $server_identity -X PUT "https://contoso.confidential-ledger.azure.com/app/roles?api-version=$apiVersion" -H "$content_type_application_json" -H "$authorization" -d $role_actions

# View the roles
#
curl $server_identity "https://contoso.confidential-ledger.azure.com/app/roles?api-version=$apiVersion" -H "$authorization"

# Create a certificate for the manager user.
#
openssl ecparam -out "manager_privk.pem" -name "$curve" -genkey
openssl req -new -key "manager_privk.pem" -x509 -nodes -days 365 -out "manager_cert.pem" -sha384 -subj=/CN="manager"
manager_cert_fingerprint=$(openssl x509 -in "manager_cert.pem" -noout -fingerprint -sha256 | cut -d "=" -f 2)
manager_user="{\"user_id\":\"$manager_cert_fingerprint\",\"assignedRoles\":[\"manager\"]}"

# Create a certificate for the teller user.
#
openssl ecparam -out "teller_privk.pem" -name "$curve" -genkey
openssl req -new -key "teller_privk.pem" -x509 -nodes -days 365 -out "teller_cert.pem" -sha384 -subj=/CN="teller"
teller_cert_fingerprint=$(openssl x509 -in "teller_cert.pem" -noout -fingerprint -sha256 | cut -d "=" -f 2)
teller_user="{\"user_id\":\"$teller_cert_fingerprint\",\"assignedRoles\":[\"teller\"]}"

# Create the manager user.
#
curl $server_identity -X PATCH "https://contoso.confidential-ledger.azure.com/app/ledgerUsers/$manager_cert_fingerprint?api-version=$apiVersion" -H "$content_type_merge_patch_json" -H "$authorization" -d $manager_user

# Create the teller user.
#
curl $server_identity -X PATCH "https://contoso.confidential-ledger.azure.com/app/ledgerUsers/$teller_cert_fingerprint?api-version=$apiVersion" -H "$content_type_merge_patch_json" -H "$authorization" -d $teller_user

# View the users
#
curl $server_identity "https://contoso.confidential-ledger.azure.com/app/ledgerUsers?api-version=$apiVersion" -H "$authorization"

Laufzeitkonfiguration aktualisieren (optional)

Aktualisieren Sie die JavaScript-Laufzeitkonfiguration durch Aufrufen des Endpunkts /app/userDefinedEndpoints/runtimeOptions .

Sie können die Optionen max_heap_bytes, max_stack_bytes, max_execution_time_ms und max_cached_interpreters festlegen. Das Ledger lehnt Anfragen mit Werten außerhalb der zulässigen Bereiche ab. Die zulässigen Werte finden Sie unter Azure Confidential Ledger-Grenzwerte. Um eine Option auf den Standardwert zurückzusetzen, legen Sie sie auf null.

Sie können log_exception_details und return_exception_details auch auf true oder false festlegen.

Im folgenden Beispiel wird die maximale Ausführungszeit auf 2.000 ms festgelegt.

apiVersion="2026-02-23"
content_type_merge_patch_json="Content-Type: application/merge-patch+json"
authorization="Authorization: Bearer raw_token_value"
runtime_options="{\"max_execution_time_ms\":2000}"
server_identity="--cacert service_cert.pem"

# Patch the runtime options
#
curl $server_identity -X PATCH "https://contoso.confidential-ledger.azure.com/app/userDefinedEndpoints/runtimeOptions?api-version=$apiVersion" -H "$content_type_merge_patch_json" -H "$authorization" -d $runtime_options

# View the runtime options
#
curl $server_identity "https://contoso.confidential-ledger.azure.com/app/userDefinedEndpoints/runtimeOptions?api-version=$apiVersion" -H "$authorization"

Jetzt können Sie die Anwendungsendpunkte aufrufen und Transaktionen übermitteln.

Bereinigen von Ressourcen

Andere Schnellstartanleitungen und Tutorials in dieser Sammlung bauen auf dieser Schnellstartanleitung auf. Wenn Sie planen, mit weiteren Schnellstartanleitungen und Tutorials fortzufahren, möchten Sie diese Ressourcen vielleicht an Ort und Stelle belassen.

Wenn Sie die Ressourcen nicht mehr benötigen, führen Sie den Azure CLI-Befehl az group delete aus, um die Ressourcengruppe und alle dazugehörigen Ressourcen zu löschen:

az group delete --name "myResourceGroup"

Nächste Schritte

In diesem Tutorial haben Sie eine benutzerdefinierte JavaScript-Anwendung in einer Confidential Ledger-Instanz bereitgestellt. Weitere Informationen zum vertraulichen Hauptbuch von Azure und zur Integration in Ihre Anwendungen finden Sie in den folgenden Artikeln: