From b8e79f20dcdde75b3dcbce1f085c18e145e7fa68 Mon Sep 17 00:00:00 2001
From: Sheen <65645666+sheensantoscapadngan@users.noreply.github.com>
Date: Wed, 2 Apr 2025 15:50:30 +0000
Subject: [PATCH] misc: improved docs for secret ref and notices
---
.../platform/admin-panel/server-admin.mdx | 2 +-
.../platform/secret-reference.mdx | 27 ++++++++++++-------
2 files changed, 19 insertions(+), 10 deletions(-)
diff --git a/docs/documentation/platform/admin-panel/server-admin.mdx b/docs/documentation/platform/admin-panel/server-admin.mdx
index 137cdde59..aa604e2a5 100644
--- a/docs/documentation/platform/admin-panel/server-admin.mdx
+++ b/docs/documentation/platform/admin-panel/server-admin.mdx
@@ -40,7 +40,7 @@ If you're using SAML/LDAP/OIDC for only one organization on your instance, you c
By default, users signing up through SAML/LDAP/OIDC will still need to verify their email address to prevent email spoofing. This requirement can be skipped by enabling the switch to trust logins through the respective method.
-### Notices
+### Broadcast Messages
Auth consent content is displayed to users on the login page. They can be used to display important information to users, such as a maintenance message or a new feature announcement. Both HTML and Markdown formatting are supported, allowing for customized styling like below:
diff --git a/docs/documentation/platform/secret-reference.mdx b/docs/documentation/platform/secret-reference.mdx
index 119a8cefa..545ed6b3b 100644
--- a/docs/documentation/platform/secret-reference.mdx
+++ b/docs/documentation/platform/secret-reference.mdx
@@ -11,10 +11,11 @@ This means that updating the value of a base secret propagates directly to other
-Since secret referencing works by reconstructing values back on the client side, the client, be it a user, service token, or a machine identity, fetching back secrets
-must be permissioned access to all base and dependent secrets.
+Since secret referencing reconstructs values on the client side, any client (user, service token, or machine identity) fetching secrets must have proper permissions to access all base and dependent secrets. Without sufficient permissions, secret references will not resolve to their appropriate values.
-For example, to access some secret `A` whose values depend on secrets `B` and `C` from different scopes, a client must have `read` access to the scopes of secrets `A`, `B`, and `C`.
+For example, if secret A references values from secrets B and C located in different scopes, the client must have read access to all three scopes containing secrets A, B, and C. If permission to any referenced secret is missing, the reference will remain unresolved, potentially causing application errors or unexpected behavior.
+
+This is an important security consideration when planning your secret access strategy, especially when working with cross-environment or cross-folder references.
### Syntax
@@ -28,11 +29,11 @@ Then consider the following scenarios:
Here are a few more helpful examples for how to reference secrets in different contexts:
-| Reference syntax | Environment | Folder | Secret Key |
-| --------------------- | ----------- | ------------ | ---------- |
-| `${KEY1}` | same env | same folder | KEY1 |
-| `${dev.KEY2}` | `dev` | `/` (root of dev environment) | KEY2 |
-| `${prod.frontend.KEY2}` | `prod` | `/frontend` | KEY2 |
+| Reference syntax | Environment | Folder | Secret Key |
+| ----------------------- | ----------- | ----------------------------- | ---------- |
+| `${KEY1}` | same env | same folder | KEY1 |
+| `${dev.KEY2}` | `dev` | `/` (root of dev environment) | KEY2 |
+| `${prod.frontend.KEY2}` | `prod` | `/frontend` | KEY2 |
## Secret Imports
@@ -59,4 +60,12 @@ To reorder a secret import, hover over it and drag the arrows handle to the posi
-
+