[ACR] Token updates

Author: dlepow

articles/container-registry/container-registry-repository-scoped-permissions.md

@@ -62,7 +62,7 @@ The following image shows the relationship between tokens and scope maps.
 
 ### Create token and specify repositories
 
-Create a token using the [az acr token create][az-acr-token-create] command. When creating a token, you can specify one or more repositories and associated actions on each repository. The repositories don't need to be in the registry yet. To create a token by specifying an existing scope map, see the next section.
+Create a token using the [az acr token create][az-acr-token-create] command. When creating a token, you can specify one or more repositories and associated actions on each repository. The repositories don't need to be in the registry yet. To create a token by specifying an existing scope map, see the [next section](#create-token-and-specify-scope-map).
 
 The following example creates a token in the registry *myregistry* with the following permissions on the `samples/hello-world` repo: `content/write` and `content/read`. By default, the command sets the default token status to `enabled`, but you can update the status to `disabled` at any time.
 
@@ -72,7 +72,7 @@ az acr token create --name MyToken --registry myregistry \
   content/write content/read
 ```
 
-The output shows details about the token, including two generated passwords. It's recommended to save the passwords in a safe place to use later for authentication. The passwords can't be retrieved again, but new ones can be generated.
+The output shows details about the token. By default, two passwords are generated. It's recommended to save the passwords in a safe place to use later for authentication. The passwords can't be retrieved again, but new ones can be generated.
 
 ```console
 {
@@ -105,6 +105,9 @@ The output shows details about the token, including two generated passwords. It'
   "type": "Microsoft.ContainerRegistry/registries/tokens"
 ```
 
+> [!NOTE]
+> If you want to regenerate token passwords and set password expiration periods, see [Regenerate token passwords](#regenerate-token-passwords) later in this article.
+
 The output includes details about the scope map the command created. You can use the scope map, here named `MyToken-scope-map`, to apply the same repository actions to other tokens. Or, update the scope map later to change the permissions of the associated tokens.
 
 ### Create token and specify scope map
@@ -128,7 +131,10 @@ az acr token create --name MyToken \
   --scope-map MyScopeMap
 ```
 
-The output shows details about the token, including two generated passwords. It's recommended to save the passwords in a safe place to use later for authentication. The passwords can't be retrieved again, but new ones can be generated.
+The output shows details about the token. By default, two passwords are generated. It's recommended to save the passwords in a safe place to use later for authentication. The passwords can't be retrieved again, but new ones can be generated.
+
+> [!NOTE]
+> If you want to regenerate token passwords and set password expiration periods, see [Regenerate token passwords](#regenerate-token-passwords) later in this article.
 
 ## Create token - portal
 
@@ -137,7 +143,7 @@ You can use the Azure portal to create tokens and scope maps. As with the `az ac
 The following example creates a token, and creates a scope map with the following permissions on the `samples/hello-world` repository: `content/write` and `content/read`.
 
 1. In the portal, navigate to your container registry.
-1. Under **Services**, select **Tokens (Preview) > +Add**.
+1. Under **Repository permissions**, select **Tokens (Preview) > +Add**.
   ![Create token in portal](media/container-registry-repository-scoped-permissions/portal-token-add.png)
 1. Enter a token name.
 1. Under **Scope map**, select **Create new**.
@@ -153,14 +159,12 @@ After the token is validated and created, token details appear in the **Tokens**
 
 ### Add token password
 
-Generate a password after you create a token. To authenticate with the registry, the token must be enabled and have a valid password.
-
-You can generate one or two passwords, and set an expiration date for each one. 
+To use a token created in the portal, you must generate a password. You can generate one or two passwords, and set an expiration date for each one. 
 
 1. In the portal, navigate to your container registry.
-1. Under **Services**, select **Tokens (Preview)**, and select a token.
+1. Under **Repository permissions**, select **Tokens (Preview)**, and select a token.
 1. In the token details, select **password1** or **password2**, and select the Generate icon.
-1. In the password screen, optionally set an expiration date for the password, and select **Generate**.
+1. In the password screen, optionally set an expiration date for the password, and select **Generate**. It's recommended to set an expiration date.
 1. After generating a password, copy and save it to a safe location. You can't retrieve a generated password after closing the screen, but you can generate a new one.
 
     ![Create token password in portal](media/container-registry-repository-scoped-permissions/portal-token-password.png)
@@ -225,7 +229,7 @@ The token doesn't have permissions to the `samples/alpine` repo, so the followin
 docker push myregistry.azurecr.io/samples/alpine:v1
 ```
 
-### Change push/pull permissions
+### Update token permissions
 
 To update the permissions of a token, update the permissions in the associated scope map. The updated scope map is applied immediately to all associated tokens. 
 
@@ -244,7 +248,7 @@ az acr scope-map update \
 In the Azure portal:
 
 1. Navigate to your container registry.
-1. Under **Services**, select **Scope maps (Preview)**, and select the scope map to update.
+1. Under **Repository permissions**, select **Scope maps (Preview)**, and select the scope map to update.
 1. Under **Repositories**, enter `samples/alpine`, and under **Permissions**, select `content/read` and `content/write`. Then select **+Add**.
 1. Under **Repositories**, select `samples/hello-world` and under **Permissions**, deselect `content/write`. Then select **Save**.
 
@@ -279,9 +283,9 @@ az acr scope-map update \
   --add samples/alpine content/delete
 ``` 
 
-To update the scope map using the portal, see the preceding section.
+To update the scope map using the portal, see the [previous section](#update-token-permissions).
 
-Use the following [az acr repository delete][az-acr-repository-delete] command to delete the `samples/alpine` repository. To delete images or repositories, the token doesn't authenticate through `docker login`. Instead, pass the token's name and password to the command. The following example uses the environment variables created earlier in the article:
+Use the following [az acr repository delete][az-acr-repository-delete] command to delete the `samples/alpine` repository. To delete images or repositories, pass the token's name and password to the command. The following example uses the environment variables created earlier in the article:
 
 ```azurecli
 az acr repository delete \
@@ -302,11 +306,11 @@ az acr scope-map update \
   --add samples/hello-world metadata/read 
 ```  
 
-To update the scope map using the portal, see the preceding section.
+To update the scope map using the portal, see the [previous section](#update-token-permissions).
 
 To read metadata in the `samples/hello-world` repository, run the [az acr repository show-manifests][az-acr-repository-show-manifests] or [az acr repository show-tags][az-acr-repository-show-tags] command. 
 
-To read metadata, the token doesn't authenticate through `docker login`. Instead, pass the token's name and password to either command. The following example uses the environment variables created earlier in the article:
+To read metadata, pass the token's name and password to either command. The following example uses the environment variables created earlier in the article:
 
 ```azurecli
 az acr repository show-tags \
@@ -321,6 +325,7 @@ Sample output:
   "v1"
 ]
 ```
+
 ## Manage tokens and scope maps
 
 ### List scope maps
@@ -358,9 +363,9 @@ Use the [az acr token list][az-acr-token-list] command, or the **Tokens (Preview
 az acr token list --registry myregistry --output table
 ```
 
-### Generate passwords for token
+### Regenerate token passwords
 
-If you don't have a token password, or you want to generate new passwords, run the [az acr token credential generate][az-acr-token-credential-generate] command. 
+If you didn't generate a token password, or you want to generate new passwords, run the [az acr token credential generate][az-acr-token-credential-generate] command. 
 
 The following example generates a new value for password1 for the *MyToken* token, with an expiration period of 30 days. It stores the password in the environment variable `TOKEN_PWD`. This example is formatted for the bash shell.