使用 AzCopy 和 Azure Active Directory (Azure AD) 授予对 blob 的访问权限Authorize access to blobs with AzCopy and Azure Active Directory (Azure AD)

你可以通过使用 Azure AD 来向 AzCopy 提供授权凭据。You can provide AzCopy with authorization credentials by using Azure AD. 这样就无需为每个命令都追加共享访问签名 (SAS) 令牌。That way, you won't have to append a shared access signature (SAS) token to each command.

首先请验证你的角色分配。Start by verifying your role assignments. 然后,选择要授权的 安全主体 类型。Then, choose what type of security principal you want to authorize. 用户标识托管标识服务主体,每一种都是安全主体类型。A user identity, a managed identity, and a service principal are each a type of security principal.

用户标识是在 Azure AD 中具有标识的任何用户。A user identity is any user that has an identity in Azure AD. 这是最易于授权的安全主体。It's the easiest security principal to authorize. 如果你计划在以无用户交互方式运行的脚本中使用 AzCopy,那么托管标识和服务主体会是非常有用的选项。Managed identities and service principals are great options if you plan to use AzCopy inside of a script that runs without user interaction. 托管标识更适合从 Azure 虚拟机 (VM) 运行的脚本,服务主体则更适合在本地运行的脚本。A managed identity is better suited for scripts that run from an Azure Virtual Machine (VM), and a service principal is better suited for scripts that run on-premises.

有关 AzCopy 的详细信息,请参阅 AzCopy 入门For more information about AzCopy, Get started with AzCopy.

验证角色分配Verify role assignments

所需的授权级别取决于是要上传文件,还是只下载文件。The level of authorization that you need is based on whether you plan to upload files or just download them.

如果你只是想下载文件,请验证是否已将存储 Blob 数据读取者角色分配到你的用户标识、托管标识或服务主体。If you just want to download files, then verify that the Storage Blob Data Reader role has been assigned to your user identity, managed identity, or service principal.

若要上传文件,请验证是否已将以下角色之一分配到了你的安全主体:If you want to upload files, then verify that one of these roles has been assigned to your security principal:

可在以下任何范围内将这些角色分配到安全主体:These roles can be assigned to your security principal in any of these scopes:

  • 容器(文件系统)Container (file system)
  • 存储帐户Storage account
  • 资源组Resource group
  • 订阅Subscription

若要了解如何验证和分配角色,请参阅使用 Azure 门户分配用于访问 Blob 和队列数据的 Azure 角色To learn how to verify and assign roles, see Use the Azure portal to assign an Azure role for access to blob and queue data.

备注

请记住,Azure 角色分配可能需要最多五分钟的时间进行传播。Keep in mind that Azure role assignments can take up to five minutes to propagate.

如果安全主体已添加到目标容器或目录的访问控制列表 (ACL),则无需将这些角色之一分配到安全主体。You don't need to have one of these roles assigned to your security principal if your security principal is added to the access control list (ACL) of the target container or directory. 在 ACL 中,安全主体需要对目标目录拥有写入权限,并对容器和每个父目录拥有执行权限。In the ACL, your security principal needs write permission on the target directory, and execute permission on container and each parent directory.

有关详细信息,请参阅 Azure Data Lake Storage Gen2 中的访问控制模型To learn more, see Access control model in Azure Data Lake Storage Gen2.

授权用户标识Authorize a user identity

验证你的用户标识已获得所需的授权级别后,打开命令提示符,然后键入以下命令并按 ENTER 键。After you've verified that your user identity has been given the necessary authorization level, open a command prompt, type the following command, and then press the ENTER key.

azcopy login --aad-endpoint https://login.partner.microsoftonline.cn

如果收到错误,请尝试包括存储帐户所属组织的租户 ID。If you receive an error, try including the tenant ID of the organization to which the storage account belongs.

azcopy login --tenant-id=<tenant-id> --aad-endpoint https://login.partner.microsoftonline.cn

请将 <tenant-id> 占位符替换为存储帐户所属组织的租户 ID。Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. 若要查找租户 ID,请在 Azure 门户中选择“Azure Active Directory”>“属性”>“目录 ID”。To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

