@azure/identity 1.2.0-beta.2 → 1.2.0

package/CHANGELOG.md

@@ -1,8 +1,30 @@
 # Release History
 
+## 1.2.0 (2020-11-11)
+
+### Changes since 1.1.\*
+
+- With 1.2, we've added support for Azure Arc to our Managed Identity credential.
+- We've also added an Interactive Browser credential for Node, which spawns the user's browser and connects via
+  a browser-based auth code flow. This is powered by the Microsoft Authentication Library (MSAL)
+- We've moved `DeviceCodeCredential` to also use the Microsoft Authentication Library (MSAL)
+- Identity now supports Subject Name/Issuer (SNI) as part of authentication for ClientCertificateCredential.
+- Added Active Directory Federation Services authority host support to the node credentials.
+- `ManagedIdentityCredential` has been aligned with other languages, and now treats expected errors properly.
+- Added support for multiple clouds on `VisualStudioCodeCredential`.
+
+### Changes since the latest 1.2-beta
+
+- `ManagedIdentityCredential` now only checks for available MSIs once per class instance.
+- `ManagedIdentityCredential` now supports Azure Arc environments.
+- `ManagedIdentityCredential` now supports Azure Service Fabric environments.
+- Added authority host for multiple clouds on `VisualStudioCodeCredential`, and specified `AzureCloud` as the default cloud name.
+- `DeviceCodeCredential` now has both of its constructor parameters, `tenantId` and `clientId`, as optional parameters. The default value of `tenantId` is "organizations", and the Azure CLI's client ID is the default value of `clientId`.
+- We've removed the persistent cache support from the previous beta.
+
 ## 1.2.0-beta.2 (2020-10-06)
 
