Merge pull request #180326 from ProbablePrime/rifox/editorial-token-quickstart

Editorial pass of access tokens quick start

Author: v-shils

articles/communication-services/quickstarts/access-tokens.md

@@ -7,7 +7,7 @@ manager: nmurav
 services: azure-communication-services
 
 ms.author: tchladek
-ms.date: 06/30/2021
+ms.date: 11/17/2021
 ms.topic: quickstart
 ms.service: azure-communication-services
 ms.subservice: identity
@@ -16,24 +16,26 @@ zone_pivot_groups: acs-js-csharp-java-python
 
 # Quickstart: Create and manage access tokens
 
-Get started with Azure Communication Services by using the Communication Services Identity SDK. It allows you to create identities and manage your access tokens. Identity is representing entity of your application in the Azure Communication Service (for example, user or device). Access tokens let your Chat and Calling SDKs authenticate directly against Azure Communication Services. We recommend generating access tokens on a server-side service. Access tokens are then used to initialize the Communication Services SDKs on client devices.
+Access tokens let ACS SDKs [authenticate](../concepts/authentication.md) directly against Azure Communication Services as a particular identity. You'll need to create some if you want your users to join a call or chat thread within your application. 
+
+You can also use the ACS SDKs to create identities and manage your access tokens and in this quickstart we'll be learning how to do this. For production use cases we recommend generating access tokens on a [server-side service](../concepts/client-and-server-architecture.md).
 
 Any prices seen in images throughout this tutorial are for demonstration purposes only.
 
 ::: zone pivot="programming-language-csharp"
-[!INCLUDE [.NET](./includes/user-access-token-net.md)]
+[!INCLUDE [.NET](./includes/access-tokens/access-token-net.md)]
 ::: zone-end
 
 ::: zone pivot="programming-language-javascript"
-[!INCLUDE [JavaScript](./includes/user-access-token-js.md)]
+[!INCLUDE [JavaScript](./includes/access-tokens/access-token-js.md)]
 ::: zone-end
 
 ::: zone pivot="programming-language-python"
-[!INCLUDE [Python](./includes/user-access-token-python.md)]
+[!INCLUDE [Python](./includes/access-tokens/access-token-python.md)]
 ::: zone-end
 
 ::: zone pivot="programming-language-java"
-[!INCLUDE [Java](./includes/user-access-token-java.md)]
+[!INCLUDE [Java](./includes/access-tokens/access-token-java.md)]
 ::: zone-end
 
 The output of the app describes each action that is completed:

articles/communication-services/quickstarts/includes/user-access-token-java.md renamed to articles/communication-services/quickstarts/includes/access-tokens/access-token-java.md

@@ -6,21 +6,21 @@ author: tomaschladek
 manager: nmurav
 ms.service: azure-communication-services
 ms.subservice: azure-communication-services
-ms.date: 06/30/2021
+ms.date: 11/17/2021
 ms.topic: include
 ms.custom: include file
 ms.author: tchladek
 ---
 