此命令返回身份验证代码和网站的 URL。This command returns an authentication code and the URL of a website. 打开网站,提供代码,然后选择“下一步”按钮。Open the website, provide the code, and then choose the Next button.

创建容器

此时会出现登录窗口。A sign-in window will appear. 在该窗口中,使用 Azure 帐户凭据登录到 Azure 帐户。In that window, sign into your Azure account by using your Azure account credentials. 成功登录后,可以关闭浏览器窗口,开始使用 AzCopy。After you've successfully signed in, you can close the browser window and begin using AzCopy.

授权托管标识Authorize a managed identity

如果你打算在无需用户交互即可运行的脚本以及从 Azure 虚拟机 (VM) 运行的脚本中使用 AzCopy,此选项非常有用。This is a great option if you plan to use AzCopy inside of a script that runs without user interaction, and the script runs from an Azure Virtual Machine (VM). 使用此选项时,无需在 VM 上存储任何凭据。When using this option, you won't have to store any credentials on the VM.

通过使用已在 VM 上启用的系统范围的托管标识,或者通过使用已分配到 VM 的用户分配托管标识的客户端 ID、对象 ID 或资源 ID,可以登录到帐户。You can sign into your account by using a system-wide managed identity that you've enabled on your VM, or by using the client ID, Object ID, or Resource ID of a user-assigned managed identity that you've assigned to your VM.

若要详细了解如何启用系统范围的托管标识或创建用户分配的托管标识,请参阅使用 Azure 门户为 VM 上的 Azure 资源配置托管标识To learn more about how to enable a system-wide managed identity or create a user-assigned managed identity, see Configure managed identities for Azure resources on a VM using the Azure portal.

通过使用系统范围的托管标识来授权Authorize by using a system-wide managed identity

首先,确保已在 VM 上启用系统范围的托管标识。First, make sure that you've enabled a system-wide managed identity on your VM. 请参阅系统分配的托管标识See System-assigned managed identity.

然后,在命令控制台中,键入以下命令并按 ENTER 键。Then, in your command console, type the following command, and then press the ENTER key.

azcopy login --identity --aad-endpoint https://login.partner.microsoftonline.cn

通过使用用户分配的托管标识来授权Authorize by using a user-assigned managed identity

首先,确保已在 VM 上启用用户分配的托管标识。First, make sure that you've enabled a user-assigned managed identity on your VM. 请参阅用户分配的托管标识See User-assigned managed identity.

然后,在命令控制台中,键入以下任意命令并按 ENTER 键。Then, in your command console, type any of the following commands, and then press the ENTER key.

azcopy login --identity --identity-client-id "<client-id>" --aad-endpoint https://login.partner.microsoftonline.cn

请将 <client-id> 占位符替换为用户分配的托管标识的客户端 ID。Replace the <client-id> placeholder with the client ID of the user-assigned managed identity.

azcopy login --identity --identity-object-id "<object-id>" --aad-endpoint https://login.partner.microsoftonline.cn

请将 <object-id> 占位符替换为用户分配的托管标识的对象 ID。Replace the <object-id> placeholder with the object ID of the user-assigned managed identity.

azcopy login --identity --identity-resource-id "<resource-id>" --aad-endpoint https://login.partner.microsoftonline.cn

请将 <resource-id> 占位符替换为用户分配的托管标识的资源 ID。Replace the <resource-id> placeholder with the resource ID of the user-assigned managed identity.

授权服务主体Authorize a service principal

如果你打算在无需用户交互即可运行(尤其是在本地运行)的脚本中使用 AzCopy,此选项非常有用。This is a great option if you plan to use AzCopy inside of a script that runs without user interaction, particularly when running on-premises. 如果你打算在 Azure 中运行的 VM 上运行 AzCopy,则最好是使用托管服务标识,因为它更易于管理。If you plan to run AzCopy on VMs that run in Azure, a managed service identity is easier to administer. 有关详细信息,请参阅本文的授权托管标识部分。To learn more, see the Authorize a managed identity section of this article.