-- `DefaultAzureCredential` now by default shows the Device Code message on the console. This can still be overwritten with a custom behavior by specifying a function as the third parameter, `userPromptCallback`.
+- `DeviceCodeCredential` now by default shows the Device Code message on the console. This can still be overwritten with a custom behavior by specifying a function as the third parameter, `userPromptCallback`.
 - Added support for multiple clouds on `VisualStudioCodeCredential`. Fixes customer issue [11452](https://github.com/Azure/azure-sdk-for-js/issues/11452).
 - `ManagedIdentityCredential` has been aligned with other languages, now treating expected errors properly. This fixes customer issue [11451](https://github.com/Azure/azure-sdk-for-js/issues/11451).
 - `InteractiveBrowserCredential` authentication now uses the silent flow if the user provides a cache and authentication record for lookup.
@@ -18,7 +40,7 @@
 
 ## 1.1.0 (2020-08-11)
 
-### Changes since 1.0.*
+### Changes since 1.0.\*
 
 - With 1.1.0, new developer credentials are now available: `VisualStudioCodeCredential` and `AzureCliCredential`.
   - `VisualStudioCodeCredential` allows developers to log into Azure using the credentials available after logging in through the Azure Account extension in Visual Studio Code.

package/README.md

@@ -6,20 +6,32 @@ to authenticate API requests. It supports token authentication using an Azure Ac
 
 ## Getting started
 
+### Install the package
+
+Install Azure Identity with `npm`:
+
+```sh
+npm install --save @azure/identity
+```
+
 ### Prerequisites
 
 - Node.js 8 LTS or higher
 - An Azure subscription.
-    - You can sign up for a [free account](https://azure.microsoft.com/free/).
+  - You can sign up for a [free account](https://azure.microsoft.com/free/).
 - The [Azure CLI][azure_cli] can also be useful for authenticating in a development environment, creating accounts, and managing account roles.
 
+### Authenticate the client
+
+When debugging and executing code locally it is typical for a developer to use their own account for authenticating calls to Azure services. There are several developer tools which can be used to perform this authentication in your development environment.
+
 #### Authenticating via Visual Studio Code
 
 Developers using Visual Studio Code can use the [Azure Account Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account), to authenticate via the IDE. Applications using the `DefaultAzureCredential` or the `VisualStudioCodeCredential` can then use this account to authenticate calls in their application when running locally.
 
 To authenticate in Visual Studio Code, first ensure the [Azure Account Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account) is installed. Once the extension is installed, press `F1` to open the command palette and run the `Azure: Sign In` command.
 
-![Visual Studio Code Account Sign In][VsCodeLoginCommand_image]
+![Visual Studio Code Account Sign In][vscodelogincommand_image]
 
 #### Authenticating via the Azure CLI
 
@@ -27,19 +39,11 @@ Applications using the `AzureCliCredential`, rather directly or via the `Default
 
 To authenticate with the [Azure CLI][azure_cli] users can run the command `az login`. For users running on a system with a default web browser the azure cli will launch the browser to authenticate the user.
 
-![Azure CLI Account Sign In][AzureCliLogin_image]
+![Azure CLI Account Sign In][azureclilogin_image]
 
 For systems without a default web browser, the `az login` command will use the device code authentication flow. The user can also force the Azure CLI to use the device code flow rather than launching a browser by specifying the `--use-device-code` argument.
 
-![Azure CLI Account Device Code Sign In][AzureCliLoginDeviceCode_image]
-
-### Install the package
-
-Install Azure Identity with `npm`:
-
-```sh
-npm install --save @azure/identity
-```
+![Azure CLI Account Device Code Sign In][azureclilogindevicecode_image]
 
 ## Key concepts
 
@@ -57,25 +61,42 @@ See [Credential Classes](#credential-classes).
 
 The `DefaultAzureCredential` is appropriate for most scenarios where the application is intended to ultimately be run in the Azure Cloud. This is because the `DefaultAzureCredential` combines credentials commonly used to authenticate when deployed, with credentials used to authenticate in a development environment. The `DefaultAzureCredential` will attempt to authenticate via the following mechanisms in order.
 
-![DefaultAzureCredential authentication flow][DefaultAuthFlow_image]
+![DefaultAzureCredential authentication flow][defaultauthflow_image]
 
-- Environment - The `DefaultAzureCredential` will read account information specified via [environment variables](#Environment-variables) and use it to authenticate.
+- Environment - The `DefaultAzureCredential` will read account information specified via [environment variables](#environment-variables) and use it to authenticate.
 - Managed Identity - If the application is deployed to an Azure host with Managed Identity enabled, the `DefaultAzureCredential` will authenticate with that account.
 - Visual Studio Code - If the developer has authenticated via the Visual Studio Code Azure Account plugin, the `DefaultAzureCredential` will authenticate with that account.
 - Azure CLI - If the developer has authenticated an account via the Azure CLI `az login` command, the `DefaultAzureCredential` will authenticate with that account.
 
-### Environment variables
+## Environment Variables
+
+`DefaultAzureCredential` and `EnvironmentCredential` can be configured with environment variables. Each type of authentication requires values for specific variables:
 
-`DefaultAzureCredential` and `EnvironmentCredential` are configured for service principal authentication with these environment variables:
+#### Service principal with secret
 
-| variable name                   | value                                                                                                |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `AZURE_CLIENT_ID`               | service principal's app id                                                                           |
-| `AZURE_TENANT_ID`               | id of the principal's Azure Active Directory tenant                                                  |
-| `AZURE_CLIENT_SECRET`           | one of the service principal's client secrets (implies `ClientSecretCredential`)                     |
-| `AZURE_CLIENT_CERTIFICATE_PATH` | path to a PEM-encoded certificate file including private key (implies `ClientCertificateCredential`) |
-| `AZURE_USERNAME`                | the username of a user in the tenant (implies `UsernamePasswordCredential`)                          |
-| `AZURE_PASSWORD`                | the password of the user specified in `AZURE_USERNAME`                                               |
+| variable name         | value                                                 |
+| --------------------- | ----------------------------------------------------- |
+| `AZURE_CLIENT_ID`     | id of an Azure Active Directory application           |
+| `AZURE_TENANT_ID`     | id of the application's Azure Active Directory tenant |
+| `AZURE_CLIENT_SECRET` | one of the application's client secrets               |
+
+#### Service principal with certificate
+
+| variable name                   | value                                                                                      |
+| ------------------------------- | ------------------------------------------------------------------------------------------ |
+| `AZURE_CLIENT_ID`               | id of an Azure Active Directory application                                                |
+| `AZURE_TENANT_ID`               | id of the application's Azure Active Directory tenant                                      |
+| `AZURE_CLIENT_CERTIFICATE_PATH` | path to a PEM-encoded certificate file including private key (without password protection) |
+
+#### Username and password
+
+| variable name     | value                                       |
+| ----------------- | ------------------------------------------- |
+| `AZURE_CLIENT_ID` | id of an Azure Active Directory application |
+| `AZURE_USERNAME`  | a username (usually an email address)       |
+| `AZURE_PASSWORD`  | that user's password                        |
+
+Configuration is attempted in the above order. For example, if values for a client secret and certificate are both present, the client secret will be used.
 
 ## Examples
 
@@ -131,36 +152,35 @@ const client = new KeyClient(vaultUrl, credentialChain);
 
 ### Authenticating Azure Hosted Applications
 
-|credential  | usage
-|-|-
-|`DefaultAzureCredential`|provides a simplified authentication experience to quickly start developing applications run in the Azure cloud
-|`ChainedTokenCredential`|allows users to define custom authentication flows composing multiple credentials
-|`EnvironmentCredential`|authenticates a service principal or user via credential information specified in environment variables
-|`ManagedIdentityCredential`|authenticates the managed identity of an azure resource
+| credential                  | usage                                                                                                           |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `DefaultAzureCredential`    | provides a simplified authentication experience to quickly start developing applications run in the Azure cloud |
+| `ChainedTokenCredential`    | allows users to define custom authentication flows composing multiple credentials                               |
+| `EnvironmentCredential`     | authenticates a service principal or user via credential information specified in environment variables         |
+| `ManagedIdentityCredential` | authenticates the managed identity of an azure resource                                                         |
 
 ### Authenticating Service Principals
 
-|credential  | usage
-|-|-
-|`ClientSecretCredential`|authenticates a service principal using a secret
-|`ClientCertificateCredential`|authenticates a service principal using a certificate
+| credential                    | usage                                                 |
+| ----------------------------- | ----------------------------------------------------- |
+| `ClientSecretCredential`      | authenticates a service principal using a secret      |
+| `ClientCertificateCredential` | authenticates a service principal using a certificate |
 
 ### Authenticating Users
 
-|credential  | usage
-|-|-
-|`InteractiveBrowserCredential`|interactively authenticates a user with the default system browser
-|`DeviceCodeCredential`|interactively authenticates a user on devices with limited UI
-|`UserPasswordCredential`|authenticates a user with a username and password
-|`AuthorizationCodeCredential`|authenticate a user with a previously obtained authorization code
+| credential                     | usage                                                              |
+| ------------------------------ | ------------------------------------------------------------------ |
+| `InteractiveBrowserCredential` | interactively authenticates a user with the default system browser |
+| `DeviceCodeCredential`         | interactively authenticates a user on devices with limited UI      |
+| `UserPasswordCredential`       | authenticates a user with a username and password                  |
+| `AuthorizationCodeCredential`  | authenticate a user with a previously obtained authorization code  |
 
 ### Authenticating via Development Tools
 
-
-|credential  | usage
-|-|-
-|`AzureCliCredential`|authenticate in a development environment with the Azure CLI
-|`VisualStudioCodeCredential`|authenticate in a development environment with Visual Studio Code
+| credential                   | usage                                                             |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `AzureCliCredential`         | authenticate in a development environment with the Azure CLI      |
+| `VisualStudioCodeCredential` | authenticate in a development environment with Visual Studio Code |
 
 ## Troubleshooting
 
@@ -184,12 +204,12 @@ setLogLevel("info");
 
 Currently, the following client libraries support authenticating with `TokenCredential` and the Azure Identity library. You can learn more about their use, and find additional documentation on use of these client libraries along samples with can be found in the links below.
 
-- [@azure/event-hubs](http://npmjs.com/package/@azure/event-hubs)
-- [@azure/keyvault-keys](http://npmjs.com/package/@azure/keyvault-keys)
-- [@azure/keyvault-secrets](http://npmjs.com/package/@azure/keyvault-secrets)
-- [@azure/keyvault-certificates](http://npmjs.com/package/@azure/keyvault-certificates)
-- [@azure/storage-blob](http://npmjs.com/package/@azure/storage-blob)
-- [@azure/storage-queue](http://npmjs.com/package/@azure/storage-queue)
+- [@azure/event-hubs](https://npmjs.com/package/@azure/event-hubs)
+- [@azure/keyvault-keys](https://npmjs.com/package/@azure/keyvault-keys)
+- [@azure/keyvault-secrets](https://npmjs.com/package/@azure/keyvault-secrets)
+- [@azure/keyvault-certificates](https://npmjs.com/package/@azure/keyvault-certificates)
+- [@azure/storage-blob](https://npmjs.com/package/@azure/storage-blob)
+- [@azure/storage-queue](https://npmjs.com/package/@azure/storage-queue)
 
 ### Read the documentation
 
@@ -213,9 +233,9 @@ If you'd like to contribute to this library, please read the [contributing guide
 [8]: https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-identity/1.0.0/classes/interactivebrowsercredential.html
 [9]: https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-identity/1.0.0/classes/usernamepasswordcredential.html
 [azure_cli]: https://docs.microsoft.com/cli/azure
-[VsCodeLoginCommand_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-js/master/sdk/identity/identity/images/VsCodeLoginCommand.png
-[AzureCliLogin_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-js/master/sdk/identity/identity/images/AzureCliLogin.png
-[AzureCliLoginDeviceCode_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-js/master/sdk/identity/identity/images/AzureCliLoginDeviceCode.png
-[DefaultAuthFlow_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-js/master/sdk/identity/identity/images/DefaultAzureCredentialAuthenticationFlow.png
+[vscodelogincommand_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-js/master/sdk/identity/identity/images/VsCodeLoginCommand.png
+[azureclilogin_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-js/master/sdk/identity/identity/images/AzureCliLogin.png
+[azureclilogindevicecode_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-js/master/sdk/identity/identity/images/AzureCliLoginDeviceCode.png
+[defaultauthflow_image]: https://raw.githubusercontent.com/Azure/azure-sdk-for-js/master/sdk/identity/identity/images/DefaultAzureCredentialAuthenticationFlow.png
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fidentity%2Fidentity%2FREADME.png)