[identity] Doc updates for GA (Azure#26787)

KarishmaGhiya · web-flow · commit 17db2d10dc9f · 2023-08-14T17:38:23.000-07:00
diff --git a/sdk/identity/identity/CHANGELOG.md b/sdk/identity/identity/CHANGELOG.md
@@ -1,9 +1,9 @@
 # Release History
 
-## 3.3.0 (2023-08-10)
+## 3.3.0 (2023-08-14)
 
 ### Features Added
--  Enabled support for logging [personally identifiable information](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/PII), required for customer support through the `enableSupportLogging` option on `loggingOptions` under `TokenCredentialOptions`.
+-  Enabled support for logging [personally identifiable information](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/PII), required for customer support through the `enableUnsafeSupportLogging` option on `loggingOptions` under `TokenCredentialOptions`.
 - Continuous Access Evaluation (CAE) is now configurable per-request by setting the `enable_cae` keyword argument to `True` in `get_token`. This applies to user credentials and service principal credentials. ([#26614](https://github.com/Azure/azure-sdk-for-js/pull/26614))
 
 ### Breaking Changes
diff --git a/sdk/identity/identity/README.md b/sdk/identity/identity/README.md
@@ -137,6 +137,12 @@ If used from Node.js, the `DefaultAzureCredential` will attempt to authenticate
 1. **Azure CLI** - If the developer has authenticated an account via the Azure CLI `az login` command, the `DefaultAzureCredential` will authenticate with that account.
 1. **Azure PowerShell** - If the developer has authenticated using the Azure PowerShell module `Connect-AzAccount` command, the `DefaultAzureCredential` will authenticate with that account.
 
+#### Continuation policy
+
+As of version 3.3.0, `DefaultAzureCredential` will attempt to authenticate with all developer credentials until one succeeds, regardless of any errors previous developer credentials experienced. For example, a developer credential may attempt to get a token and fail, so `DefaultAzureCredential` will continue to the next credential in the flow. Deployed service credentials will stop the flow with a thrown exception if they're able to attempt token retrieval, but don't receive one.
+
+This allows for trying all of the developer credentials on your machine while having predictable deployed behavior.
+
 #### Note about `VisualStudioCodeCredential`
 
 Due to a [known issue](https://github.com/Azure/azure-sdk-for-js/issues/20500), `VisualStudioCodeCredential` has been removed from the `DefaultAzureCredential` token chain. When the issue is resolved in a future release, this change will be reverted.
@@ -298,6 +304,10 @@ Not all credentials require this configuration. Credentials that authenticate th
 
 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.
 
+## Continuous Access Evaluation
+
+As of version 3.3.0, accessing resources protected by [Continuous Access Evaluation](https://learn.microsoft.com/azure/active-directory/conditional-access/concept-continuous-access-evaluation) (CAE) is possible on a per-request basis. This can be enabled using the [`GetTokenOptions.enableCae(boolean)` API](https://learn.microsoft.com/javascript/api/@azure/core-auth/gettokenoptions?view=azure-node-latest#@azure-core-auth-gettokenoptions-enablecae). CAE isn't supported for developer credentials.
+
 ## Token caching
 
 Token caching is a feature provided by the Azure Identity library that allows apps to:
@@ -310,69 +320,6 @@ The Azure Identity library offers both in-memory and persistent disk caching. Fo
 
 ## Troubleshooting
 
-### Error handling
-
-Credentials raise `AuthenticationError` when they fail to authenticate. This class has a `message` field which describes why authentication failed. An `AggregateAuthenticationError` will be raised by `ChainedTokenCredential` with an `errors` field containing an array of errors from each credential in the chain.
-
-### Logging
-
-Enabling logging may help uncover useful information about failures.
-
-To see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`.
-You can read this environment variable from the _.env_ file by explicitly specifying a file path:
-
-```javascript
-require("dotenv").config({ path: ".env" });
-```
-
-Alternatively, logging can be enabled at runtime by calling `setLogLevel` from the `@azure/logger` package:
-
-```typescript
-import { setLogLevel } from "@azure/logger";
-
-setLogLevel("info");
-```
-
-In cases where the authenticate code might be running in an environment with more than one credential available,
-the `@azure/identity` package offers a unique form of logging. On the optional parameters for every credential,
-developers can set `allowLoggingAccountIdentifiers` to true in the
-`loggingOptions` to log information specific to the authenticated account after
-each successful authentication, including the Client ID, the Tenant ID, the
-Object ID of the authenticated user, and if possible the User Principal Name.
-
-For example, using the `DefaultAzureCredential`:
-
-```ts
-import { setLogLevel } from "@azure/logger";
-
-setLogLevel("info");
-
-const credential = new DefaultAzureCredential({
-  loggingOptions: { allowLoggingAccountIdentifiers: true },
-});
-```
-
-Once that credential authenticates, the following message will appear in the logs (with the real information instead of `HIDDEN`):
-
-```
-azure:identity:info [Authenticated account] Client ID: HIDDEN. Tenant ID: HIDDEN. User Principal Name: HIDDEN. Object ID (user): HIDDEN
-```
-
-In cases where the user's [Personally Identifiable Information](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/PII) needs to be logged for customer support, developers can set `enableSupportLogging` to true in the
-`loggingOptions`.
-
-For example, using the `DefaultAzureCredential`:
-
-```ts
-import { setLogLevel } from "@azure/logger";
-
-setLogLevel("info");
-
-const credential = new DefaultAzureCredential({
-  loggingOptions: { enableSupportLogging: true },
-});
-```
-
 For assistance with troubleshooting, see the [troubleshooting guide](https://aka.ms/azsdk/js/identity/troubleshoot).
 
 ## Next steps
diff --git a/sdk/identity/identity/TOKEN_CACHING.md b/sdk/identity/identity/TOKEN_CACHING.md
@@ -21,6 +21,10 @@ The in-memory token cache provided by the Azure Identity library:
 
 **Note:** When Azure Identity library credentials are used with Azure service libraries (for example, Azure Blob Storage), the in-memory token caching is active in the `HttpPipeline` layer as well. All `TokenCredential` implementations are supported there, including custom implementations external to the Azure Identity library.
 
+#### Caching cannot be disabled
+
+As there are many levels of cache, it's not possible disable in-memory caching. However, the in-memory cache may be cleared by creating a new credential instance.
+
 ### Persistent token caching
 
 *Persistent disk token caching* is an opt-in feature in the Azure Identity library. The feature allows apps to cache access tokens in an encrypted, persistent storage mechanism. As indicated in the following table, the storage mechanism differs across operating systems.
diff --git a/sdk/identity/identity/TROUBLESHOOTING.md b/sdk/identity/identity/TROUBLESHOOTING.md
@@ -9,11 +9,14 @@ This troubleshooting guide covers the following areas of the Azure Identity clie
 ## Table of contents
 
 - [Handle Azure Identity errors](#handle-azure-identity-errors)
-  - [AuthenticationRequiredError](#authenticationrequirederror)
-  - [CredentialUnavailableError](#credentialunavailableerror)
+  - [AggregateAuthenticationError](#aggregateauthenticationerror) 
   - [AuthenticationError](#authenticationerror)
+  - [AuthenticationRequiredError](#authenticationrequirederror) 
+  - [CredentialUnavailableError](#credentialunavailableerror)
 - [Find relevant information in error messages](#find-relevant-information-in-error-messages)
 - [Enable and configure logging](#enable-and-configure-logging)
+    - [Allow logging identifiers](#allow-logging-identifiers)
+    - [PII Logging](#pii-logging)
 - [Permission issues](#permission-issues)
 - [Troubleshoot default Azure credential authentication issues](#troubleshoot-default-azure-credential-authentication-issues)
 - [Troubleshoot environment credential authentication issues](#troubleshoot-environment-credential-authentication-issues)
@@ -31,11 +34,13 @@ This troubleshooting guide covers the following areas of the Azure Identity clie
 
 ## Handle Azure Identity errors
 
-### AuthenticationRequiredError
+### AggregateAuthenticationError
 
-Errors arising from authentication issues can be thrown on any service client method that makes a request to the service. This is because the token is requested from the credential on the first call to the service and on any subsequent call that needs to refresh the token.
+An `AggregateAuthenticationError` will be raised by `ChainedTokenCredential` with an `errors` field containing an array of errors from each credential in the chain.
 
-To distinguish these failures from failures in the service client, Azure Identity classes throw the `AuthenticationRequiredError`. Details describing the source of the error are provided in the error message. Depending on the application, these errors may or may not be recoverable.
+### AuthenticationError
+
+The `AuthenticationError` is used to indicate a failure to authenticate with Azure Active Directory (Azure AD). The `errorResponse` field contains more details about the specific failure.
 
 ```ts
 import * from "@azure/identity";
@@ -51,20 +56,18 @@ async function main() {
     // Retrieving the properties of the existing keys in that specific Key Vault.
     console.log(await client.listPropertiesOfKeys().next());
   } catch (error) {
-    console.log("Authentication Failed", error.message);
+    console.log("Azure Active Directory service response with error", error.errorResponse);
   }
 }
 
 main();
 ```
 
-### CredentialUnavailableError
-
-The `CredentialUnavailableError` is used to indicate that the credential can't authenticate in the current environment due to lack of required configuration or setup. This error is also used as a signal to chained credential types, such as `DefaultAzureCredential` and `ChainedTokenCredential`, that the chained credential should continue to try other credential types later in the chain. In `ManagedIdentityCredential`, it can also trigger if the authentication endpoint (like the IMDS endpoint) is unavailable.
+### AuthenticationRequiredError
 
-### AuthenticationError
+Errors arising from authentication issues can be thrown on any service client method that makes a request to the service. This is because the token is requested from the credential on the first call to the service and on any subsequent call that needs to refresh the token.
 
-The `AuthenticationError` is used to indicate a failure to authenticate with Azure Active Directory (Azure AD). The `errorResponse` field contains more details about the specific failure.
+To distinguish these failures from failures in the service client, Azure Identity classes throw the `AuthenticationRequiredError`. Details describing the source of the error are provided in the error message. Depending on the application, these errors may or may not be recoverable.
 
 ```ts
 import * from "@azure/identity";
@@ -80,13 +83,17 @@ async function main() {
     // Retrieving the properties of the existing keys in that specific Key Vault.
     console.log(await client.listPropertiesOfKeys().next());
   } catch (error) {
-    console.log("Azure Active Directory service response with error", error.errorResponse);
+    console.log("Authentication Failed", error.message);
   }
 }
 
 main();
 ```
 
+### CredentialUnavailableError
+
+The `CredentialUnavailableError` is used to indicate that the credential can't authenticate in the current environment due to lack of required configuration or setup. This error is also used as a signal to chained credential types, such as `DefaultAzureCredential` and `ChainedTokenCredential`, that the chained credential should continue to try other credential types later in the chain. In `ManagedIdentityCredential`, it can also trigger if the authentication endpoint (like the IMDS endpoint) is unavailable.
+
 ## Find relevant information in error messages
 
 `AuthenticationRequiredError` is thrown when unexpected errors occurred while a credential is authenticating. This can include errors received from requests to the Azure AD Security Token Service (STS) and often contains information helpful to diagnosis. Consider the following `AuthenticationRequiredError` message:
@@ -117,6 +124,13 @@ import { setLogLevel } from "@azure/logger";
 setLogLevel("info");
 ```
 
+Alternatively, you can set the `AZURE_LOG_LEVEL` environment variable to `info`. You can read this environment variable from the _.env_ file by explicitly specifying a file path:
+
+```ts
+import dotenv from "dotenv";
+dotenv.config({path: ".env"});
+```
+
 Consider a scenario in which you have the following environment variables set up either in your environment or _.env_ file:
 
 - `AZURE_TENANT_ID`
@@ -134,6 +148,44 @@ These logging statements indicate that the `EnvironmentCredential` is being used
 
 > CAUTION: Requests and responses in the Azure Identity library contain sensitive information. Precaution must be taken to protect logs when customizing the output to avoid compromising account security.
 
+#### Allow logging identifiers
+
+In cases where the authentication code might be running in an environment with more than one credential available, the `@azure/identity` package offers a unique form of logging. On the optional parameters for every credential, developers can set `allowLoggingAccountIdentifiers` to `true` in the `loggingOptions` to log information specific to the authenticated account after each successful authentication, including the Client ID, the Tenant ID, the Object ID of the authenticated user, and, if possible, the User Principal Name.
+
+For example, using the `DefaultAzureCredential`:
+
+```ts
+import { setLogLevel } from "@azure/logger";
+
+setLogLevel("info");
+
+const credential = new DefaultAzureCredential({
+  loggingOptions: { allowLoggingAccountIdentifiers: true },
+});
+```
+
+Once that credential authenticates, the following message will appear in the logs (with the real information instead of `HIDDEN`):
+
+```
+azure:identity:info [Authenticated account] Client ID: HIDDEN. Tenant ID: HIDDEN. User Principal Name: HIDDEN. Object ID (user): HIDDEN
+```
+
+#### PII logging
+
+In cases where the user's [Personally Identifiable Information](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/PII) needs to be logged for customer support, developers can set `enableUnsafeSupportLogging` to `true` in the `loggingOptions`.
+
+For example, using the `DefaultAzureCredential`:
+
+```ts
+import { setLogLevel } from "@azure/logger";
+
+setLogLevel("info");
+
+const credential = new DefaultAzureCredential({
+  loggingOptions: { enableUnsafeSupportLogging: true },
+});
+```
+
 ## Permission issues
 
 If you're using app registration to authenticate the service, ensure the app registration has the correct permissions and role assignments in the service you want to use. For example, if you want to have access to the Azure App Configuration service through Azure AD, ensure your app registration has the permissions and role assignments for access to Azure AD. You can either be assigned the role directly or be in a group that's assigned the role. The "Contributor" and the "Owner" roles allow you to manage the App Configuration resource. In this case, you can either use "App Configuration Data Owner" directly on the user or the Azure AD group. Alternatively, use "Owner" on the Azure AD group. While the App Configuration data can be accessed using access keys, these keys don't grant direct access to the data using Azure AD.