-> [!NOTE]
-> Find the finalized code for this quickstart on [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/access-token-quickstart)
-
 ## Prerequisites
 
 - An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
 - [Java Development Kit (JDK)](/azure/developer/java/fundamentals/java-jdk-install) version 8 or above.
 - [Apache Maven](https://maven.apache.org/download.cgi).
-- A deployed Communication Services resource and connection string. [Create a Communication Services resource](../create-communication-resource.md).
+- A deployed Communication Services resource and connection string. [Create a Communication Services resource](../../create-communication-resource.md).
+
+## Final Code
+Find the finalized code for this quickstart on [GitHub](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/access-token-quickstart).
 
 ## Setting Up
 
@@ -32,9 +32,9 @@ Open your terminal or command window. Navigate to the directory where you'd like
 mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
 ```
 
-You'll notice that the 'generate' task created a directory with the same name as the `artifactId`. Under this directory, the src/main/java directory contains the project source code, the `src/test/java directory` contains the test source, and the `pom.xml` file is the project's Project Object Model, or POM.
+You'll notice that the 'generate' task created a directory with the same name as the `artifactId`. Under this directory, the src/main/java directory contains the project source code, the `src/test/java directory` contains the test source, and the `pom.xml` file is the project's Project Object Model, or POM. This file is used for project configuration parameters.
 
-### Install the package
+### Install the ACS packages
 
 Open the **pom.xml** file in your text editor. Add the following dependency element to the group of dependencies.
 
@@ -46,12 +46,14 @@ Open the **pom.xml** file in your text editor. Add the following dependency elem
 </dependency>
 ```
 
+This will instruct Maven to install the ACS Identity SDK when we use it later on.
+
 ### Set up the app framework
 
 From the project directory:
 
-1. Navigate to the */src/main/java/com/communication/quickstart* directory
-1. Open the *App.java* file in your editor
+1. Navigate to the `/src/main/java/com/communication/quickstart` directory
+1. Open the `App.java` file in your editor
 1. Replace the `System.out.println("Hello world!");` statement
 1. Add `import` directives
 
@@ -81,12 +83,12 @@ public class App
 
 ## Authenticate the client
 
-Instantiate a `CommunicationIdentityClient` with your resource's access key and endpoint. Learn how to [manage your resource's connection string](../create-communication-resource.md#store-your-connection-string). In addition, you can initialize the client with any custom HTTP client the implements the `com.azure.core.http.HttpClient` interface.
+Instantiate a `CommunicationIdentityClient` with your resource's access key and endpoint. Learn how to [manage your resource's connection string](../../create-communication-resource.md#store-your-connection-string). In addition, you can initialize the client with any custom HTTP client that implements the `com.azure.core.http.HttpClient` interface.
 
-Add the following code to the `main` method:
+Add the following code to the `main` method inside `App.java`:
 
 ```java
-// Your can find your endpoint and access key from your resource in the Azure portal
+// You can find your endpoint and access key from your resource in the Azure portal
 String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
 String accessKey = "SECRET";
 
@@ -96,17 +98,17 @@ CommunicationIdentityClient communicationIdentityClient = new CommunicationIdent
         .buildClient();
 ```
 
-You can also provide the entire connection string using the `connectionString()` function instead of providing the endpoint and access key.
+You can also provide the entire connection string using the `connectionString()` method instead of providing the endpoint and access key.
 ```java
-// Your can find your connection string from your resource in the Azure portal
+// Your can find your connection string from your ACS resource in the Azure portal
 String connectionString = "<connection_string>";
 
 CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
     .connectionString(connectionString)
     .buildClient();
 ```
 
-If you have an Azure Active Directory(AD) application set up, see [Use service principals](../identity/service-principal.md), you may also authenticate with AD.
+If you have an Azure Active Directory(Azure AD) application set up, see [Use service principals](../../identity/service-principal.md), you may also authenticate with Azure AD.
 ```java
 String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
 TokenCredential credential = new DefaultAzureCredentialBuilder().build();
@@ -119,16 +121,17 @@ CommunicationIdentityClient communicationIdentityClient = new CommunicationIdent
 
 ## Create an identity
 
-Azure Communication Services maintains a lightweight identity directory. Use the `createUser` method to create a new entry in the directory with a unique `Id`. Store received identity with mapping to your application's users. For example, by storing them in your application server's database. The identity is required later to issue access tokens.
-
+To create access tokens, you'll need an identity. Azure Communication Services maintains a lightweight identity directory. Use the `createUser` method to create a new entry in the directory with a unique `Id`.
 ```java
 CommunicationUserIdentifier user = communicationIdentityClient.createUser();
 System.out.println("\nCreated an identity with ID: " + user.getId());
 ```
 
+The created identity is required later to issue access tokens. You should therefore store any received identities with a mapping to your application's user. For example, by storing them in your application server's database. 
+
 ## Issue access tokens
 
-Use the `getToken` method to issue an access token for already existing Communication Services identity. Parameter `scopes` defines set of primitives, that will authorize this access token. See the [list of supported actions](../../concepts/authentication.md). New instance of parameter `user` can be constructed based on string representation of Azure Communication Service identity.
+Use the `getToken` method to issue an access token for already existing Communication Services identity. The `scopes` parameter defines set of permissions and abilities that this token will be able to perform. See the [list of supported actions](../../../concepts/authentication.md) for valid values. In this case we'll use our user variable created in the previous step to get a token.
 
 ```java
 // Issue an access token with the "voip" scope for a user identity
@@ -139,9 +142,9 @@ String token = accessToken.getToken();
 System.out.println("\nIssued an access token with 'voip' scope that expires at: " + expiresAt + ": " + token);
 ```
 
-## Create an identity and issue token in one call
+## Create an identity and issue token in one request
 
-Alternatively, use the 'createUserAndToken' method to to create a new entry in the directory with a unique `Id` and
+Alternatively, we can use the 'createUserAndToken' method to to create a new entry in the directory with a unique `Id` and
 issue an access token.
 
 ```java
@@ -162,14 +165,14 @@ Access tokens are short-lived credentials that need to be reissued. Not doing so
 To refresh an access token, use the `CommunicationUserIdentifier` object to reissue:
 
 ```java
-// Value existingIdentity represents identity of Azure Communication Services stored during identity creation
+// existingIdentity represents identity of Azure Communication Services stored during identity creation
 CommunicationUserIdentifier identity = new CommunicationUserIdentifier(existingIdentity.getId());
 AccessToken response = communicationIdentityClient.getToken(identity, scopes);
 ```
 
-## Revoke access tokens
+## Revoke an access token
 
-In some cases, you may explicitly revoke access tokens. For example, when an application's user changes the password they use to authenticate to your service. Method `revokeTokens` invalidates all active access tokens, that were issued to the identity.
+In some cases, you may explicitly revoke access tokens. For example, when an application's user changes the password they use to authenticate to your service. The `revokeTokens` method invalidates all active access tokens for a particular user. In this case we'll again use the previously created user.
 
 ```java
 communicationIdentityClient.revokeTokens(user);
@@ -187,7 +190,7 @@ System.out.println("\nDeleted the user identity with ID: " + user.getId());
 
 ## Run the code
 
-Navigate to the directory containing the *pom.xml* file and compile the project by using the following `mvn` command.
+Navigate to the directory containing the `pom.xml` file and compile the project by using the following `mvn` command.
 
 ```console
 mvn compile