在运行脚本之前,必须至少以交互方式登录一次,以便能够向 AzCopy 提供服务主体凭据。Before you run a script, you have to sign in interactively at least one time so that you can provide AzCopy with the credentials of your service principal. 这些凭据存储在受保护的已加密文件中,因此,脚本无需提供敏感信息。Those credentials are stored in a secured and encrypted file so that your script doesn't have to provide that sensitive information.

可以使用客户端机密或使用与服务主体应用注册关联的证书的密码登录到帐户。You can sign into your account by using a client secret or by using the password of a certificate that is associated with your service principal's app registration.

若要详细了解如何创建服务主体,请参阅如何:使用门户创建可访问资源的 Azure AD 应用程序和服务主体To learn more about creating service principal, see How to: Use the portal to create an Azure AD application and service principal that can access resources.

若要了解有关服务主体的一般性详细信息,请参阅 Azure Active Directory 中的应用程序和服务主体对象To learn more about service principals in general, see Application and service principal objects in Azure Active Directory

通过使用客户端密码来授权服务主体Authorize a service principal by using a client secret

首先将 AZCOPY_SPA_CLIENT_SECRET 环境变量设置为服务主体应用注册的客户端机密。Start by setting the AZCOPY_SPA_CLIENT_SECRET environment variable to the client secret of your service principal's app registration.

备注

确保在命令提示符下设置此值,而不要在操作系统的环境变量设置中进行设置。Make sure to set this value from your command prompt, and not in the environment variable settings of your operating system. 这样,该值就只能在当前会话中使用。That way, the value is available only to the current session.

本示例演示如何在 PowerShell 中执行此操作。This example shows how you could do this in PowerShell.

$env:AZCOPY_SPA_CLIENT_SECRET="$(Read-Host -prompt "Enter key")"

备注

考虑使用本示例中所示的提示符。Consider using a prompt as shown in this example. 这样,密码就不会显示在控制台的命令历史记录中。That way, your password won't appear in your console's command history.

接下来键入以下命令,然后按 ENTER 键。Next, type the following command, and then press the ENTER key.

azcopy login --service-principal  --application-id application-id --tenant-id=tenant-id --aad-endpoint https://login.partner.microsoftonline.cn

请将 <application-id> 占位符替换为服务主体应用注册的应用程序 ID。Replace the <application-id> placeholder with the application ID of your service principal's app registration. 请将 <tenant-id> 占位符替换为存储帐户所属组织的租户 ID。Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. 若要查找租户 ID,请在 Azure 门户中选择“Azure Active Directory”>“属性”>“目录 ID”。To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

通过使用证书来授权服务主体Authorize a service principal by using a certificate

如果希望使用自己的凭据进行授权,可将证书上传到应用注册,然后使用该证书来登录。If you prefer to use your own credentials for authorization, you can upload a certificate to your app registration, and then use that certificate to log in.

除了将证书上传到应用注册以外,还需要在运行 AzCopy 的计算机或 VM 中保存该证书的副本。In addition to uploading your certificate to your app registration, you'll also need to have a copy of the certificate saved to the machine or VM where AzCopy will be running. 此证书副本应采用 .PFX 或 .PEM 格式,且必须包含私钥。This copy of the certificate should be in .PFX or .PEM format, and must include the private key. 该私钥应通过密码予以保护。The private key should be password-protected. 如果使用的是 Windows,且证书仅在证书存储中,请确保将该证书导出到 PFX 文件(包括私钥)。If you're using Windows, and your certificate exists only in a certificate store, make sure to export that certificate to a PFX file (including the private key). 有关指导,请参阅 Export-PfxCertificateFor guidance, see Export-PfxCertificate

接下来,将 AZCOPY_SPA_CERT_PASSWORD 环境变量设为证书密码。Next, set the AZCOPY_SPA_CERT_PASSWORD environment variable to the certificate password.

备注

确保在命令提示符下设置此值,而不要在操作系统的环境变量设置中进行设置。Make sure to set this value from your command prompt, and not in the environment variable settings of your operating system. 这样,该值就只能在当前会话中使用。That way, the value is available only to the current session.

本示例演示如何在 PowerShell 中执行此任务。This example shows how you could do this task in PowerShell.

$env:AZCOPY_SPA_CERT_PASSWORD="$(Read-Host -prompt "Enter key")"

