將 Active Directory 群組支援功能與 AlloyDB Omni 整合

選取說明文件版本：

本頁面說明如何在 AlloyDB Omni 中設定及管理以 Active Directory 群組為基礎的驗證和授權。Active Directory 群組支援功能可根據使用者在 Active Directory 中的群組成員資格，自動管理 PostgreSQL 角色成員資格，簡化使用者管理作業，並確保權限同步。

詳情請參閱「Active Directory 總覽」。

Active Directory 整合工作流程

Active Directory 整合功能是透過 PostgreSQL 擴充功能 (google_pg_auth) 實作，如下列工作流程所示：

  1. 使用者登入：使用者透過 GSSAPI 使用標準 Active Directory 憑證向 AlloyDB Omni 進行驗證。
  2. 自動建立角色：如果使用者沒有對應的 PostgreSQL 角色，系統會自動建立一個，例如 CREATE ROLE "user@REALM" WITH LOGIN;。
  3. LDAP 群組檢查：系統會使用 LDAP 安全地連線至 Active Directory，擷取使用者目前的群組成員資格。
  4. 成員資格同步：系統會根據您設定的對應關係，比較使用者的 Active Directory 群組。
    • 如果使用者位於對應的 Active Directory 群組中，但不在對應的 PostgreSQL 群組中，系統會授予使用者成員資格。
    • 如果使用者不在對應的 PostgreSQL 群組中，但屬於已對應的 Active Directory 群組，系統就會撤銷該使用者的成員資格。
  5. 登入完成：使用者連線完成，並登入資料庫。使用者的權限取決於所屬的 PostgreSQL 角色，這些角色會與 Active Directory 群組狀態同步。

每次使用者登入時，系統都會自動進行這項同步作業，確保 PostgreSQL 存取權反映 Active Directory 的目前狀態。

事前準備

將 Active Directory 群組支援功能與 AlloyDB Omni 整合前，請確認您符合下列需求。

  • GSSAPI 驗證：您必須為 AlloyDB Omni 執行個體設定並啟用以 GSSAPI 為基礎的驗證。詳情請參閱「整合 Active Directory 與 AlloyDB Omni」。

  • PostgreSQL 群組角色：您必須手動建立要對應至 Active Directory 群組的 PostgreSQL 群組角色，如下列範例所示：

    CREATE ROLE 'postgres_developers';
CREATE ROLE 'postgres_read_only';

  • 權限：您必須手動將資料庫權限 (例如 SELECT 和 INSERT) 指派給這些 PostgreSQL 群組角色。這項整合功能只會管理成員資格，但不會管理群組本身的權限，如下例所示：

    GRANT SELECT ON ALL TABLES IN SCHEMA sales TO postgres_read_only;
GRANT USAGE ON SCHEMA finance TO postgres_developers;
GRANT USAGE ON SCHEMA sales TO postgres_read_only;
GRANT SELECT, INSERT ON finance.transactions TO postgres_developers;

設定 Active Directory 群組支援

如要在 AlloyDB Omni 中設定 Active Directory 群組支援，請啟用 google_pg_auth 擴充功能、在 postgresql.conf 檔案中提供 Active Directory 詳細資料，並安全地處理憑證。

  1. 提供 LDAP 密碼。

    您必須使用 AD_LDAP_PASSWORD 環境變數，將 ldap_bind_dn 服務帳戶的密碼提供給 AlloyDB Omni 容器，如下列範例所示：

    docker run -d --name CONTAINER_NAME \
          -e POSTGRES_PASSWORD=NEW_PASSWORD \
          -e AD_LDAP_PASSWORD=AD_LDAP_PASSWORD \
          -vDATA_DIR:/var/lib/postgresql/data \
          -p HOST_PORT:5432 \
          --restart=always \
          google/alloydbomni:IMAGE_TAG

  2. 啟用 google_pg_auth 擴充功能。

    1. 在 postgresql.conf 檔案中新增或修改下列參數，啟用擴充功能並設定 LDAP 連線。postgresql.conf 檔案位於您啟動 AlloyDB Omni 映像檔時掛接的資料目錄中。

      # ---------------------------------------------------------------------------
# ALLOYDB ACTIVE DIRECTORY INTEGRATION SETTINGS
# ---------------------------------------------------------------------------

google_pg_auth.enable_auth = on
google_pg_auth.ldap_uri = "AD_LDAP_SERVER_HOST"
google_pg_auth.ldap_base_dn = AD_LDAP_BASE_DN
google_pg_auth.ldap_bind_dn = AD_LDAP_BIND_DN
google_pg_auth.auth_cache_ttl_sec = 3600

      請將下列項目改為對應的值：

      • AD_LDAP_SERVER_HOST：Active Directory LDAP 伺服器的 URI，例如 ldap://ad-controller.example.com。
      • ：執行 LDAP 搜尋的基準辨別名稱 (DN)，例如 DC=example,DC=com。AD_LDAP_BASE_DN
      • ：Active Directory 使用者帳戶的辨別名稱 (DN)，AlloyDB Omni 會使用這個帳戶連線並執行 LDAP 搜尋，例如 setupadmin@ad-example.com。AD_LDAP_BIND_DN
      • auth_cache_ttl_sec 是指 AlloyDB Omni 為每位使用者快取資料的時間，之後 AlloyDB Omni 會再次嘗試連線至 LDAP 伺服器。auth_cache_ttl_sec 的值範圍為 60 秒到 86400 秒 (24 小時)。

    2. 在 postgresql.conf 中，將 google_pg_auth 新增至 shared_preload_libraries 參數。

    3. 在 postgresql.conf 檔案中新增下列程式碼：

      shared_preload_libraries='google_pg_auth,google_columnar_engine,google_job_scheduler,google_storage'

    4. 重新啟動資料庫。

      docker restart CONTAINER_NAME

  3. 設定 LDAPS 憑證。

    如要確保透過 LDAPS 安全連線至 Active Directory 伺服器，您需要 CA 憑證。

    將 LDAPS 憑證檔案放在 AlloyDB Omni 映像檔中下列預先定義的位置：/etc/ldap/ldap.crt。

