Update FGAM migration documentation (#385)

* Update FGAM migration documentation

* Update pages/authzed/concepts/restricted-api-access.mdx

Co-authored-by: Maria Ines Parnisari <maria.ines.parnisari@authzed.com>

---------

Co-authored-by: Maria Ines Parnisari <maria.ines.parnisari@authzed.com>

Author: tstirrat15

package.json

@@ -56,5 +56,5 @@
     "typescript": "^4.9.5",
     "yaml-loader": "^0.8.1"
   },
-  "packageManager": "pnpm@10.10.0+sha512.d615db246fe70f25dcfea6d8d73dee782ce23e2245e3c4f6f888249fb568149318637dca73c2c5c8ef2a4ca0d5657fb9567188bfab47f566d1ee6ce987815c39"
+  "packageManager": "pnpm@10.17.1"
 }

pages/authzed/concepts/restricted-api-access.mdx

@@ -245,14 +245,63 @@ policy:
 
 If you want to apply a configuration to an existing SpiceDB cluster without downtime, you must conduct an upgrade process with the following steps:
 
-1. Create pre-shared keys that follow the token format for each client of your SpiceDB instance.
-   You should add those to your SpiceDB instance configuration.
-   You can do this by defining multiple PSKs via the ENV or flags as comma separated values.
-2. Update all your clients to use those new PSKs.
-3. Prepare the FGAM configuration YAML.
+1. Create pre-shared keys that follow the Restricted Access Token format for each client of your SpiceDB instance.
+   Using some Bash:
+
+   ```sh
+   # Generate your secret (substitute your preferred method for generating a cryptographically-secure random string here)
+   # This will be a part of the token
+   base64 < /dev/random | head -c64
+   # g2l2/YjC3jFg6FdV080qiqBPvCrlLuc9GcHutgHF4WhVjsg7+AvlqLmoCrJEC68t
+
+   # Hash that secret using sha256sum
+   # This will go in your FGAM configuration as the token hash
+   # NOTE: truncate the trailing spaces and "-". You just want the alphanum characters.
+   echo -n "g2l2/YjC3jFg6FdV080qiqBPvCrlLuc9GcHutgHF4WhVjsg7+AvlqLmoCrJEC68t" | sha256sum
+   # 1d619ac2f5013845c5f2df93add92fc87e88ca6c57d19a77d1b189663f1ff5b0  -
+   
+   # Add the prefix to create the token that you'll supply to your client
+   echo "sdbst_h256_g2l2/YjC3jFg6FdV080qiqBPvCrlLuc9GcHutgHF4WhVjsg7+AvlqLmoCrJEC68t"
+   # sdbst_h256_g2l2/YjC3jFg6FdV080qiqBPvCrlLuc9GcHutgHF4WhVjsg7+AvlqLmoCrJEC68t
+   ```
+
+2. Prepare the FGAM configuration YAML.
+   You'll add the hashes that you generated in the previous step to the `hash` key in the `token` list for each respective token.
    This process heavily depends on what each client needs:
      1. You may want to start with FGAM tokens bound to a admin-like Role, since that's what the original PSKs effectively were.
         This is probably lower risk, and then from there you can move to start trimming down permissions.
      2. Or you may want to move directly to downscoped tokens for your individual services, creating the tokens you need.
         This may be simple if you have few clients, but more complex as the number of clients grow, and with a bigger blast radious of impact on rollout.
-4. Deploy SpiceDB with the new configuration
+   A minimal configuration would look something like:
+
+   ```yaml
+   role:
+     - id: "admin"
+       permission:
+         authzed.v1/CheckPermission: ""
+   service_account:
+     - id: "my_microservice"
+       token:
+         - id: "token_01"
+           hash: "1d619ac2f5013845c5f2df93add92fc87e88ca6c57d19a77d1b189663f1ff5b0"
+   policy:
+     - id: "microservice_with_admin"
+       principal_id: "my_microservice"
+       principal_type: "service_account"
+       roles:
+         - "admin"
+   ```
+
+3. Set the created tokens as valid preshared keys in your SpiceDB instance.
+   You can do this by defining multiple PSKs via the ENV or flags as comma separated values:
+
+   ```sh
+   spicedb serve --grpc-preshared-key="<old_preshared_key>,<new_token_1>,...,<new_token_n>"
+   ```
+
+   Deploy SpiceDB with this new configuration.
+4. Update all your clients to use the new tokens that you've created, according to which token should have which permissions.
+5. Deploy SpiceDB with the new Restricted Access configuration.
+
+Prior to the migration, the keys that your client sends will be treated as preshared keys.
+After the migration, the keys that your client sends will be treated as Restricted Access keys.