docs(nx-cloud): add new documentation for PATs and emphasise Access Tokens are for CI (#27227)

- adds a new Personal Access Tokens page
- updates the existing Access Tokens page to emphasise they're more for
CI
- adds `nx-cloud login` reference
- adds `nx-cloud configure` reference

---------

Co-authored-by: lourw <[email protected]>

Author: catfireparty

docs/generated/cli/login.md

@@ -1,11 +1,11 @@
 ---
 title: 'login - CLI command'
-description: 'Login to Nx Cloud.'
+description: 'Login to Nx Cloud. This command is an alias for [`nx-cloud login`](/ci/reference/nx-cloud-cli#npx-nxcloud-login).'
 ---
 
 # login
 
-Login to Nx Cloud.
+Login to Nx Cloud. This command is an alias for [`nx-cloud login`](/ci/reference/nx-cloud-cli#npx-nxcloud-login).
 
 ## Usage
 

docs/generated/cli/logout.md

@@ -1,11 +1,11 @@
 ---
 title: 'logout - CLI command'
-description: 'Logout from Nx Cloud.'
+description: 'Logout from Nx Cloud. This command is an alias for [`nx-cloud logout`](/ci/reference/nx-cloud-cli#npx-nxcloud-logout).'
 ---
 
 # logout
 
-Logout from Nx Cloud.
+Logout from Nx Cloud. This command is an alias for [`nx-cloud logout`](/ci/reference/nx-cloud-cli#npx-nxcloud-logout).
 
 ## Usage
 

docs/generated/manifests/ci.json

@@ -560,7 +560,7 @@
           },
           {
             "id": "access-tokens",
-            "name": "Access Tokens",
+            "name": "CI Access Tokens",
             "description": "",
             "mediaImage": "",
             "file": "nx-cloud/recipes/access-tokens",
@@ -569,6 +569,17 @@
             "path": "/ci/recipes/security/access-tokens",
             "tags": []
           },
+          {
+            "id": "personal-access-tokens",
+            "name": "Personal Access Tokens",
+            "description": "",
+            "mediaImage": "",
+            "file": "nx-cloud/recipes/personal-access-tokens",
+            "itemList": [],
+            "isExternal": false,
+            "path": "/ci/recipes/security/personal-access-tokens",
+            "tags": []
+          },
           {
             "id": "encryption",
             "name": "Enable End to End Encryption",
@@ -1056,7 +1067,7 @@
       },
       {
         "id": "access-tokens",
-        "name": "Access Tokens",
+        "name": "CI Access Tokens",
         "description": "",
         "mediaImage": "",
         "file": "nx-cloud/recipes/access-tokens",
@@ -1065,6 +1076,17 @@
         "path": "/ci/recipes/security/access-tokens",
         "tags": []
       },
+      {
+        "id": "personal-access-tokens",
+        "name": "Personal Access Tokens",
+        "description": "",
+        "mediaImage": "",
+        "file": "nx-cloud/recipes/personal-access-tokens",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/ci/recipes/security/personal-access-tokens",
+        "tags": []
+      },
       {
         "id": "encryption",
         "name": "Enable End to End Encryption",
@@ -1094,7 +1116,7 @@
   },
   "/ci/recipes/security/access-tokens": {
     "id": "access-tokens",
-    "name": "Access Tokens",
+    "name": "CI Access Tokens",
     "description": "",
     "mediaImage": "",
     "file": "nx-cloud/recipes/access-tokens",
@@ -1103,6 +1125,17 @@
     "path": "/ci/recipes/security/access-tokens",
     "tags": []
   },
+  "/ci/recipes/security/personal-access-tokens": {
+    "id": "personal-access-tokens",
+    "name": "Personal Access Tokens",
+    "description": "",
+    "mediaImage": "",
+    "file": "nx-cloud/recipes/personal-access-tokens",
+    "itemList": [],
+    "isExternal": false,
+    "path": "/ci/recipes/security/personal-access-tokens",
+    "tags": []
+  },
   "/ci/recipes/security/encryption": {
     "id": "encryption",
     "name": "Enable End to End Encryption",

docs/generated/manifests/menus.json

@@ -5694,13 +5694,21 @@
                 "disableCollapsible": false
               },
               {
-                "name": "Access Tokens",
+                "name": "CI Access Tokens",
                 "path": "/ci/recipes/security/access-tokens",
                 "id": "access-tokens",
                 "isExternal": false,
                 "children": [],
                 "disableCollapsible": false
               },
+              {
+                "name": "Personal Access Tokens",
+                "path": "/ci/recipes/security/personal-access-tokens",
+                "id": "personal-access-tokens",
+                "isExternal": false,
+                "children": [],
+                "disableCollapsible": false
+              },
               {
                 "name": "Enable End to End Encryption",
                 "path": "/ci/recipes/security/encryption",
@@ -6056,13 +6064,21 @@
             "disableCollapsible": false
           },
           {
-            "name": "Access Tokens",
+            "name": "CI Access Tokens",
             "path": "/ci/recipes/security/access-tokens",
             "id": "access-tokens",
             "isExternal": false,
             "children": [],
             "disableCollapsible": false
           },
+          {
+            "name": "Personal Access Tokens",
+            "path": "/ci/recipes/security/personal-access-tokens",
+            "id": "personal-access-tokens",
+            "isExternal": false,
+            "children": [],
+            "disableCollapsible": false
+          },
           {
             "name": "Enable End to End Encryption",
             "path": "/ci/recipes/security/encryption",
@@ -6083,13 +6099,21 @@
         "disableCollapsible": false
       },
       {
-        "name": "Access Tokens",
+        "name": "CI Access Tokens",
         "path": "/ci/recipes/security/access-tokens",
         "id": "access-tokens",
         "isExternal": false,
         "children": [],
         "disableCollapsible": false
       },
+      {
+        "name": "Personal Access Tokens",
+        "path": "/ci/recipes/security/personal-access-tokens",
+        "id": "personal-access-tokens",
+        "isExternal": false,
+        "children": [],
+        "disableCollapsible": false
+      },
       {
         "name": "Enable End to End Encryption",
         "path": "/ci/recipes/security/encryption",

docs/generated/packages/nx/documents/login.md

@@ -1,11 +1,11 @@
 ---
 title: 'login - CLI command'
-description: 'Login to Nx Cloud.'
+description: 'Login to Nx Cloud. This command is an alias for [`nx-cloud login`](/ci/reference/nx-cloud-cli#npx-nxcloud-login).'
 ---
 
 # login
 
-Login to Nx Cloud.
+Login to Nx Cloud. This command is an alias for [`nx-cloud login`](/ci/reference/nx-cloud-cli#npx-nxcloud-login).
 
 ## Usage
 

docs/generated/packages/nx/documents/logout.md

@@ -1,11 +1,11 @@
 ---
 title: 'logout - CLI command'
-description: 'Logout from Nx Cloud.'
+description: 'Logout from Nx Cloud. This command is an alias for [`nx-cloud logout`](/ci/reference/nx-cloud-cli#npx-nxcloud-logout).'
 ---
 
 # logout
 
-Logout from Nx Cloud.
+Logout from Nx Cloud. This command is an alias for [`nx-cloud logout`](/ci/reference/nx-cloud-cli#npx-nxcloud-logout).
 
 ## Usage
 

docs/map.json

@@ -1766,10 +1766,15 @@
                   "file": "nx-cloud/recipes/google-auth"
                 },
                 {
-                  "name": "Access Tokens",
+                  "name": "CI Access Tokens",
                   "id": "access-tokens",
                   "file": "nx-cloud/recipes/access-tokens"
                 },
+                {
+                  "name": "Personal Access Tokens",
+                  "id": "personal-access-tokens",
+                  "file": "nx-cloud/recipes/personal-access-tokens"
+                },
                 {
                   "name": "Enable End to End Encryption",
                   "id": "encryption",

docs/nx-cloud/concepts/cache-security.md

@@ -22,9 +22,15 @@ If a malicious actor were able to modify the cache and those output files were t
 
 In order to keep your cache secure, there are a few steps we recommend you take:
 
-### Specify a Read-Only Token in `nx.json`
+### Use Personal Access Tokens to Provide Fine-Grained Access Control for Local Development
 
-The [token you specify](/ci/recipes/security/access-tokens) for the `nxCloudAccessToken` property in `nx.json` is visible to anyone who can view your codebase. If this token was a read-write token someone who doesn't even have permission to create a PR could still add entries to the remote cache, which would then be used on other developer's machines and in CI.
+When you use a [personal access token](/ci/recipes/security/personal-access-tokens) to connect to Nx Cloud, you can control the level of access that your developers have to the cache after they authenticate by logging in. By default, all personal access tokens have read-only access to the cache. If you need to give a developer write access to the cache, you can do so in the workspace settings of the Nx Cloud UI.
+
+You can strengthen your workspace security further by revoking all access to the cache for unauthenticated users. This is done by changing the ID Access Level in your workspace settings. By default this is set to `read-only`, but you can change it to `none` to prevent all access.
+
+### Avoid using CI Access Tokens in `nx.json`
+
+While you can [specify a token](/ci/recipes/security/access-tokens) with the `nxCloudAccessToken` property in `nx.json`, this is visible to anyone who can view your codebase. A read-write token would give someone who may not even have permission to create a PR the access to add entries to the remote cache, which would then be used on other developer's machines and in CI. We recommend you restrict CI Access Tokens to CI use only and rely on [personal access tokens](/ci/recipes/security/personal-access-tokens) for local development instead.
 
 ### Use a Read-Write Token in CI
 

docs/nx-cloud/recipes/access-tokens.md

@@ -1,31 +1,31 @@
-# Nx CLI and Access Tokens
+# Nx CLI and CI Access Tokens
 
-The permissions and membership define what developers can access on [Nx Cloud](https://nx.app). They don't affect what happens when you run Nx commands locally or on CI. To manage that, you need to provision access tokens. To do that, go to Workspace Options / Manage Access Tokens.
+The permissions and membership define what developers can access on nx.app but they don't affect what happens when you run Nx commands in CI. To manage that, you need to provision CI access tokens in Workspace settings / Manage CI access tokens.
 
-## Types of Access Tokens
+## Access Types
 
 {% callout type="warning" title="Use Caution With Read-Write Tokens" %}
-Read-write tokens allow full write access to your remote cache. They should only be used in trusted environments. For instance, open source projects should only use read-write tokens as secrets configured for protected branches (e.g, main). Read-only tokens should be used in all other cases.
+Read-write tokens allow full write access to your remote cache. They should only be used in trusted environments.
 {% /callout %}
 
-There are currently two (2) types of Access Tokens for Nx Cloud's runner that you can use on your workspace. Both tokens support distributed task execution and allow Nx Cloud to store metadata about runs.
+There are currently two (2) types of CI Access Token for Nx Cloud's runner that you can use with your workspace. Both support distributed task execution and allow Nx Cloud to store metadata about runs.
 
 - `read-only`
 - `read-write`
 
-### Access Tokens: Read Only
+### Read Only Access
 
-The `read-only` access tokens will only read from the remote cache. Task results will not be stored in the remote cache for other developers to use.
+The `read-only` access tokens will only read from the remote cache. Task results will not be stored in the remote cache for other machines or CI pipelines to use.
 
-### Access Tokens: Read & Write
+### Read & Write Access
 
-The `read-write` access tokens allows task results to be stored in the remote cache for other developers to download and replay on their machines.
+The `read-write` access tokens allows task results to be stored in the remote cache for other other machines or CI pipelines to download and replay.
 
-## Setting Access Tokens
+## Setting CI Access Tokens
 
-Let's see how access tokens work.
+You can configure an access token in CI by setting the `NX_CLOUD_ACCESS_TOKEN` environment variable. `NX_CLOUD_ACCESS_TOKEN` takes precedence over any value in your `nx.json`.
 
-If you open your `nx.json`, you will see something like this:
+We do not recommend that you commit an access token to your repository but older versions of Nx do support this and if you open your `nx.json`, you may see something like this:
 
 {% tabs %}
 {% tab label="Nx >= 17" %}
@@ -40,24 +40,24 @@ If you open your `nx.json`, you will see something like this:
 {% tab label="Nx < 17" %}
 
 ```json
-"tasksRunnerOptions": {
+{
+  "tasksRunnerOptions": {
     "default": {
       "runner": "nx-cloud",
       "options": {
         "accessToken": "SOMETOKEN"
       }
     }
   }
+}
 ```
 
 {% /tab %}
 {% /tabs %}
 
-If you remove the `nxCloudAccessToken` or `accessToken` property from the configuration, the runner will run all commands as if you were not connected to Nx Cloud. This essentially turns off Nx Cloud.
-
-## Setting a Different Access Token in CI
-
-You can also configure the access token by setting the `NX_CLOUD_ACCESS_TOKEN` environment variable. `NX_CLOUD_ACCESS_TOKEN` takes precedence over the `accessToken` property. It's common to have a read-only token stored in `nx.json` and a read-write token set via `NX_CLOUD_ACCESS_TOKEN` in CI.
+{% callout type="warning" title="Nx Cloud authentication is changing" %}
+From Nx 19.7 new workspaces are connected to Nx Cloud with a property called `nxCloudId` instead, and we recommend developers use [`nx-cloud login`](/ci/reference/nx-cloud-cli#npx-nxcloud-login) to provision their own local [personal access tokens](/ci/recipes/security/personal-access-tokens).
+{% /callout %}
 
 ## Using `nx-cloud.env`
 

docs/nx-cloud/recipes/personal-access-tokens.md

@@ -0,0 +1,55 @@
+# Nx Cloud and Personal Access Tokens
+
+From Nx 19.7 repositories are connected to Nx Cloud via a property in `nx.json` called `nxCloudId`. By default this value allows anyone who clones the repository `read-only` access to Nx Cloud features for that workspace. These permissions can be updated in the workspace settings. To disallow access to anonymous users or allow `read-write` access to known users it is required that all users provision their own personal access token. To do that they need to use [`npx nx-cloud login`](/ci/reference/nx-cloud-cli#npx-nxcloud-login).
+
+{% callout type="warning" title="Personal Access Tokens require the `nxCloudId` field in `nx.json`" %}
+Ensure that you have the `nxCloudId` property in your `nx.json` file to connect to Nx Cloud with a Personal Access Token. If you have been using `nxCloudAccessToken`, you can convert it to `nxCloudId` by running [`npx nx-cloud convert-to-nx-cloud-id`](/ci/reference/nx-cloud-cli#npx-nxcloud-converttonxcloudid).
+{% /callout %}
+
+{% tabs %}
+{% tab label="Nx >= 19.7" %}
+
+```json {% fileName="nx.json" %}
+{
+  "nxCloudId": "SOMEID"
+}
+```
+
+{% /tab %}
+{% tab label="Nx <= 19.6" %}
+
+```json {% fileName="nx.json" %}"
+"tasksRunnerOptions": {
+    "default": {
+      "runner": "nx-cloud",
+      "options": {
+        "nxCloudId": "SOMEID"
+      }
+    }
+  }
+```
+
+To utilize personal access tokens and Nx Cloud ID with Nx <= 19.6, the nx-cloud npm package is also required to be installed in your workspaces `package.json`.
+
+```json {% fileName="package.json" %}"
+{
+  "devDependencies": {
+    "nx-cloud": "latest"
+  }
+}
+```
+
+{% /tab %}
+{% /tabs %}
+
+## Personal Access Tokens (PATs)
+
+When you run [`npx nx-cloud login`](/ci/reference/nx-cloud-cli#npx-nxcloud-login) you will be directed to the Nx Cloud app where you will be required to create an account and login. A new personal access token will be provisioned and saved in a local configuration file in your home folder (the location of this will be displayed when login is complete and varies depending on OS).
+
+## Permissions
+
+By default all personal access tokens have `read-only` local access to Nx Cloud features for the workspace in which that user is a member. This can be updated to `read-write` in the workspace settings if required, although it is typical for local access to be restricted to `read-only`.
+
+## Better Security
+
+Without an access token committed to your `nx.json` file you gain more fine-grained control over who has access to your cache artifacts and who can utilise Nx Cloud features that you pay for. When you remove a member from your organization they will immediately lose access to all Nx Cloud features saving you the trouble of needing to cycle any tokens you were previously committing to the repository.