管理群組對應

您可以使用 SQL 函式，建立及管理 Active Directory 群組與 PostgreSQL 角色之間的對應關係。

登入叢集並載入擴充功能

docker exec -it CONTAINER_NAME psql -h localhost -U postgres
postgres=# CREATE EXTENSION google_pg_auth;
CREATE EXTENSION

建立群組對應

如要將 Active Directory 群組對應至您已建立的 PostgreSQL 群組角色，請使用 map_ad_group() 函式：

SELECT google_pg_auth.map_ad_group(ad_group_name TEXT, ad_group_sid TEXT, pg_role_name TEXT);

舉例來說，如要將 ad-developers Active Directory 群組對應至 pg-developers PostgreSQL 角色，請使用下列指令：

SELECT google_pg_auth.map_ad_group('ad-developers', 'S-1-5-21-.....', 'postgres_read_only');

如要擷取 Active Directory 中特定群組的 SID，請在 Active Directory 伺服器上使用下列指令：

C:\Users\Admin> Get-ADGroup -Identity ad-developers | select SID

             SID
-----------------------------------------------
S-1-5-21-3168537779-1985441202-1799118680-1612

移除群組對應

如要移除現有對應，請使用 unmap_ad_group() 函式。這個函式會停止該群組的同步作業，但如果使用者已是 PostgreSQL 群組的成員，則不會移除。

SELECT google_pg_auth.unmap_ad_group(ad_group_sid TEXT, pg_role_name TEXT);

請參閱以下範例：

SELECT google_pg_auth.unmap_ad_group('quinn@google.com', 'postgres_read_only');

連線至 AlloyDB Omni 資料庫

使用 Active Directory 使用者登入 AlloyDB Omni 資料庫。您必須在連線的用戶端中啟用 kinit。

在下列範例中，postgres-client Pod 已安裝 kinit 和 psql，並設定為使用 psql 用戶端連線至 AlloyDB Omni 叢集。

root@postgres-client:/# kinit AD_USER_NAME
Password for user1REALM:

root@postgres-client:/# psql -h ALLOYDB_SERVER_HOST_NAME -U AD_USER_NAME@REALM -d postgres
psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 16.3)
GSSAPI-encrypted connection
Type "help" for help.

user1=#

系統會根據下列項目，自動決定您在 AlloyDB Omni 資料庫中的存取權：

  • 您目前在 Active Directory 群組中的成員資格。
  • 管理員在這些 Active Directory 群組和 PostgreSQL 角色之間定義的對應。
  • 管理員授予這些 PostgreSQL 角色的權限。

如果是首次連線，系統會自動建立 PostgreSQL 使用者角色 (your_ad_user@YOURDOMAIN.COM)。

每次登入時，系統都會檢查您目前的 Active Directory 群組成員資格，並更新對應的 PostgreSQL 角色成員資格。您不必採取任何特定行動，系統就會進行同步。

資料庫連線範例

舉例來說，假設使用者 Quinn 隸屬於名為 ad_developers 的 Active Directory 群組。管理員已將 ad_developers 對應至名為 pg_read_only 的 postgres 角色。這個角色擁有名為 sales 的資料表讀取權限。使用者登入後，即可存取資料表。

root@postgres-client:/# kinit quinn@REALM
Password for quinn@YOUR.REALM:

root@postgres-client:/# psql -h ALLOYDB_SERVER_HOST_NAME -U quinn@REALM -d postgres
psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 16.3)
GSSAPI-encrypted connection
Type "help" for help.

postgres=# select * from sales;
// Query will be run successfully

在下列範例中，Quinn 會從 Active Directory 的 ad_developers 群組中移除：

root@postgres-client:/# kinit quinn@REALM
Password for quinn@YOUR.REALM:

root@postgres-client:/# psql -h ALLOYDB_SERVER_HOST_NAME -U quinn@REALM -d postgres
psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 16.3)
GSSAPI-encrypted connection
Type "help" for help.

postgres=# select * from sales;
// Query will fail

限制

  • 手動管理群組和權限：這項功能只會自動管理現有 PostgreSQL 群組中的使用者成員資格。建立這些群組及授予權限仍須手動管理。
  • 同步處理延遲：只有在使用者登入時，系統才會同步處理成員資格。 在 Active Directory 中變更使用者群組成員資格後，只有在使用者下次登入時，AlloyDB Omni 才會反映這些變更。
  • 效能：LDAP 查詢會在初始使用者登入程序中增加少量延遲。快取有助於在設定的存留時間 (auth_cache_ttl_sec) 內，減少後續登入的延遲時間。
  • 錯誤處理：如果無法連上 LDAP 伺服器，或在同步處理程序期間發生其他錯誤，AlloyDB Omni 會記錄錯誤。不過，由於 GSSAPI 驗證成功，使用者仍可順利登入。只有該工作階段的群組成員資格同步處理作業會失敗。

後續步驟