本文假設您熟悉如何套用 Kubernetes 資訊清單檔案，以及如何使用 kubectl 指令列工具。詳情請參閱「指令列工具 (kubectl)」。
Active Directory 整合工作流程
Active Directory 整合功能是透過 PostgreSQL 擴充功能 (google_pg_auth) 實作，工作流程如下：
- 使用者登入：使用者透過一般安全性服務應用程式設計介面 (GSSAPI)，使用標準 Active Directory 憑證向 AlloyDB Omni 進行驗證。
- 自動建立角色：如果使用者沒有對應的 PostgreSQL 角色，系統會自動建立一個，例如
CREATE ROLE "user@REALM" WITH LOGIN;。 - LDAP 群組檢查：系統會使用 LDAP 安全地連線至 Active Directory，擷取使用者目前的群組成員資格。
成員資格同步處理：系統會比較使用者的 Active Directory 群組與您設定的對應。
- 如果使用者位於對應的 Active Directory 群組，但不在對應的 PostgreSQL 群組中，系統會授予使用者成員資格。
- 如果使用者不在對應的 PostgreSQL 群組中，但屬於已對應的 Active Directory 群組，系統會撤銷該使用者的成員資格。
登入完成：使用者連線完成，並登入資料庫。使用者的權限取決於所屬的 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 群組支援
如要設定 Active Directory 群組支援，您必須在現有資料庫叢集上套用UserDefinedAuthentication自訂資源。
使用 LDAP 伺服器憑證設定 AlloyDB Omni。套用下列使用者定義的驗證自訂資源資訊清單：
apiVersion: alloydbomni.dbadmin.goog/v1 kind: UserDefinedAuthentication metadata: name: USER_DEFINED_AUTHENTICATION_NAME namespace: DB_CLUSTER_NAMESPACE spec: dbclusterRef: name: DB_CLUSTER_NAME keytabSecretRef: name: KEYTAB_SECRET_NAME pgHbaEntries: PG_HBA_ENTRIES pgIdentEntries: PG_IDENT_ENTRIES ldapConfiguration: enableGroupMapping: true ldapURI: LDAP_URI ldapBaseDN: LDAP_BASE_DN ldapBindDN: LDAP_BIND_DN cacheTTLSeconds: CACHE_TTL_SECONDS ldap_connection_timeout_ms: LDAP_CONNECTION_TIMEOUT ldapBindPasswordSecretRef: name: LDAP_PASSWORD_SECRET_REF ldapsCertificateSecretRef: name: LDAPS_CERT_SECRET_REF allow_unmapped_ad_users: ALLOW_UNMAPPED_AD_USERS請替換下列項目：
USER_DEFINED_AUTHENTICATION_NAME：UserDefinedConfiguration 的名稱，例如DB_CLUSTER_NAME-ad-auth。DB_CLUSTER_NAMESPACE：此備份方案的 Kubernetes 命名空間。 命名空間必須與資料庫叢集的命名空間相符。DB_CLUSTER_NAME：資料庫叢集名稱，這是您在建立叢集時指派的名稱。LDAP_URI：LDAP 伺服器 URI，例如ldaps://ad.example.com:636。LDAP_BASE_DN：LDAP 搜尋的基準 DN。(例如 DC=ad,DC=alloydb,DC=COM)LDAP_BIND_DN：LDAP 繫結使用者的辨別名稱 (DN)。LDAP_PASSWORD_SECRET_REF：參照 Kubernetes 密碼，其中包含 LDAP 密碼。這個密鑰的金鑰必須是password。LDAPS_CERT_SECRET_REF：(選用) 參照具有 LDAPS 憑證的 Kubernetes 密碼。這個密鑰的鍵必須是ldap.crt。CACHE_TTL_SECONDS：(選用) 觸發 LDAP 群組成員資格同步處理前，最長等待時間 (以秒為單位)。預設值為 3600 秒。LDAP_CONNECTION_TIMEOUT：(選用) LDAP 連線逾時時間 (以毫秒為單位)。預設值為 5000 毫秒。ALLOW_UNMAPPED_AD_USERS：(選用) 如果設為true，系統也會允許不屬於任何對應 Active Directory 群組的使用者登入。預設值為false。
請參閱以下範例：
apiVersion: v1 kind: Secret metadata: name: ldaps-secret type: Opaque data: ldap.crt: LDAPS_CERTIFICATE_CONTENT_BASE64_ENCODED --- apiVersion: v1 kind: Secret metadata: name: ldap-password-dbcluster-sample type: Opaque data: password: LDAPS_PASSWORD_CONTENT_BASE64_ENCODED --- apiVersion: v1 kind: Secret metadata: name: db-pw-dbcluster-sample type: Opaque data: dbcluster-sample: POSTGRES_PASSWORD --- apiVersion: alloydbomni.dbadmin.goog/v1 kind: DBCluster metadata: name: dbcluster-sample spec: databaseVersion: 16.8.0 primarySpec: adminUser: passwordRef: name: db-pw-dbcluster-sample resources: memory: 5Gi cpu: 1 disks: - name: DataDisk size: 10Gi --- apiVersion: v1 kind: Secret metadata: name: db-keytab-dbcluster-sample type: Opaque data: krb5.keytab: | DUMMY_KEYTAB --- apiVersion: alloydbomni.dbadmin.goog/v1 kind: UserDefinedAuthentication metadata: name: dbcluster-sample-ad-auth spec: dbclusterRef: name: dbcluster-sample keytabSecretRef: name: db-keytab-dbcluster-sample pgHbaEntries: - hostgssenc all all 0.0.0.0/0 gss - hostgssenc all all ::1/128 gss - hostssl all all 0.0.0.0/0 scram-sha-256 - hostssl all all ::/0 scram-sha-256 ldapConfiguration: enableGroupMapping: true ldapURI: ldaps://ad.alloydb.com:636 ldapBaseDN: DC=ad,DC=alloydb,DC=COM ldapBindDN: read-only-admin@ad.alloydb.com cacheTTLSeconds: 60 ldapBindPasswordSecretRef: name: ldap-password-dbcluster-sample ldapsCertificateSecretRef: name: ldaps-secret
管理群組對應
您可以使用 SQL 函式，建立及管理 Active Directory 群組與 PostgreSQL 角色之間的對應。
登入叢集並載入擴充功能
連線至在 Kubernetes 上執行的 AlloyDB Omni。
export DBPOD=`kubectl get pod --selector=alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}'` kubectl exec -ti $DBPOD -n DB_CLUSTER_NAMESPACE -c database -- 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() 函式，停止該群組的同步處理。如果使用者已是成員，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('S-1-5-21-.....', ''postgres_read_only'');
建立使用者對應
如要將個別 Active Directory 使用者對應至您已建立的 PostgreSQL 角色，請使用 map_ad_user() 函式。
SELECT google_pg_auth.map_ad_user(ad_username TEXT, pg_role_name TEXT);
舉例來說，如要將 quinn@google.com Active Directory 使用者對應至 pg-developers PostgreSQL 角色，請按照下列步驟操作：
SELECT google_pg_auth.map_ad_user('quinn@google.com', ''postgres_read_only'');
移除使用者對應
如要移除現有對應，請使用 unmap_ad_user() 函式。
SELECT google_pg_auth.unmap_ad_user(ad_username TEXT, pg_role_name TEXT);
舉例來說，如要取消將 quinn@google.com Active Directory 使用者對應至 pg-developers PostgreSQL 角色，請按照下列步驟操作：
SELECT google_pg_auth.unmap_ad_user('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 -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 對應至名為 postgres_read_only 的 postgres 角色。這個角色擁有名為「sales」的資料表讀取權限。使用者登入後，即可存取資料表。
root@postgres-client:/# kinit quinnREALM Password for quinn@YOUR.REALM: root@postgres-client:/# psql -h ALLOYDB_SERVER_HOST_NAME -U quinnREALM -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 quinnREALM Password for quinn@YOUR.REALM: root@postgres-client:/# psql -h ALLOYDB_SERVER_HOST_NAME -U quinnREALM -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 驗證成功，使用者仍可順利登入。只有該工作階段的群組成員資格同步處理作業會失敗。