本頁面由英文在 AI 協助下翻譯而成。若兩者有出入,請以英文版本為準。
存取管理
呼叫端存取管理會驗證 StackQL 工作階段的呼叫端,並依據政策授權每個陳述式。它與 Provider 憑證無關,Provider 憑證仍透過下列方式提供:--auth、環境變數或 Provider 工作階段。此功能預設為停用,未啟用此功能的部署行為與先前相同。適用於 StackQL v1.0 及更新版本。
另請參閱:
[ 全域旗標 ] [mcp] [whoami] [groups]
啟用存取管理
啟用存取管理的方式,是以指向 JSON 設定檔的 --access.config 全域旗標啟動 StackQL。此範例以受保護模式啟動互動式 shell;exec 和 mcp 也以相同方式啟用。
stackql --access.config '{"path": "/etc/stackql/access.json"}' shell
--access.config 接受只含單一 path 鍵的 JSON 封套;也接受單純的檔案路徑。設定只在啟動時載入一次,因此請透過受控制的重新啟動來輪替金鑰或政策。
啟用存取管理時,只有 exec、shell、mcp 和 version 可以執行;其他命令(包括 registry)會拒絕執行,而不會繞過受保護的路徑。srv 和 MCP reverse_proxy 伺服器類型也會拒絕執行,因為 PostgreSQL 線路協定的相依套件尚未公開每個連線的驗證證據。SQL AUTH 和 AUTH REVOKE 陳述式在受保護模式下會拒絕執行;請改為透過主機設定佈建 Provider 憑證。受保護的 exec 失敗時,會在顯示錯誤後傳回結束狀態 1。
驗證模式
設定檔會選取一種 type:jwt(省略時的預設值)、bearer、mtls 或 local_os。設定採用嚴格的 JSON:未知的欄位以及屬於其他模式的欄位都會遭拒。所有模式共用相同的 rules 和相同的主體目錄。
JWT
呼叫端出示已簽署的權杖,系統會依據設定中固定的金鑰離線驗證該權杖。最小設定會指定權杖必須帶有的簽發者和受眾,列出一個公開金鑰,並讓 analysts 群組的成員執行讀取陳述式(readers 群組的成員不需要規則即可執行,請參閱政策規則):
{
"type": "jwt",
"issuer": "https://identity.example",
"audience": "stackql",
"keys": [
{"kid": "primary", "algorithm": "EdDSA", "public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"}
],
"rules": [
{"subject": "group:analysts", "resource": "host/sql/read", "action": "execute"}
]
}
簽發者、受眾和公開金鑰都固定在設定中;不使用 OIDC 探索。接受的演算法為 EdDSA、RS256、RS384、RS512、PS256、PS384、PS512、ES256、ES384 和 ES512,且 RSA 金鑰必須至少為 2048 位元。每個金鑰都繫結至其設定的演算法。金鑰 ID 未知、簽章無效、缺少到期時間或已過期、nbf 或 iat 為未來時間,或簽發者或受眾錯誤的權杖都會遭拒。權杖中攜帶的群組宣告和 URL 不會用於信任判斷或目錄成員資格。
靜態 bearer 權杖
呼叫端出示不透明權杖,設定中則列出每個可接受權杖的 SHA-256 摘要,以及該權杖所識別的主旨。這適用於少量且固定的服務身分,也就是不值得為此執行權杖簽發者的情況:
{
"type": "bearer",
"issuer": "local-tokens",
"tokens": [{"subject": "alice", "sha256": "<64 hexadecimal characters: the SHA-256 of the token>"}],
"rules": [{"subject": "group:analysts", "resource": "host/sql/read", "action": "execute"}]
}
設定中只包含每個權杖的 SHA-256 摘要,且摘要必須是唯一的。變更設定的摘要需要重新啟動。
相互 TLS
呼叫端由其在 HTTPS MCP 傳輸方式上出示的用戶端憑證來識別。設定中包含必須簽發該憑證的 CA,並指定由哪一種主體別名保存身分:
{
"type": "mtls",
"issuer": "client-certificates",
"client_ca_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
"certificate_identity": "uri_san",
"rules": [{"subject": "group:analysts", "resource": "host/sql/read", "action": "execute"}]
}
用戶端憑證鏈會依據 client_ca_pem 進行驗證,身分主旨則取自恰好一個所設定種類的 SAN,即 uri_san 或 dns_san。不會退而使用 Common Name。相互 TLS 僅能透過 HTTPS MCP 傳輸方式使用。
本機 OS 身分
不交換任何憑證:主旨是執行 StackQL 處理程序的作業系統身分。設定只需要 issuer 標籤和規則:
{
"type": "local_os",
"issuer": "this-host",
"rules": [{"subject": "group:analysts", "resource": "host/sql/read", "action": "execute"}]
}
身分主旨是 StackQL 處理程序的有效 Unix UID 或 Windows SID,包括沒有 passwd 項目的數字容器 UID。不會出示任何憑證,且會忽略 STACKQL_CALLER_TOKEN。此模式僅限本機:HTTP 呼叫端會遭拒。作業系統群組成員資格不會授予存取權;只有目錄成員資格才會。
工作階段期限
預設情況下,查詢沒有由驗證衍生的期限。每個新的陳述式都會驗證憑證並重新整理目錄成員資格,因此過期的憑證無法啟動新的工作,但到期不會中斷已經獲得授權的陳述式。設定 "enforce_session_deadline": true 可在 max_session_seconds(預設 300,上限 86400)時取消,此時間會因 JWT 或憑證到期而縮短。此設定不會更新權杖。
主體目錄
身分會對應至主體,主體再對應至群組,這些對應存放在所設定 SQLite 或 PostgreSQL 後端的四個資料表中:
| 資料表 | 內容 |
|---|---|
stackql_access_principals | 主體 ID 和字串屬性的 JSON 物件。tenant 屬性會為預覽 IaC 狀態劃分命名空間。 |
stackql_access_identities | 已驗證的 (issuer, subject) 配對對應至主體 ID。 |
stackql_access_groups | 群組 ID。 |
stackql_access_memberships | 主體與群組的繫結。 |
在提供受保護的查詢之前,請透過受信任的資料庫管理連線佈建資料表、身分和成員資格:
INSERT INTO stackql_access_principals (id, attributes) VALUES ('alice', '{}');
INSERT INTO stackql_access_groups (id) VALUES ('readers');
INSERT INTO stackql_access_identities (issuer, subject, principal_id)
VALUES ('https://identity.example', 'alice', 'alice');
INSERT INTO stackql_access_memberships (principal_id, group_id) VALUES ('alice', 'readers');
請使用該模式實際的簽發者和主旨:對於本機 OS 身分,可能是 ('this-host', '1000');對於相互 TLS,則是 ('client-certificates', 'spiffe://example/alice')。請明確選取後端:
stackql --access.config '{"path":"/etc/stackql/access.json"}' \
--sqlBackend '{"dbEngine":"postgres_tcp","dsn":"postgres://runtime@localhost/stackql?sslmode=require","sqlDialect":"postgres"}' \
exec 'SELECT whoami(), groups();'
目錄會為每個陳述式產生不可變的快照。撤銷的方式是在管理連線上執行 DELETE FROM stackql_access_memberships;下一個陳述式就會看到新的快照。未知的身分、缺少 schema、格式錯誤的資料和目錄中斷都會拒絕存取。一般受保護的 SQL 無法存取目錄資料表。請將成員資格的寫入保留在管理連線上、保護資料庫檔案,並在後端支援時,為管理和執行階段使用不同的資料庫權限。
政策規則
每條規則會將一個 resource 上的一個 action 授予格式為 group:<group id> 的 subject。請使用受信任 Provider 文件中已編譯的方法和作業識別碼;作業萬用字元除了讀取之外,也會授予變更方法。
readers 群組隱含擁有主機的安全讀取 SQL 功能。該群組以外的主體進行讀取時需要 host/sql/read,其他陳述式則需要 host/sql/<statement kind> 上的 execute。Provider 作業和憑證的使用一律需要明確的規則,且對集合的授權不會授予其底層方法。其他主機檢查:
| 資源 | 動作 | 範圍 |
|---|---|---|
host/sql/read | execute | 隱含讀取者群組以外的讀取陳述式 |
host/sql/exec | execute | 原生 EXEC,包括巢狀 EXEC |
host/iac/run, host/iac/destroy | execute | 預覽 IaC 關聯,即使它們使用 SELECT 語法 |
host/function/<name> | execute | 不在已知純函式小型允許清單中的函式 |
host/backend | read | 不透明的已儲存和外部後端關聯 |
host/credentials | reload | MCP reload_credentials 工具 |
session/variables | read | 解除參考工作階段變數和祕密 |
session/config | write | SET 和 UNSET |
已儲存查詢的展開會在執行前進行檢查,且受保護的路徑會停用計畫和資料列快取的重複使用。
進入點
| 驗證 | exec, shell, MCP stdio | HTTPS MCP |
|---|---|---|
| JWT | STACKQL_CALLER_TOKEN 環境變數 | Authorization: Bearer 要求標頭 |
| 靜態 bearer | STACKQL_CALLER_TOKEN 環境變數 | Authorization: Bearer 要求標頭 |
| 本機 OS | 有效的處理程序 UID 或 SID;無憑證 | 拒絕 |
| 相互 TLS | 拒絕:沒有已驗證的 TLS 連線 | 已驗證的用戶端憑證鏈和一個設定的 SAN |
請透過處理程序環境提供本機權杖憑證,切勿以 SQL 常值或命令列引數提供。透過 HTTPS 時,呼叫端驗證器會取代 HTTP 用戶端驗證 中所述的共用 auth_token_env_var bearer 管控;伺服器 TLS 憑證和金鑰的設定是必要的,且沒有憑證的要求絕不會退而使用伺服器的環境權杖。
檢查呼叫端
在已驗證的工作階段中,whoami() 會傳回主體 ID,groups() 則以 JSON 陣列傳回目錄群組:
SELECT whoami() AS principal, groups() AS memberships;
|-----------|-------------|
| principal | memberships |
|-----------|-------------|
| alice | ["readers"] |
|-----------|-------------|
這兩個函式都需要以 --access.config 啟動的工作階段。
逐步解說
StackQL 存放庫隨附四個可執行的逐步解說,每種驗證模式各一個,由 Python 指令碼驅動,該指令碼會佈建示範目錄並驗證一個查詢。這些逐步解說不需要雲端帳戶,並由專案的測試套件執行。