From 9e55c40d16d00f32e10b614ec9002cbe0172603d Mon Sep 17 00:00:00 2001 From: Jiashuo Li <4003950+jiasli@users.noreply.github.com> Date: Tue, 2 Nov 2021 11:08:44 +0800 Subject: [PATCH] Add doc for MSAL-based Azure CLI (#2807) --- docs-ref-conceptual/TOC.yml | 37 +++--- docs-ref-conceptual/install-azure-cli-beta.md | 110 ------------------ .../install-azure-cli-windows.md | 12 +- docs-ref-conceptual/install-azure-cli.md | 1 - .../migrate-to-azure-identity.md | 66 ----------- docs-ref-conceptual/msal-based-azure-cli.md | 61 ++++++++++ .../release-notes-azure-cli.md | 32 +---- 7 files changed, 82 insertions(+), 237 deletions(-) delete mode 100644 docs-ref-conceptual/install-azure-cli-beta.md delete mode 100644 docs-ref-conceptual/migrate-to-azure-identity.md create mode 100644 docs-ref-conceptual/msal-based-azure-cli.md diff --git a/docs-ref-conceptual/TOC.yml b/docs-ref-conceptual/TOC.yml index 42cff83824..53642a4922 100644 --- a/docs-ref-conceptual/TOC.yml +++ b/docs-ref-conceptual/TOC.yml @@ -9,15 +9,15 @@ href: azure-services-the-azure-cli-can-manage.md displayName: >- into, introduction, matrix, azure products, products supported, services - App Configuration, App Service, Active Directory (AD), Backup, Cognitive Search, - Cosmos DB, Data Lake Storage, Database, MariaDB, MySQL, PostgreSQL, PostgreSQL, - DevOps, DevTest Labs, DNS, Functions, IoT, IoT Central, IoT Edge, IoT Hub, - Kubernetes Service (AKS), Lab Services, Machine Learning, Managed Applications, - Private Link, Resource Manager, Spring Cloud, SQL Database, Batch, Cognitive Services, - Container Instances, Container Registry, Data Lake Analytics, Event Grid, Event Hubs, - HDInsight, Key Vault, Load Balancer, Managed Disks, Media Services, - Notification Hubs, Service Bus, Service Fabric, Storage Accounts, Traffic Manager, - Virtual Machine Scale Sets, Virtual Network, Compute, Networking, Internet of Things, + App Configuration, App Service, Active Directory (AD), Backup, Cognitive Search, + Cosmos DB, Data Lake Storage, Database, MariaDB, MySQL, PostgreSQL, PostgreSQL, + DevOps, DevTest Labs, DNS, Functions, IoT, IoT Central, IoT Edge, IoT Hub, + Kubernetes Service (AKS), Lab Services, Machine Learning, Managed Applications, + Private Link, Resource Manager, Spring Cloud, SQL Database, Batch, Cognitive Services, + Container Instances, Container Registry, Data Lake Analytics, Event Grid, Event Hubs, + HDInsight, Key Vault, Load Balancer, Managed Disks, Media Services, + Notification Hubs, Service Bus, Service Fabric, Storage Accounts, Traffic Manager, + Virtual Machine Scale Sets, Virtual Network, Compute, Networking, Internet of Things, Developer Tools, Databases, Analytics, Management and Governance, Hybrid, Storage, Security, AI + Machine Learning - name: Get started href: get-started-with-azure-cli.md @@ -27,6 +27,9 @@ displayName: core, extension, status, GA, public preview, experimental - name: Release notes href: release-notes-azure-cli.md?toc=%2fcli%2fazure%2ftoc.json&bc=%2fcli%2fazure%2fbreadcrumb%2ftoc.json + - name: MSAL-based Azure CLI + href: msal-based-azure-cli.md + displayName: MSAL, ADAL, authentication, encryption, accessTokens, az account get-access-token - name: CLI Versioning href: cli-versioning-identifiers.md displayName: version, classic, 2.0, 1.0, xplat @@ -44,9 +47,6 @@ - name: Install - Linux href: install-azure-cli-linux.md displayName: install, script, unix, bsd, linux, lfs, wsl, slackware, ubuntu, debian, mint, opensuse, suse, sles, leap, tumbleweed, rhel, redhat, red hat, fedora - - name: Install - beta - href: install-azure-cli-beta.md - displayName: install, beta - name: Update href: update-azure-cli.md displayName: update, upgrade @@ -131,9 +131,6 @@ - name: Work with multiple clouds href: manage-clouds-azure-cli.md?toc=%2fcli%2fazure%2ftoc.json&bc=%2fcli%2fazure%2fbreadcrumb%2ftoc.json displayName: region, china, germany, government, governance, stack - - name: Migrate to Azure Identity - href: migrate-to-azure-identity.md - displayName: accessTokens, ADAL, MSAL, az account get-access-token - name: Request support href: azure-cli-support-request.md - name: Deploy with templates @@ -156,7 +153,7 @@ items: - name: Azure Cosmos DB href: azure-cli-reference-for-cosmos-db.md - display: Azure Cosmos DB, SQL, MongoDB, Cassandra, Gremlin, Table, colleciton, database, identity, keys, network-rule, private-endpoint-connection, private-link-resource, restorable-database-account, managed-cassandra, cluster, datacenter + display: Azure Cosmos DB, SQL, MongoDB, Cassandra, Gremlin, Table, colleciton, database, identity, keys, network-rule, private-endpoint-connection, private-link-resource, restorable-database-account, managed-cassandra, cluster, datacenter - name: Azure Data Share href: azure-cli-reference-for-data-share.md displayName: Azure Data Share, az datashare, Data Share @@ -171,16 +168,16 @@ displayName: IoT, az iot, az dt, az maps, az timeseriesinsights - name: Azure Monitor href: azure-cli-reference-for-monitor.md - display: Azure Monitor, az monitor, insights, application insights, log analytics, az app-insights, az log-analytics + display: Azure Monitor, az monitor, insights, application insights, log analytics, az app-insights, az log-analytics - name: Azure Network href: azure-cli-reference-for-network.md - display: peering, asg, appliance, dns, endpoint, nat, nic, route, vmware, vnet, cross connection, express-route, vhub, vpn, vrouter, vwan, ib, ip, front-door, gateway, traffic, bastion, ddos, firewall + display: peering, asg, appliance, dns, endpoint, nat, nic, route, vmware, vnet, cross connection, express-route, vhub, vpn, vrouter, vwan, ib, ip, front-door, gateway, traffic, bastion, ddos, firewall - name: Azure SQL href: azure-cli-reference-for-sql.md display: Azure SQL, Azure SQL Database, Azure SQL Managed Instance, SQL Server on Azure VM, SQL pool, database - name: Azure Storage href: azure-cli-reference-for-storage.md - display: Azure Storage, Azure Blob Storage, Azure Import/Export service, Azure Data Lake Storage Gen2 + display: Azure Storage, Azure Blob Storage, Azure Import/Export service, Azure Data Lake Storage Gen2 - name: Azure Virtual Machines href: azure-cli-reference-for-virtual-machines.md - display: Azure Virtual Machines, Azure virtual machine scale set, shared image galleries, desktop virtualization \ No newline at end of file + display: Azure Virtual Machines, Azure virtual machine scale set, shared image galleries, desktop virtualization \ No newline at end of file diff --git a/docs-ref-conceptual/install-azure-cli-beta.md b/docs-ref-conceptual/install-azure-cli-beta.md deleted file mode 100644 index bdc7b2e76f..0000000000 --- a/docs-ref-conceptual/install-azure-cli-beta.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: How to install the Azure CLI beta version | Microsoft Docs -description: Learn how to install the Azure CLI beta version. This beta version offers increased security for token cache, access tokens and SSL certificates. -author: dbradish-microsoft -ms.author: dbradish -manager: barbkess -ms.date: 08/01/2021 -ms.topic: conceptual -ms.service: azure-cli -ms.devlang: azurecli -ms.custom: devx-track-azurecli, seo-azure-cli -keywords: Install azure cli, azure cli download, install azure cli beta ---- - -# Install Azure CLI beta version - -A new beta version of the Azure CLI has been released that offers increased security for token cache, access tokens and SSL certificates. This beta vesion can be installed in Windows, macOS and Linux environments and will stay in sync with the most recent release. - -> [!NOTE] -> -> BREAKING CHANGES are introduced in this release. Carefully read all [release notes](/cli/azure/release-notes-azure-cli?tabs=azure-cli-beta) prior to installation. -> -> The beta version does not guarantee product level quality so it should not be used in your production environment. - -## Understand beta changes - -### `accessTokens.json` deprecation - -The current Azure CLI saves the ADAL refresh tokens and access tokens to `~/.azure/accessToken.json`. Azure CLI beta uses MSAL and will no longer generate `accessTokens.json`. Tokens will be saved to MSAL's shared token cache called `msal.cache`. - -The MSAL token cache will be encrypted on Windows, macOS and Linux with a desktop environment; therefore, directly accessing the MSAL token cache will not work. Any existing workflow depending on `accessTokens.json` will stop working. - -Below are several alternatives you may consider: - -#### Calling `az account get-access-token` - -You can manually call `az account get-access-token` in a terminal or use subprocess to call it from another programming language. By default, the returned token is for the default subscription/tenant shown in `az account show`. - -#### Using `AzureCliCredential` - -`AzureCliCredential` is a credential type in all existing language SDKs. It internally uses subprocess to call `az account get-access-token` to gets an access token from current logged in CLI accounts. - -#### Accessing shared MSAL cache - -First party apps can use `SharedTokenCacheCredential` from Azure Identity SDK to directly access the shared MSAL cache. - -## How to install Azure CLI beta - -Azure CLI is built on [Python](https://www.python.org/). The supported Python versions are 3.6, 3.7, 3.8. On Windows, you will first need to [install Python](https://www.python.org/downloads/windows/). - -Azure CLI beta can only be installed with `pip` from a Microsoft repository. Use [Azure Cloud Shell](https://shell.azure.com) to execute the following commands, or `python3`, depending on the Linux distribution or your installed Python version. - -To avoid overwriting your installed Azure CLI, we recommend installing the beta version in a [virtual environment](https://docs.python.org/3/tutorial/venv.html). - -1. Create a virtual environment - - Navigate to the folder where you want to create the virtual environment, then run: - - ```bash - python -m venv - ``` - -1. Activate the virtual environment - - ### [Windows PowerShell](#tab/powershell) - - ```powershell - . .\\Scripts\Activate.ps1 - ``` - - ### [Linux/macOS Bash](#tab/bash) - - ```bash - . /bin/activate - ``` - --- - These commands can also be used to reactivate your virtual environment. - -1. Install Azure CLI beta - - ```bash - python -m pip install --upgrade pip - pip install --extra-index-url https://azcliprod.blob.core.windows.net/beta/simple/ azure-cli - ``` - -1. Deactivate the virtual environment - - After you finish using Azure CLI beta, you can close the terminal window, or use the `deactivate` command. - - ```bash - deactivate - ``` - -## How to uninstall Azure CLI beta - -To uninstall Azure CLI beta, delete the virtual environment folder. - -### [Windows PowerShell](#tab/powershell) - -```powershell -Remove-Item -Force -Recurse -``` - -### [Linux/macOS Bash](#tab/bash) - -```bash -rm -rf -``` - ---- diff --git a/docs-ref-conceptual/install-azure-cli-windows.md b/docs-ref-conceptual/install-azure-cli-windows.md index f1bc21b5bb..fdea611433 100644 --- a/docs-ref-conceptual/install-azure-cli-windows.md +++ b/docs-ref-conceptual/install-azure-cli-windows.md @@ -29,23 +29,17 @@ The MSI distributable is used for installing or updating the Azure CLI on Window # [Microsoft Installer (MSI)](#tab/azure-cli) -When the installer asks if it can make changes to your computer, click the "Yes" box. +### Latest version -### Current version - -Download and install the current release of the Azure CLI. After the installation is complete, you will need to close and reopen any active Windows Command Prompt or PowerShell windows to use the Azure CLI. +Download and install the latest release of the Azure CLI. When the installer asks if it can make changes to your computer, click the "Yes" box. After the installation is complete, you will need to close and reopen any active Windows Command Prompt or PowerShell windows to use the Azure CLI. > [!div class="nextstepaction"] -> [Current release of the Azure CLI](https://aka.ms/installazurecliwindows) +> [Latest release of the Azure CLI](https://aka.ms/installazurecliwindows) ### Specific version To download the MSI installer for specific version, change the version segment in URL `https://azcliprod.blob.core.windows.net/msi/azure-cli-.msi` and download it. Available versions can be found at [Azure CLI release notes](/cli/azure/release-notes-azure-cli). -### Azure CLI beta version - -The beta version of the Azure CLI supports all commands and will stay in sync with the current released version. For installation instructions, see [Install Azure CLI beta version](install-azure-cli-beta.md). - # [Microsoft Installer (MSI) with Command](#tab/azure-powershell) ### Powershell Command diff --git a/docs-ref-conceptual/install-azure-cli.md b/docs-ref-conceptual/install-azure-cli.md index b7fc6cf591..51676d6a18 100644 --- a/docs-ref-conceptual/install-azure-cli.md +++ b/docs-ref-conceptual/install-azure-cli.md @@ -27,7 +27,6 @@ The Azure CLI is available to install in Windows, macOS and Linux environments. * [Install with dnf on RHEL, Fedora, or CentOS](/cli/azure/install-azure-cli-linux?pivots=yum) * [Install with zypper on openSUSE or SLE](/cli/azure/install-azure-cli-linux?pivots=zypper) * [Install from script](install-azure-cli-linux.md) -* [Install beta version (all environments)](install-azure-cli-beta.md) * [Run in Docker container](run-azure-cli-docker.md) * [Run in Azure Cloud Shell](/azure/cloud-shell/quickstart) diff --git a/docs-ref-conceptual/migrate-to-azure-identity.md b/docs-ref-conceptual/migrate-to-azure-identity.md deleted file mode 100644 index f5410c5ad3..0000000000 --- a/docs-ref-conceptual/migrate-to-azure-identity.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Migrate to Azure Identity – Azure CLI | Microsoft Docs -description: Azure CLI beta internally replaces ADAL with Azure Identity and MSAL. Learn how to migrate from accessTokens.json to Azure Identity and MSAL. -author: dbradish-microsoft -ms.author: dbradish -manager: barbkess -ms.date: 9/21/2021 -ms.topic: conceptual -ms.service: azure-cli -ms.devlang: azurecli -ms.custom: devx-track-azurecli, seo-azure-cli -keywords: migrate to azure identity, azure cli beta ---- -# Migrate to Azure Identity - -Azure CLI beta internally replaces Azure Active Directory Authentication Library [(ADAL)](https://github.com/AzureAD/azure-activedirectory-library-for-python) with [Azure Identity](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity) and Microsoft Authentication Library [(MSAL)](https://github.com/AzureAD/microsoft-authentication-library-for-python). Existing ADAL token cache (`~/.azure/accessToken.json`) will be migrated to MSAL encrypted token cache automatically when any command requiring a credential is executed. - -This article provides detail about this breaking change and gives examples on how to get an access-token in Azure CLI beta. - -## Azure CLI beta release breaking change - -The current Azure CLI saves the ADAL refresh tokens and access tokens to `~/.azure/accessToken.json`. Azure CLI beta uses MSAL and will no longer generate `accessTokens.json` after a successful login. Tokens will be saved to MSAL's shared token cache called `msal.cache`. To get an access token, use `az account get-access-token` instead. - -The MSAL token cache will be encrypted on Windows, macOS and Linux with a desktop environment; therefore, directly accessing the MSAL token cache will not work. Any existing workflow depending on `accessTokens.json` will stop working. - -## Alternatives to consider - -##### Call `az account get-access-token` - -You can manually call [az account get-access-token](/cli/azure/account#az_account_get_access_token) in a terminal or use a subprocess to call it from another programming language. By default, the returned token is for the default subscription/tenant shown in [az account show](/cli/azure/account#az_account_show). - -```azurecli -# get the active subscription -az account show --output table - -# get access token for the default subscription -az account get-access-token - -# get access token for a specific subscription -az account get-access-token --subscription "mySubscriptionName" -``` - -##### Use `AzureCliCredential` - -`AzureCliCredential` is a credential type in all existing language SDKs. It internally uses a subprocess to call `az account get-access-token` to gets an access token from current logged in CLI accounts. - -##### Access shared MSAL cache - -First party apps can use `SharedTokenCacheCredential` from Azure Identity SDK to directly access the shared MSAL cache. - -## See also -* Azure CLI - * [Azure CLI beta](/cli/azure/release-notes-azure-cli?toc=%2Fcli%2Fazure%2Ftoc.json&bc=%2Fcli%2Fazure%2Fbreadcrumb%2Ftoc.json&tabs=azure-cli-beta) release notes - * [Install Azure CLI beta version](/cli/azure/install-azure-cli-beta) -* .NET - * [AzureCliCredential Class](/dotnet/api/azure.identity.azureclicredential?view=azure-dotnet&preserve-view=true) in .NET - * [SharedTokenCacheCredential Class](/dotnet/api/azure.identity.sharedtokencachecredential?view=azure-dotnet&preserve-view=true) in .NET -* Java - * [SharedTokenCacheCredential Class](/java/api/com.azure.identity.sharedtokencachecredential?view=azure-java-stable&preserve-view=true) in Java - * [AzureCliCredential Class](/java/api/com.azure.identity.azureclicredential?view=azure-java-stable&preserve-view=true) in Java -* Python - * [AzureCliCredential Class](/python/api/azure-identity/azure.identity.azureclicredential?view=azure-python&preserve-view=true) in Python - * [SharedTokenCacheCredential Class](/python/api/azure-identity/azure.identity.sharedtokencachecredential?view=azure-python&preserve-view=true) in Python -* Azure security - * [Introduction to Azure security](/azure/security/fundamentals/overview) - * [Overview of the Microsoft Authentication Library (MSAL)](/azure/active-directory/develop/msal-overview) diff --git a/docs-ref-conceptual/msal-based-azure-cli.md b/docs-ref-conceptual/msal-based-azure-cli.md new file mode 100644 index 0000000000..4dfe50f5cc --- /dev/null +++ b/docs-ref-conceptual/msal-based-azure-cli.md @@ -0,0 +1,61 @@ +--- +title: MSAL-based Azure CLI | Microsoft Docs +description: Learn about the MSAL-based Azure CLI. +author: jiasli +ms.author: jiasli +manager: yonzhan +ms.date: 10/28/2021 +ms.topic: conceptual +ms.service: azure-cli +ms.devlang: azurecli +ms.custom: devx-track-azurecli, seo-azure-cli +keywords: msal, msal-based azure cli +--- + +# MSAL-based Azure CLI + +Starting in version 2.30.0, Azure CLI uses [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-python) as the underlying authentication library. MSAL uses AAD v2.0 authentication flow to provide more functionality and increases security for token cache. + +> [!WARNING] +> BREAKING CHANGES are introduced in Azure CLI 2.30.0. Carefully read document prior to installation. + +## `accessTokens.json` deprecation + +Previous versions of Azure CLI save ADAL tokens and service principal entries to `~/.azure/accessToken.json`. Latest versions of Azure CLI use MSAL and no longer generate `accessTokens.json`. Any existing workflow depending on `accessTokens.json` no longer works. + +The MSAL token cache and service principal entries are saved as encrypted files on Windows, and plaintext files on Linux and MacOS. + +## Alternatives to consider + +Below are several alternatives you may consider: + +### Calling `az account get-access-token` + +You can manually call [`az account get-access-token`](/cli/azure/account#az_account_get_access_token) in a terminal or use subprocess to call it from another programming language. By default, the returned access token is for Azure Resource Manager (ARM) and the default subscription/tenant shown in [`az account show`](/cli/azure/account#az_account_show). + +```azurecli +# get the active subscription +az account show --output table + +# get access token for the active subscription +az account get-access-token + +# get access token for a specific subscription +az account get-access-token --subscription "" +``` + +### Using `AzureCliCredential` + +`AzureCliCredential` is a credential type in all existing language SDKs. It uses subprocess to call `az account get-access-token` to get an access token for the current logged-in account. + +## See also + +* MSAL + * [Overview of the Microsoft Authentication Library (MSAL)](/azure/active-directory/develop/msal-overview) + * [Migrate applications to the Microsoft Authentication Library (MSAL)](/azure/active-directory/develop/msal-migration) +* Python + * [AzureCliCredential Class](/python/api/azure-identity/azure.identity.azureclicredential) in Python +* .NET + * [AzureCliCredential Class](/dotnet/api/azure.identity.azureclicredential) in .NET +* Java + * [AzureCliCredential Class](/java/api/com.azure.identity.azureclicredential) in Java diff --git a/docs-ref-conceptual/release-notes-azure-cli.md b/docs-ref-conceptual/release-notes-azure-cli.md index 6ca069b1ad..fa992885ad 100644 --- a/docs-ref-conceptual/release-notes-azure-cli.md +++ b/docs-ref-conceptual/release-notes-azure-cli.md @@ -14,8 +14,6 @@ keywords: azure cli updates, azure cli notes, azure cli versions # Azure CLI release notes -# [Current release notes](#tab/azure-cli) - ## November 02, 2021 Version 2.30.0 @@ -2131,7 +2129,7 @@ Version 2.14.0 * Add List-SKUS Command, Table Transformers, Local Context for Postgres, MySQL, Mariadb Single Server * [BREAKING CHANGE] Parameter name updates. Improvements to Management Plane for MySQL and PostgreSQL -* `az postgres|mariadb|mysql server create` : Update create experience for Postgres, MySQL and MariaDB - new fields in the output , Introduce new values for `--public` parameter in create command (all,,,0.0.0.0) +* `az postgres|mariadb|mysql server create` : Update create experience for Postgres, MySQL and MariaDB - new fields in the output , Introduce new values for `--public` parameter in create command (all,\,\,0.0.0.0) ### SignalR @@ -8501,31 +8499,3 @@ You can report issues with nightly preview builds in the following ways: - Report issues in our [github issues list](https://github.com/azure/azure-cli/issues/) - Contact the product team at [azfeedback@microsoft.com](mailto:azfeedback@microsoft.com) - Provide feedback from the command line with the `az feedback` command - -# [Beta release notes](#tab/azure-cli-beta) - -## February 8, 2021 - -> [!NOTE] -> -> BREAKING CHANGES are introduced in this release. Carefully read all release notes prior to installation. -> -> The beta version does not guarantee product level quality so it should not be used in your production environment. - -* Azure CLI beta internally replaces [ADAL](https://github.com/AzureAD/azure-activedirectory-library-for-python) with [Azure Identity](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity) and [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-python). Existing ADAL token cache (`~/.azure/accessToken.json`) will be migrated to MSAL encrypted token cache automatically when any command requiring a credential is executed. - -* There are several changes to `az login`. (Run `az login --help` for more details.) - * [BREAKING CHANGE] `~/.azure/accessToken.json` will no longer be created after a successful login. To get an access token, use [`az account get-access-token`](/cli/azure/account#az_account_get_access_token) instead. - * [BREAKING CHANGE] `--use-cert-sn-issuer` argument is not supported. - * After logging in with a managed identity, all `clientId`, `objectId` and `resourceId` will be shown. - * Fix #13188: `az login` with managed identity indicating system assigned when the identity is user assigned. - -* [BREAKING CHANGE] Skip SSL verification via environment `ADAL_PYTHON_SSL_NO_VERIFY` has been removed. See [work behind a proxy](/cli/azure/use-cli-effectively#work-behind-a-proxy) for trusting a self-signed root certificate. - -The beta version of the Azure CLI supports all commands and will stay in sync with the current released version. - -For installation instructions, see [Install Azure CLI beta version](install-azure-cli-beta.md). - -If you find issues in the beta release, the Azure CLI engineering team welcomes your comments on [GitHub](https://github.com/Azure/azure-cli/issues/new/choose). - ----