Endpoint definiti dall'utente in Azure confidential ledger

Gli endpoint definiti dall'utente consentono l'esecuzione di codice personalizzato nello stesso ambiente di esecuzione attendibile (TEE) del ledger. Questa funzionalità estende i vantaggi della riservatezza e dell'integrità garantiti al codice personalizzato. Supporta anche il controllo degli accessi in base al ruolo personalizzato per l'autorizzazione. Gli UDE erano precedentemente chiamati funzioni avanzate definite dall'utente.

Casi d'uso

Ecco alcuni scenari in cui gli endpoint definiti dall'utente possono essere utili:

• Analisi e aggregazione dei dati: le informazioni riservate possono essere elaborate nell'ambiente tee e le informazioni aggregate possono essere condivise con gli stakeholder.
• Protezione delle informazioni riservate: informazioni riservate come dati personali, punteggio di credito e informazioni sull'integrità possono essere condivise con altri carichi di lavoro riservati dopo l'attestazione.

Prerequisiti

• Interfaccia della riga di comando di Azure o Azure PowerShell.

• Proprietario della sottoscrizione: un registro riservato può essere creato solo dagli utenti con autorizzazioni Owner per la sottoscrizione di Azure. Verificare di avere l'accesso appropriato prima di continuare con questo avvio rapido.

Questa guida presuppone che sia stata creata un'istanza del libro mastro. È possibile crearne uno usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell.

Sviluppo di applicazioni

Le applicazioni libro mastro vengono sviluppate usando TypeScript e inserite in un bundle JavaScript. Per altre informazioni sul processo di sviluppo, vedere la documentazione di Confidential Consortium Framework (CCF).

L'applicazione bancaria disponibile nel repository azureconfidentialledger-app-samples (https://github.com/microsoft/azureconfidentialledger-app-samples) viene usata per illustrare la funzionalità.

Accedere ad Azure

Ottenere un token ID Microsoft Entra.

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

Connect-AzAccount
Set-AzContext -Subscription subscriptionid
Get-AzAccessToken -ResourceUrl "https://confidential-ledger.azure.com"

Copiare il valore grezzo del token dall'output.

Scaricare l'identità del libro mastro

Un libro mastro viene identificato in modo univoco da un certificato denominato certificato di servizio. Viene usato per stabilire una connessione sicura al registro. Scaricarlo da un endpoint noto e salvarlo in servicer_cert.pem.

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

Distribuire l'applicazione

Distribuire il bundle dell'applicazione JavaScript richiamando l'endpoint /app/userDefinedEndpoints.

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"

Creare ruoli e utenti

L'applicazione bancaria usa due persone, vale a dire un manager e un teller. Creiamo ruoli e utenti per rappresentarli.

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"

Aggiornare la configurazione del runtime (facoltativo)

Aggiornare la configurazione del runtime JavaScript chiamando l'endpoint /app/userDefinedEndpoints/runtimeOptions .

È possibile impostare le opzioni max_heap_bytes, max_stack_bytes, max_execution_time_ms e max_cached_interpreters. Il libro mastro rifiuta le richieste con valori esterni agli intervalli consentiti. Per i valori consentiti, vedere limiti di Azure Confidential Ledger. Per reimpostare un'opzione sul valore predefinito, impostarla su null.

È anche possibile impostare log_exception_details e return_exception_details su true o false.

Nell'esempio seguente viene impostato il tempo di esecuzione massimo su 2.000 ms.

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"

A questo punto è possibile chiamare gli endpoint dell'applicazione e inviare le transazioni.

Pulire le risorse

Altri avvii rapidi ed esercitazioni in questa raccolta si basano su questo avvio rapido. Se prevedi di continuare a lavorare con le guide introduttive e i tutorial successivi, potresti voler lasciare queste risorse intatte.

Quando non sono più necessari, è possibile rimuovere il gruppo di risorse e tutte le risorse correlate tramite il comando az group delete dell'interfaccia della riga di comando di Azure:

az group delete --name "myResourceGroup"

Passaggi successivi

In questa esercitazione è stata distribuita un'applicazione JavaScript personalizzata in un'istanza del libro mastro riservato. Per altre informazioni sul libro mastro riservato di Azure e su come integrarlo con le applicazioni, continuare con questi articoli:

• Programmazione lato server in Azure Confidential Ledger
• Funzioni definite dall'utente nel libro mastro riservato di Azure
• Panoramica del libro mastro riservato di Microsoft Azure