docs: Add HCPb grants issue and fix (#5746) (#5760)

* docs: Add HCPb grants issue and fix

* docs: Add important change, revise alertbox

* docs: Updates based on review feedback

* docs: Updates based on review feedback

* docs: Rephrase reference to fix

* docs: Update date of fix

* docs: Update transparent sessions configuration topic

website/content/docs/api-clients/client-agent.mdx

@@ -58,8 +58,7 @@ $ boundary client-agent sessions
 
 ### Grants
 
-The default grants that Boundary creates for anonymous and authenticated users are sufficient to get started with the Client Agent for the public beta.
-However, in a production scenario, you may want to provide the least amount of privileges necessary for users.
+In a production environment, you may want to provide the least amount of privileges necessary for users.
 For a Boundary user to be able to use the Client Agent to establish a transparent session, they must:
 
 - be able to authenticate using an auth method.
@@ -76,12 +75,28 @@ type=auth-token;ids=*;actions=read:self
 
 HashiCorp highly recommends that you also grant users the permission to list resolvable aliases, as the Client Agent periodically fetches a list of aliases to match incoming DNS requests against.
 Without that permission, every DNS request on the system is sent to the Boundary controller, which can easily overwhelm it.
+
 You can use the following grant string to grant the permission to list resolvable aliases:
 
 ```
 type=user;ids=*;actions=list-resolvable-aliases
 ```
 
+<Warning>
+
+A known issue regarding how grants were previously created in HCP Boundary may cause you to receive a 500 error when you attempt to list resolvable aliases.
+Clusters created before April 26, 2025 may be missing the following grants:
+
+   `ids={{.User.Id}};type=user;actions=list-resolvable-aliases`
+
+   `ids=*;type=target;actions=list,read`
+
+If your cluster is missing these grants, HashiCorp recommends adding them.
+
+For more information, refer to the [known issue](/boundary/docs/release-notes/v0_19_0#hcp-grants).
+
+</Warning>
+
 ## Configuration
 
 The default configuration included with the Boundary Client Agent upon installation will be suitable for most users. If you want to make changes to the configuration, the configuration file is located in the following directory:

website/content/docs/commands/database/init.mdx

@@ -115,6 +115,8 @@ The default value is `false`.
 - `-skip-host-resources-creation` - If not set, skips the creation of host resources as part of the initialization, inlcuding host catalog, host set, and hosts.
 The default value is `false`.
 
+- `-skip-initial-authenticated-user-role-creation` - If set, skips the creation of the role and grants that are provisioned by default for all authenticated users.
+
 - `-skip-initial-login-role-creation` - If not set, skips the creation of a default role allowing necessary grants for logging in as part of initialization.
 If you set this value, the recovery KMS is required to perform any actions.
 The default value is `false`.

website/content/docs/configuration/target-aliases/transparent-sessions.mdx

@@ -19,6 +19,24 @@ Before you configure transparent sessions, you must:
 - Download the appropriate Boundary installer for your Windows or MacOS environment from the [Install Boundary](/boundary/install#installer) page or the [releases](https://releases.hashicorp.com/boundary-installer) page.
 - Ensure that both IPv4 and IPv6 protocols are enabled for your environment. The [Client Agent](/boundary/docs/api-clients/client-agent) requires both protocols to start and perform DNS lookups.
 
+Once Boundary is installed, you should make sure you have the appropriate grants configured so that you can resolve aliases and establish transparent sessions.
+For more information, refer to the [Grants](/boundary/docs/api-clients/client-agent#grants) section in the Client Agent documentation.
+
+   <Warning>
+
+   A known issue regarding how grants were previously created in HCP Boundary may cause you to receive a 500 error when you attempt to list resolvable aliases.
+   Clusters created before April 26, 2025 may be missing the following grants:
+
+   `ids={{.User.Id}};type=user;actions=list-resolvable-aliases`
+
+   `ids=*;type=target;actions=list,read`
+
+   If your cluster is missing these grants, HashiCorp recommends adding them.
+
+   For more information, refer to the [known issue](/boundary/docs/release-notes/v0_19_0#hcp-grants).
+
+   </Warning>
+
 ## Install the Boundary clients
 
 Complete the following steps to install the Boundary Client Agent, CLI, and Desktop client:
@@ -41,11 +59,13 @@ The following section details how to configure targets and test the transparent
 
 <Tip>
 
-  If you use a cluster that was created earlier than release 0.16.0, you must add the grant `list-resolvable-aliases` so that the client agent can populate the local alias cache.
+If you use a cluster that was created earlier than release 0.16.0, you must add the grant `list-resolvable-aliases` so that the client agent can populate the local alias cache.
+
+As an example, you could add the grant:
 
-  As an example, you could add the grant:
+`type=user;actions=list-resolvable-aliases;ids=*`.
 
-  `type=user;actions=list-resolvable-aliases;ids=*`.
+For more information, refer to the [Grants](/boundary/docs/api-clients/client-agent#grants) section in the Client Agent documentation.
 
 </Tip>
 

website/content/docs/release-notes/v0_19_0.mdx

@@ -53,6 +53,19 @@ description: >-
     </td>
   </tr>
 
+  <tr>
+    <td style={{verticalAlign: 'middle'}}>
+    Error when sending requests to aliases using HCP Boundary
+    </td>
+    <td style={{verticalAlign: 'middle'}}>
+    A known issue that was caused by the way default grants were previously configured in HCP Boundary could cause you to receive 500 errors when you attempted to list resolvable aliases. The issue has been resolved. Any clusters that you created on or after April 26, 2025 should not have the issue.
+    <br /><br />
+    You can add grants to resolve the error for any older clusters that exhibit this behavior.
+    <br /><br />
+    Learn more:&nbsp; <a href="#hcp-grants">Known issues and breaking changes </a>
+    </td>
+  </tr>
+
   </tbody>
 </table>
 
@@ -289,5 +302,35 @@ description: >-
     </td>
   </tr>
 
+  <tr id="hcp-grants">
+    <td style={{verticalAlign: 'middle'}}>
+    0.19.0
+    <br /><br />
+    (Fixed in 0.19.2)
+    </td>
+    <td style={{verticalAlign: 'middle'}}>
+    500 error when attempting to list resolvable aliases
+    </td>
+    <td style={{verticalAlign: 'middle'}}>
+    In HCP Boundary, you may receive a 500 error when you attempt to list resolvable aliases. This is a known issue that is caused by the way default grants were previously configured in HCP Boundary. The issue has been resolved, and any clusters that were created on or after April 26, 2025 should not have the issue.
+    <br /><br />
+    For any clusters created before April 26, 2025, you can add grants to resolve the error:
+    <ol>
+    <li>Create a role in the <code>global</code> scope and assign it to the <code>u_auth</code> user.</li>
+    <li>Configure the role to apply to all <code>descendants</code> in the <code>global</code> scope.</li> <li>Assign the following grants to the role:
+    <br /><br />
+    <code>ids=&#123;&#123;.User.Id&#125;&#125;;type=user;actions=list-resolvable-aliases</code><br />
+    <code>ids=*;type=target;actions=list,read</code>
+    </li></ol>
+    Learn more:
+    <ul>
+    <li><a href="/boundary/docs/api-clients/client-agent#grants">Boundary Client Agent grants</a> requirements</li>
+    <li><a href="/boundary/docs/commands/roles/create"><code>roles create</code></a> command documentation</li>
+    <li><a href="/boundary/docs/comands/roles/add-grant-scopes"><code>roles add-grant-scopes</code></a> command documentation</li>
+    <li><a href="/boundary/docs/commands/roles/add-grants"><code>roles add-grants</code></a> command documentation</li>
+    </ul>
+    </td>
+  </tr>
+
   </tbody>
 </table>