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.

Please note that, 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 

Install Az.Attestation PowerShell module

On machine with Azure PowerShell, install the Az.Attestation PowerShell module, which contains cmdlets for Azure Attestation.

Initial installation

Terminate all existing PowerShell windows.

To install for "current user", launch a non-elevated PowerShell window and run:

Install-Module -Name Az.Attestation -AllowClobber -Scope CurrentUser

To install for "all users", launch an elevated PowerShell window and run:

Install-Module -Name Az.Attestation -AllowClobber -Scope AllUsers

Close the elevated PowerShell console.

Update the installation

Terminate all existing PowerShell windows.

To update for "current user", launch a non-elevated PowerShell window and run:

Update-Module -Name Az.Attestation

To update for "all users", launch an elevated PowerShell window and run:

Update-Module -Name Az.Attestation

Close the elevated PowerShell console.

Get installed modules

Minimum version of Az modules required to support attestation operations:

  • Az 4.5.0
  • Az.Accounts 1.9.2
  • Az.Attestation 0.1.8

Run the below command to verify the installed version of all Az modules

Get-InstalledModule

If the versions are not matching with the minimum requirement, run Update-Module commands.

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. Note that 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. Note that 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, an Azure AD user must have Attestation Contributor role on the provider to perform operations like policy configuration/ policy signer certificates management. These permissions can be 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-AzAttestation -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-AzAttestation -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-AzAttestation -Name $attestationProvider -ResourceGroupName $attestationResourceGroup  

The above command should produce an output like the one below:

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-AzAttestation -Name $attestationProvider -ResourceGroupName $attestationResourceGroup

Policy management

In order to manage policies, an Azure AD 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, an Azure AD user must have Attestation Contributor role on the attestation provider. These permissions can be also be inherited with roles such as Owner (wildcard permissions)/ Contributor (wildcard permissions) on the subscription/ resource group.

In order to read policies, an Azure AD user requires the following permission for "Actions":

  • Microsoft.Attestation/attestationProviders/attestation/read

To perform this action, an Azure AD user must have Attestation Reader role on the attestation provider. The read permission can be also be inherited with roles such as Reader (wildcard permissions) on the subscription/ resource group.

Below 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

Below 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.

Note that 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

Next steps