|
| 1 | +--- |
| 2 | +title: Stop using the managed identity VM extension and start using the Azure Instance Metadata Service endpoint |
| 3 | +description: Step by step instructions to stop using the VM extension and start using the Azure Instance Metadata Service (IMDS) for authentication. |
| 4 | +services: active-directory |
| 5 | +documentationcenter: |
| 6 | +author: priyamohanram |
| 7 | +manager: daveba |
| 8 | +editor: |
| 9 | + |
| 10 | +ms.service: active-directory |
| 11 | +ms.subservice: msi |
| 12 | +ms.devlang: na |
| 13 | +ms.topic: conceptual |
| 14 | +ms.tgt_pltfrm: na |
| 15 | +ms.workload: identity |
| 16 | +ms.date: 02/25/2018 |
| 17 | +ms.author: priyamo |
| 18 | +--- |
| 19 | + |
| 20 | +# How to stop using the virtual machine managed identities extension and start using the Azure Instance Metadata Service |
| 21 | + |
| 22 | +## Virtual machine extension for managed identities |
| 23 | + |
| 24 | +The virtual machine extension for managed identities is used to request tokens for a managed identity within the virtual machine. The workflow consists of the following steps: |
| 25 | + |
| 26 | +1. First, the workload within the resource calls the local endpoint `http://localhost/oauth2/token` to request an access token. |
| 27 | +2. The virtual machine extension then uses the credentials for the managed identity, to request an access token from Azure AD.. |
| 28 | +3. The access token is returned to the caller, and can be used to authenticate to services that support Azure AD authentication, like Azure Key Vault or Azure Storage. |
| 29 | + |
| 30 | +Due to several limitations outlined in the next section, the managed identity VM extension has been deprecated in favor of using the equivalent endpoint in the Azure Instance Metadata Service (IMDS) |
| 31 | + |
| 32 | +### Provision the extension |
| 33 | + |
| 34 | +When you configure a virtual machine or virtual machine scale set to have a managed identity, you may optional choose to, you may optionally choose to provision the managed identities for Azure resources VM extension using the `-Type` parameter on the [Set-AzVMExtension](https://docs.microsoft.com/powershell/module/az.compute/set-azvmextension) cmdlet. You can pass either `ManagedIdentityExtensionForWindows` or `ManagedIdentityExtensionForLinux`, depending on the type of virtual machine, and name it using the `-Name` parameter. The `-Settings` parameter specifies the port used by the OAuth token endpoint for token acquisition: |
| 35 | + |
| 36 | +```powershell |
| 37 | + $settings = @{ "port" = 50342 } |
| 38 | + Set-AzVMExtension -ResourceGroupName myResourceGroup -Location WestUS -VMName myVM -Name "ManagedIdentityExtensionForWindows" -Type "ManagedIdentityExtensionForWindows" -Publisher "Microsoft.ManagedIdentity" -TypeHandlerVersion "1.0" -Settings $settings |
| 39 | +``` |
| 40 | + |
| 41 | +You can also use the Azure Resource Manager deployment template to provision the VM extension, by adding the following JSON to the `resources` section to the template (use `ManagedIdentityExtensionForLinux` for the name and type elements for the Linux version). |
| 42 | + |
| 43 | + ```json |
| 44 | + { |
| 45 | + "type": "Microsoft.Compute/virtualMachines/extensions", |
| 46 | + "name": "[concat(variables('vmName'),'/ManagedIdentityExtensionForWindows')]", |
| 47 | + "apiVersion": "2018-06-01", |
| 48 | + "location": "[resourceGroup().location]", |
| 49 | + "dependsOn": [ |
| 50 | + "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'))]" |
| 51 | + ], |
| 52 | + "properties": { |
| 53 | + "publisher": "Microsoft.ManagedIdentity", |
| 54 | + "type": "ManagedIdentityExtensionForWindows", |
| 55 | + "typeHandlerVersion": "1.0", |
| 56 | + "autoUpgradeMinorVersion": true, |
| 57 | + "settings": { |
| 58 | + "port": 50342 |
| 59 | + } |
| 60 | + } |
| 61 | + } |
| 62 | + ``` |
| 63 | + |
| 64 | + |
| 65 | +If you're working with virtual machine scale sets, you can also provision the managed identities for Azure resources virtual machine scale set extension using the [Add-AzVmssExtension](/powershell/module/az.compute/add-azvmssextension) cmdlet. You can pass either `ManagedIdentityExtensionForWindows` or `ManagedIdentityExtensionForLinux`, depending on the type of virtual machine scale set, and name it using the `-Name` parameter. The `-Settings` parameter specifies the port used by the OAuth token endpoint for token acquisition: |
| 66 | + |
| 67 | + ```powershell |
| 68 | + $setting = @{ "port" = 50342 } |
| 69 | + $vmss = Get-AzVmss |
| 70 | + Add-AzVmssExtension -VirtualMachineScaleSet $vmss -Name "ManagedIdentityExtensionForWindows" -Type "ManagedIdentityExtensionForWindows" -Publisher "Microsoft.ManagedIdentity" -TypeHandlerVersion "1.0" -Setting $settings |
| 71 | + ``` |
| 72 | +To provision the virtual machine scale set extension with the Azure Resource Manager deployment template, add the following JSON to the `extensionpProfile` section to the template (use `ManagedIdentityExtensionForLinux` for the name and type elements for the Linux version). |
| 73 | + |
| 74 | + ```json |
| 75 | + "extensionProfile": { |
| 76 | + "extensions": [ |
| 77 | + { |
| 78 | + "name": "ManagedIdentityWindowsExtension", |
| 79 | + "properties": { |
| 80 | + "publisher": "Microsoft.ManagedIdentity", |
| 81 | + "type": "ManagedIdentityExtensionForWindows", |
| 82 | + "typeHandlerVersion": "1.0", |
| 83 | + "autoUpgradeMinorVersion": true, |
| 84 | + "settings": { |
| 85 | + "port": 50342 |
| 86 | + }, |
| 87 | + "protectedSettings": {} |
| 88 | + } |
| 89 | + } |
| 90 | + ``` |
| 91 | + |
| 92 | +Provisioning of the virtual machine extension might fail due to DNS lookup failures. If this happens, restart the virtual machine, and try again. |
| 93 | + |
| 94 | +### Remove the extension |
| 95 | +To remove the extension, use `-n ManagedIdentityExtensionForWindows` or `-n ManagedIdentityExtensionForLinux` switch (depending on the type of virtual machine) with [az vm extension delete](https://docs.microsoft.com/cli/azure/vm/), or [az vmss extension delete](https://docs.microsoft.com/cli/azure/vmss) for virtual machine scale sets using Azure CLI, or `Remove-AzVMExtension` for Powershell: |
| 96 | + |
| 97 | +```azurecli-interactive |
| 98 | +az vm identity --resource-group myResourceGroup --vm-name myVm -n ManagedIdentityExtensionForWindows |
| 99 | +``` |
| 100 | + |
| 101 | +```azurecli-interactive |
| 102 | +az vmss extension delete -n ManagedIdentityExtensionForWindows -g myResourceGroup -vmss-name myVMSS |
| 103 | +``` |
| 104 | + |
| 105 | +```powershell |
| 106 | +Remove-AzVMExtension -ResourceGroupName myResourceGroup -Name "ManagedIdentityExtensionForWindows" -VMName myVM |
| 107 | +``` |
| 108 | + |
| 109 | +### Acquire a token using the virtual machine extension |
| 110 | + |
| 111 | +The following is a sample request using the managed identities for Azure resources VM Extension Endpoint: |
| 112 | + |
| 113 | +``` |
| 114 | +GET http://localhost:50342/oauth2/token?resource=https%3A%2F%2Fmanagement.azure.com%2F HTTP/1.1 |
| 115 | +Metadata: true |
| 116 | +``` |
| 117 | + |
| 118 | +| Element | Description | |
| 119 | +| ------- | ----------- | |
| 120 | +| `GET` | The HTTP verb, indicating you want to retrieve data from the endpoint. In this case, an OAuth access token. | |
| 121 | +| `http://localhost:50342/oauth2/token` | The managed identities for Azure resources endpoint, where 50342 is the default port and is configurable. | |
| 122 | +| `resource` | A query string parameter, indicating the App ID URI of the target resource. It also appears in the `aud` (audience) claim of the issued token. This example requests a token to access Azure Resource Manager, which has an App ID URI of https://management.azure.com/. | |
| 123 | +| `Metadata` | An HTTP request header field, required by managed identities for Azure resources as a mitigation against Server Side Request Forgery (SSRF) attack. This value must be set to "true", in all lower case.| |
| 124 | +| `object_id` | (Optional) A query string parameter, indicating the object_id of the managed identity you would like the token for. Required, if your VM has multiple user-assigned managed identities.| |
| 125 | +| `client_id` | (Optional) A query string parameter, indicating the client_id of the managed identity you would like the token for. Required, if your VM has multiple user-assigned managed identities.| |
| 126 | + |
| 127 | + |
| 128 | +Sample response: |
| 129 | + |
| 130 | +``` |
| 131 | +HTTP/1.1 200 OK |
| 132 | +Content-Type: application/json |
| 133 | +{ |
| 134 | + "access_token": "eyJ0eXAi...", |
| 135 | + "refresh_token": "", |
| 136 | + "expires_in": "3599", |
| 137 | + "expires_on": "1506484173", |
| 138 | + "not_before": "1506480273", |
| 139 | + "resource": "https://management.azure.com/", |
| 140 | + "token_type": "Bearer" |
| 141 | +} |
| 142 | +``` |
| 143 | + |
| 144 | +| Element | Description | |
| 145 | +| ------- | ----------- | |
| 146 | +| `access_token` | The requested access token. When calling a secured REST API, the token is embedded in the `Authorization` request header field as a "bearer" token, allowing the API to authenticate the caller. | |
| 147 | +| `refresh_token` | Not used by managed identities for Azure resources. | |
| 148 | +| `expires_in` | The number of seconds the access token continues to be valid, before expiring, from time of issuance. Time of issuance can be found in the token's `iat` claim. | |
| 149 | +| `expires_on` | The timespan when the access token expires. The date is represented as the number of seconds from "1970-01-01T0:0:0Z UTC" (corresponds to the token's `exp` claim). | |
| 150 | +| `not_before` | The timespan when the access token takes effect, and can be accepted. The date is represented as the number of seconds from "1970-01-01T0:0:0Z UTC" (corresponds to the token's `nbf` claim). | |
| 151 | +| `resource` | The resource the access token was requested for, which matches the `resource` query string parameter of the request. | |
| 152 | +| `token_type` | The type of token, which is a "Bearer" access token, which means the resource can give access to the bearer of this token. | |
| 153 | + |
| 154 | + |
| 155 | +### Troubleshoot the virtual machine extension |
| 156 | + |
| 157 | +#### Restart the virtual machine extension after a failure |
| 158 | + |
| 159 | +On Windows and certain versions of Linux, if the extension stops, the following cmdlet may be used to manually restart it: |
| 160 | + |
| 161 | +```powershell |
| 162 | +Set-AzVMExtension -Name <extension name> -Type <extension Type> -Location <location> -Publisher Microsoft.ManagedIdentity -VMName <vm name> -ResourceGroupName <resource group name> -ForceRerun <Any string different from any last value used> |
| 163 | +``` |
| 164 | + |
| 165 | +Where: |
| 166 | +- Extension name and type for Windows is: `ManagedIdentityExtensionForWindows` |
| 167 | +- Extension name and type for Linux is: `ManagedIdentityExtensionForLinux` |
| 168 | + |
| 169 | +#### "Automation script" fails when attempting schema export for managed identities for Azure resources extension |
| 170 | + |
| 171 | +When managed identities for Azure resources is enabled on a virtual machine, the following error is shown when attempting to use the “Automation script” feature for the virtual machine, or its resource group: |
| 172 | + |
| 173 | + |
| 174 | + |
| 175 | +The managed identities for Azure resources virtual machine extension does not currently support the ability to export its schema to a resource group template. As a result, the generated template does not show configuration parameters to enable managed identities for Azure resources on the resource. These sections can be added manually by following the examples in [Configure managed identities for Azure resources on an Azure virtual machine using a templates](qs-configure-template-windows-vm.md). |
| 176 | + |
| 177 | +When the schema export functionality becomes available for the managed identities for Azure resources virtual machine extension (planned for deprecation in January 2019), it will be listed in [Exporting Resource Groups that contain VM extensions](../../virtual-machines/extensions/export-templates.md#supported-virtual-machine-extensions). |
| 178 | + |
| 179 | +## Limitations of the virtual machine extension |
| 180 | + |
| 181 | +There are several major limitations to using the virtual machine extension. |
| 182 | + |
| 183 | + * The most serious limitation is the fact that the credentials used to request tokens are stored on the virtual machine. An attacker who successfully breaches the virtual machine can exfiltrate the credentials. |
| 184 | + * Furthermore, the virtual machine extension is still unsupported by several Linux distributions, with a huge development cost to modify, build and test the extension on each of those distributions. Currently, only the following Linux distributions are supported: |
| 185 | + * CoreOS Stable |
| 186 | + * CentOS 7.1 |
| 187 | + * Red Hat 7.2 |
| 188 | + * Ubuntu 15.04 |
| 189 | + * Ubuntu 16.04 |
| 190 | + * There is a performance impact to deploying virtual machines with managed identities, as the virtual machine extension also has to be provisioned. |
| 191 | + * Finally, the virtual machine extension can only support having 32 user-assigned managed identities per virtual machine. |
| 192 | + |
| 193 | +## Azure Instance Metadata Service |
| 194 | + |
| 195 | +The [Azure Instance Metadata Service (IMDS)](https://docs.microsoft.com/azure/virtual-machines/instance-metadata-service) is a REST endpoint that provides information about running virtual machine instances that can be used to manage and configure your virtual machines. The endpoint is available at a well-known non-routable IP address (`169.254.169.254`) that can be accessed only from within the virtual machine. |
| 196 | + |
| 197 | +There are several advantages to using Azure IMDS to request tokens. |
| 198 | + |
| 199 | +1. The service is external to the virtual machine, therefore the credentials used by managed identities are no longer present on the virtual machine. Instead, they are hosted and secured on the host machine of the Azure virtual machine. |
| 200 | +2. All Windows and Linux operating systems supported on Azure IaaS can use managed identities. |
| 201 | +3. Deployment is faster and easier, since the VM extension no longer needs to be provisioned. |
| 202 | +4. With the IMDS endpoint, up to 1000 user-assigned managed identities can be assigned to a single virtual machine. |
| 203 | +5. There is no significant change to the requests using IMDS as opposed to those using the virtual machine extension, therefore it is fairly simple to port over existing deployments that currently use the virtual machine extension. |
| 204 | + |
| 205 | +For these reasons, the Azure IMDS service will be the defacto way to request tokens, once the virtual machine extension is deprecated. |
| 206 | + |
| 207 | + |
| 208 | +## Next Steps |
| 209 | + |
| 210 | +* [How to use managed identities for Azure resources on an Azure virtual machine to acquire an access token](how-to-use-vm-token.md) |
| 211 | +* [Azure Instance Metadata Service](https://docs.microsoft.com/azure/virtual-machines/windows/instance-metadata-service) |
0 commit comments