将 Active Directory 群组支持与 AlloyDB Omni 集成

选择文档版本：

本页面介绍如何在 AlloyDB Omni 中设置和管理基于 Active Directory 群组的身份验证和授权。基于 Active Directory 群组的支持可根据用户在 Active Directory 中的群组成员资格自动管理 PostgreSQL 角色成员资格，从而简化用户管理并确保权限保持同步。

如需了解详情，请参阅 Active Directory 概览。

Active Directory 集成工作流

Active Directory 集成使用 PostgreSQL 扩展程序 (google_pg_auth) 实现，如以下工作流所示：

  1. 用户登录：用户使用标准 Active Directory 凭证通过 GSSAPI 向 AlloyDB Omni 进行身份验证。
  2. 自动创建角色：如果不存在与用户对应的 PostgreSQL 角色，系统会自动创建一个角色，例如 CREATE ROLE "user@REALM" WITH LOGIN;。
  3. LDAP 群组检查：系统使用 LDAP 安全地连接到您的 Active Directory，以检索用户的当前群组成员资格。
  4. 成员资格同步：系统会将用户的 Active Directory 群组与您配置的映射进行比较。
    • 如果用户属于已映射的 Active Directory 群组，但不属于相应的 PostgreSQL 群组，则系统会授予该用户成员资格。
    • 如果用户不在已映射的 Active Directory 群组中，但在相应的 PostgreSQL 群组中，则系统会撤消该用户的成员资格。
  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';

  • 权限：您必须手动为这些 PostgreSQL 群组角色分配数据库权限，例如 SELECT 和 INSERT。集成功能仅管理成员资格，但不管理群组本身的权限，如以下示例所示：

    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。
      • AD_LDAP_BASE_DN：用于执行 LDAP 搜索的基本标识名 (DN)，例如 DC=example,DC=com。
      • AD_LDAP_BIND_DN：Active Directory 用户账号的标识名 (DN)，AlloyDB Omni 将使用该账号连接并执行 LDAP 搜索，例如 setupadmin@ad-example.com。
      • auth_cache_ttl_sec 指示在 AlloyDB Omni 尝试再次与 LDAP 服务器建立通信之前，经过多长时间后 AlloyDB Omni 便会缓存每个用户的数据。auth_cache_ttl_sec 的值可以介于 60 秒（最小值）到 86,400 秒（24 小时，最大值）之间。

    2. 向 postgresql.conf 中的 shared_preload_libraries 参数添加 google_pg_auth。

    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 身份验证成功，用户仍可成功登录。只有相应会话的群组成员资格同步会失败。

后续步骤