Azure 机密账本中的高级用户定义函数（预览版）

高级用户定义函数（UDF）允许自定义代码与账本相同的受信任执行环境（TEE）中执行。 此功能将保密性和完整性保证的优势扩展到自定义代码。 此外，它还支持通过自定义的基于角色的访问控制（RBAC）来进行授权。

重要

用户定义函数目前在 API 版本下处于预览状态 2024-08-22-preview。 可以通过 此注册表单请求对此预览版的访问权限。 有关适用于 Beta 版、预览版或尚未正式发布的 Azure 功能的法律条款，请参阅 适用于 Microsoft azure 预览版的补充使用条款 。

小窍门

对于更简单的方案（例如轻型自定义逻辑或与账本 API 的直接集成），请参阅 Azure 机密账本中的简单用户定义的函数。

用例

下面是一些高级用户定义函数可能有益的情境：

• 数据分析和聚合：敏感信息可以在 TEE 中处理，聚合信息可以与利益干系人共享。
• 保护机密信息：证明后，可以与其他机密工作负荷共享机密信息，如个人数据、信用评分和健康信息。

先决条件

• Azure CLI 或 Azure PowerShell。

• 订阅所有者 - 只有在 Azure 订阅上具有所有者权限的用户才能创建机密账本。 在继续此快速入门之前，请先确认你具有适当的访问权限。

本教程假定你创建了一个账本实例。 可以使用 Azure 门户、 Azure CLI 或 Azure PowerShell 创建一个。

开发应用程序

账本应用程序是使用 TypeScript 开发的，并汇总到 JavaScript 捆绑包中。 若要详细了解开发过程，请参阅机密联盟框架 (CCF) 文档。

重要

只有管理员才能在账本中部署应用程序和管理自定义 RBAC。 本部分的其余部分假定管理员执行命令。

我们使用 azureconfidentialledger-app-samples 存储库（https://github.com/microsoft/azureconfidentialledger-app-samples）中提供的银行应用程序来演示该功能。

注释

银行应用程序公开了常用的银行场景的 API，例如开户、存款和转账使用自定义角色和操作。

登录到 Azure

注释

Azure 机密账本开箱即用支持 Microsoft Entra ID。 如果应用程序与其他标识提供者集成，请联系客户支持，在账本中对其进行配置。

获取Microsoft Entra ID 令牌。

CLI

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

PowerShell

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

从输出复制原始令牌值。

下载账本标识

账本通过名为服务证书的证书进行唯一标识。 它用于建立与账本的安全连接。 从已知终结点下载它并将其保存到 servicer_cert.pem。

注释

contoso 是账本的名称。 将其替换为相应的账本名称。

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

部署应用程序

通过调用 /app/userDefinedEndpoints 终结点来部署 JavaScript 应用程序捆绑包。

apiVersion="2024-08-22-preview"
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"

注释

高级用户定义的函数和 简单的用户定义的函数 是互斥的功能。 如果定义了高级 UDF，则无法创建或运行简单的 UDF，反之亦然。 若要在两者之间切换，请按照 UDF 概述页中的说明作。

创建角色和用户

银行应用程序使用两种角色，即 经理 和 柜员。 我们将创建角色和用户来表示它们。

注释

每个用户都由唯一的证书表示。

注释

可以为应用程序用户分配内置角色，即“管理员”、“参与者”和“读者”。 自定义角色区分大小写，但内置角色不区分大小写。 可以向用户分配多个角色。

apiVersion="2024-08-22-preview"
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"

更新运行时配置（可选）

可以通过调用 /app/userDefinedEndpoints/runTimeOptions 终结点来更新 JavaScript 运行时配置。 为了演示，让我们将最大执行时间设置为 2,000 毫秒。

apiVersion="2024-08-22-preview"
content_type_merge_patch_json="Content-Type: application/merge-patch+json"
authorization="Authorization: Bearer raw_token_value"
runtime_options="{\"max_heap_bytes\":1024,\"max_stack_bytes\":1024,\"max_execution_time_ms\":2000,\"log_exception_details\":false,\"return_exception_details\":false,\"max_cached_interpreters\":1024}"
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"

现在，你已准备好调用应用程序终结点并提交事务。

清理资源

本系列中的其他快速入门和教程是在本快速入门的基础上制作的。 如果打算继续使用后续的快速入门和教程，则可能需要保留这些资源。

如果不再需要资源组和所有相关的资源，可以使用 Azure CLI az group delete 命令将其删除：

az group delete --name "myResourceGroup"

后续步骤

在本教程中，你将自定义 JavaScript 应用程序部署到了机密账本实例中。 若要详细了解 Azure 机密账本以及如何将其与应用程序集成，请继续阅读以下文章：

• Azure 机密账本中的用户定义的函数概述
• Azure 机密账本中的简单用户定义函数
• Microsoft Azure 机密账本概述