接下来键入以下命令,然后按 ENTER 键。Next, type the following command, and then press the ENTER key.

azcopy login --service-principal --certificate-path <path-to-certificate-file> --tenant-id=<tenant-id> --aad-endpoint https://login.partner.microsoftonline.cn

请将 <path-to-certificate-file> 占位符替换为证书文件的相对路径或完全限定的路径。Replace the <path-to-certificate-file> placeholder with the relative or fully qualified path to the certificate file. AzCopy 将保存此证书的路径,但并不会保存此证书的副本,因此,请务必将此证书放在原有位置。AzCopy saves the path to this certificate but it doesn't save a copy of the certificate, so make sure to keep that certificate in place. 请将 <tenant-id> 占位符替换为存储帐户所属组织的租户 ID。Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. 若要查找租户 ID,请在 Azure 门户中选择“Azure Active Directory”>“属性”>“目录 ID”。To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

备注

考虑使用本示例中所示的提示符。Consider using a prompt as shown in this example. 这样,密码就不会显示在控制台的命令历史记录中。That way, your password won't appear in your console's command history.

不使用机密存储授权Authorize without a secret store

azcopy login 命令检索 OAuth 令牌,然后将该令牌放入系统上的机密存储。The azcopy login command retrieves an OAuth token and then places that token into a secret store on your system. 如果操作系统没有机密存储(如 Linux keyring),则 azcopy login 命令将不起作用,因为没有地方可以放置令牌。If your operating system doesn't have a secret store such as a Linux keyring, the azcopy login command won't work because there is nowhere to place the token.

可以设置内存中环境变量来代替使用 azcopy login 命令。Instead of using the azcopy login command, you can set in-memory environment variables. 然后运行任何 AzCopy 命令。Then run any AzCopy command. AzCopy 将检索完成操作所需的 Auth 令牌。AzCopy will retrieve the Auth token required to complete the operation. 操作完成后,令牌将从内存中消失。After the operation completes, the token disappears from memory.

授权用户标识Authorize a user identity

验证你的用户标识已获得所需的授权级别后,键入以下命令并按 Enter。After you've verified that your user identity has been given the necessary authorization level, type the following command, and then press the ENTER key.

export AZCOPY_AUTO_LOGIN_TYPE=DEVICE

