Quickstart: Set up Azure Attestation with Azure PowerShell
Follow the below steps to create and configure an attestation provider using Azure PowerShell. See Overview of Azure PowerShell for information on how to install and run Azure PowerShell.
Note
The Az.Attestation PowerShell module is now integrated into Az PowerShell module. Minimum version of Az module required to support attestation operations:
- Az PowerShell module 6.5.0
The PowerShell Gallery has deprecated Transport Layer Security (TLS) versions 1.0 and 1.1. TLS 1.2 or a later version is recommended. Hence you may receive the following errors:
- WARNING: Unable to resolve package source 'https://www.powershellgallery.com/api/v2'
- PackageManagement\Install-Package: No match was found for the specified search criteria and module name
To continue to interact with the PowerShell Gallery, run the following command before the Install-Module commands
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Sign in to Azure
Sign in to Azure in PowerShell console (without elevated access privileges).
Connect-AzAccount
If needed, switch to the subscription to be used for Azure Attestation.
Set-AzContext -Subscription <subscription id>
Register Microsoft.Attestation resource provider
Register the Microsoft.Attestation resource provider in subscription. For more information about Azure resource providers and how to configure and manage resources providers, see Azure resource providers and types. Registering a resource provider is required only once for a subscription.
Register-AzResourceProvider -ProviderNamespace Microsoft.Attestation
Regional availability of Azure Attestation
(Get-AzResourceProvider -ProviderNamespace Microsoft.Attestation)[0].Locations
Create an Azure resource group
Create a resource group for the attestation provider. Other Azure resources (including a virtual machine with client application instance) can be put in the same resource group.
$location = "uksouth"
$attestationResourceGroup = "<attestation provider resource group name>"
New-AzResourceGroup -Name $attestationResourceGroup -Location $location
Note
Once an attestation provider is created in this resource group, a Microsoft Entra user must have Attestation Contributor role on the provider to perform operations like policy configuration/ policy signer certificates management. These permissions can also be inherited with roles such as Owner (wildcard permissions)/ Contributor (wildcard permissions) on the subscription/ resource group.
Create and manage an attestation provider
New-AzAttestation creates an attestation provider.
$attestationProvider = "<attestation provider name>"
New-AzAttestationProvider -Name $attestationProvider -ResourceGroupName $attestationResourceGroup -Location $location
PolicySignerCertificateFile is a file specifying a set of trusted signing keys. If a filename is specified for the PolicySignerCertificateFile parameter, attestation provider can be configured only with policies in signed JWT format. Else policy can be configured in text or an unsigned JWT format.
New-AzAttestationProvider -Name $attestationProvider -ResourceGroupName $attestationResourceGroup -Location $location -PolicySignersCertificateFile "C:\test\policySignersCertificates.pem"
For PolicySignersCertificateFile sample, see examples of policy signer certificate.
Get-AzAttestation retrieves the attestation provider properties like status and AttestURI. Take a note of AttestURI, as it will be needed later.
Get-AzAttestationProvider -Name $attestationProvider -ResourceGroupName $attestationResourceGroup
The above command should produce output in this format:
Id:/subscriptions/MySubscriptionID/resourceGroups/MyResourceGroup/providers/Microsoft.Attestation/attestationProviders/MyAttestationProvider
Location: MyLocation
ResourceGroupName: MyResourceGroup
Name: MyAttestationProvider
Status: Ready
TrustModel: AAD
AttestUri: https://MyAttestationProvider.us.attest.azure.net
Tags:
TagsTable:
Attestation providers can be deleted using the Remove-AzAttestation cmdlet.
Remove-AzAttestationProvider -Name $attestationProvider -ResourceGroupName $attestationResourceGroup
Policy management
In order to manage policies, a Microsoft Entra user requires the following permissions for "Actions":
- Microsoft.Attestation/attestationProviders/attestation/read
- Microsoft.Attestation/attestationProviders/attestation/write
- Microsoft.Attestation/attestationProviders/attestation/delete
To perform these actions, a Microsoft Entra user must have Attestation Contributor role on the attestation provider. These permissions can also be inherited with roles such as Owner (wildcard permissions)/ Contributor (wildcard permissions) on the subscription/ resource group.
In order to read policies, a Microsoft Entra user requires the following permission for "Actions":
- Microsoft.Attestation/attestationProviders/attestation/read
To perform this action, a Microsoft Entra user must have Attestation Reader role on the attestation provider. The read permissions can also be inherited with roles such as Reader (wildcard permissions) on the subscription/ resource group.
These PowerShell cmdlets provide policy management for an attestation provider (one TEE at a time).
Get-AzAttestationPolicy returns the current policy for the specified TEE. The cmdlet displays policy in both text and JWT format of the policy.
$teeType = "<tee Type>"
Get-AzAttestationPolicy -Name $attestationProvider -ResourceGroupName $attestationResourceGroup -Tee $teeType
Supported TEE types are "SgxEnclave", "OpenEnclave" and "VbsEnclave".
Set-AttestationPolicy sets a new policy for the specified TEE. The cmdlet accepts policy in either text or JWT format and is controlled by the PolicyFormat parameter. "Text" is the default value for PolicyFormat.
$policyFormat = "<policy format>"
$policy=Get-Content -path "C:\test\policy.txt" -Raw
Set-AzAttestationPolicy -Name $attestationProvider -ResourceGroupName $attestationResourceGroup -Tee $teeType -Policy $policy -PolicyFormat $policyFormat
If PolicySignerCertificateFile is provided during creation of an attestation provider, policies can be configured only in signed JWT format. Else policy can be configured in text or an unsigned JWT format.
Attestation policy in JWT format must contain a claim named "AttestationPolicy". For signed policy, JWT must be signed with private key corresponding to any of the existing policy signer certificates.
For policy samples, see examples of an attestation policy.
Reset-AzAttestationPolicy resets the policy to default for the specified TEE.
Reset-AzAttestationPolicy -Name $attestationProvider -ResourceGroupName $attestationResourceGroup -Tee $teeType
Policy signer certificates management
These PowerShell cmdlets provide policy signer certificates management for an attestation provider:
Get-AzAttestationPolicySigners -Name $attestationProvider -ResourceGroupName $attestationResourceGroup
Add-AzAttestationPolicySigner -Name $attestationProvider -ResourceGroupName $attestationResourceGroup -Signer <signer>
Remove-AzAttestationPolicySigner -Name $attestationProvider -ResourceGroupName $attestationResourceGroup -Signer <signer>
Policy signer certificate is a signed JWT with claim named "maa-policyCertificate". Value of the claim is a JWK, which contains the trusted signing key to add. The JWT must be signed with private key corresponding to any of the existing policy signer certificates.
All semantic manipulation of the policy signer certificate must be done outside of PowerShell. As far as PowerShell is concerned, it is a simple string.
For policy signer certificate sample, see examples of policy signer certificate.
For more information on the cmdlets and its parameters, see Azure Attestation PowerShell cmdlets