然后,运行任何 azcopy 命令(例如 azcopy list https://contoso.blob.core.chinacloudapi.cn)。Then, run any azcopy command (For example: azcopy list https://contoso.blob.core.chinacloudapi.cn).

此命令返回身份验证代码和网站的 URL。This command returns an authentication code and the URL of a website. 打开网站,提供代码,然后选择“下一步”按钮。Open the website, provide the code, and then choose the Next button.

创建容器

此时会出现登录窗口。A sign-in window will appear. 在该窗口中,使用 Azure 帐户凭据登录到 Azure 帐户。In that window, sign into your Azure account by using your Azure account credentials. 成功登录后,操作即可完成。After you've successfully signed in, the operation can complete.

通过使用系统范围的托管标识来授权Authorize by using a system-wide managed identity

首先,确保已在 VM 上启用系统范围的托管标识。First, make sure that you've enabled a system-wide managed identity on your VM. 请参阅系统分配的托管标识See System-assigned managed identity.

键入以下命令,然后按 Enter。Type the following command, and then press the ENTER key.

export AZCOPY_AUTO_LOGIN_TYPE=MSI

然后,运行任何 azcopy 命令(例如 azcopy list https://contoso.blob.core.chinacloudapi.cn)。Then, run any azcopy command (For example: azcopy list https://contoso.blob.core.chinacloudapi.cn).

通过使用用户分配的托管标识来授权Authorize by using a user-assigned managed identity

首先,确保已在 VM 上启用用户分配的托管标识。First, make sure that you've enabled a user-assigned managed identity on your VM. 请参阅用户分配的托管标识See User-assigned managed identity.

键入以下命令,然后按 Enter。Type the following command, and then press the ENTER key.

export AZCOPY_AUTO_LOGIN_TYPE=MSI

然后,键入以下任何命令并按 Enter。Then, type any of the following commands, and then press the ENTER key.

export AZCOPY_MSI_CLIENT_ID=<client-id>

请将 <client-id> 占位符替换为用户分配的托管标识的客户端 ID。Replace the <client-id> placeholder with the client ID of the user-assigned managed identity.

export AZCOPY_MSI_OBJECT_ID=<object-id>

请将 <object-id> 占位符替换为用户分配的托管标识的对象 ID。Replace the <object-id> placeholder with the object ID of the user-assigned managed identity.

export AZCOPY_MSI_RESOURCE_STRING=<resource-id>

请将 <resource-id> 占位符替换为用户分配的托管标识的资源 ID。Replace the <resource-id> placeholder with the resource ID of the user-assigned managed identity.

设置这些变量后,可以运行任何 azcopy 命令(例如 azcopy list https://contoso.blob.core.chinacloudapi.cn)。After you set these variables, you can run any azcopy command (For example: azcopy list https://contoso.blob.core.chinacloudapi.cn).

授权服务主体Authorize a service principal

可以使用客户端机密或使用与服务主体应用注册关联的证书的密码登录到帐户。You can sign into your account by using a client secret or by using the password of a certificate that is associated with your service principal's app registration.

通过使用客户端密码来授权服务主体Authorize a service principal by using a client secret

键入以下命令,然后按 Enter。Type the following command, and then press the ENTER key.

export AZCOPY_AUTO_LOGIN_TYPE=SPN
export AZCOPY_SPA_APPLICATION_ID=<application-id>
export AZCOPY_SPA_CLIENT_SECRET=<client-secret>

请将 <application-id> 占位符替换为服务主体应用注册的应用程序 ID。Replace the <application-id> placeholder with the application ID of your service principal's app registration. <client-secret> 占位符替换为客户端机密。Replace the <client-secret> placeholder with the client secret.

备注

考虑使用提示从用户处收集密码。Consider using a prompt to collect the password from the user. 这样,密码就不会显示在命令历史记录中。That way, your password won't appear in your command history.

然后,运行任何 azcopy 命令(例如 azcopy list https://contoso.blob.core.chinacloudapi.cn)。Then, run any azcopy command (For example: azcopy list https://contoso.blob.core.chinacloudapi.cn).

通过使用证书来授权服务主体Authorize a service principal by using a certificate

如果希望使用自己的凭据进行授权,可将证书上传到应用注册,然后使用该证书来登录。If you prefer to use your own credentials for authorization, you can upload a certificate to your app registration, and then use that certificate to log in.

除了将证书上传到应用注册以外,还需要在运行 AzCopy 的计算机或 VM 中保存该证书的副本。In addition to uploading your certificate to your app registration, you'll also need to have a copy of the certificate saved to the machine or VM where AzCopy will be running. 此证书副本应采用 .PFX 或 .PEM 格式,且必须包含私钥。This copy of the certificate should be in .PFX or .PEM format, and must include the private key. 该私钥应通过密码予以保护。The private key should be password-protected.

键入以下命令,然后按 Enter。Type the following command, and then press the ENTER key.

export AZCOPY_AUTO_LOGIN_TYPE=SPN
export AZCOPY_SPA_CERT_PATH=<path-to-certificate-file>
export AZCOPY_SPA_CERT_PASSWORD=<certificate-password>

请将 <path-to-certificate-file> 占位符替换为证书文件的相对路径或完全限定的路径。Replace the <path-to-certificate-file> placeholder with the relative or fully qualified path to the certificate file. AzCopy 将保存此证书的路径,但并不会保存此证书的副本,因此,请务必将此证书放在原有位置。AzCopy saves the path to this certificate but it doesn't save a copy of the certificate, so make sure to keep that certificate in place. <certificate-password> 占位符替换为证书的密码。Replace the <certificate-password> placeholder with the password of the certificate.

备注

考虑使用提示从用户处收集密码。Consider using a prompt to collect the password from the user. 这样,密码就不会显示在命令历史记录中。That way, your password won't appear in your command history.

然后,运行任何 azcopy 命令(例如 azcopy list https://contoso.blob.core.chinacloudapi.cn)。Then, run any azcopy command (For example: azcopy list https://contoso.blob.core.chinacloudapi.cn).

后续步骤Next steps