在 Snowflake Open Catalog 中配置外部 OAuth¶

本主题介绍如何配置使用 OAuth 的外部服务器访问 Snowflake Open Catalog。

备注

本主题演示如何使用 Auth0 为 Open Catalog 配置外部 OAuth。不过，在 Okta 或 Microsoft Entra ID 中的配置步骤类似。

先决条件¶

在 Open Catalog 账户中创建一个或多个目录。
确保您拥有一个身份提供商 (IdP) 的账户。出于演示目的，本主题使用 Auth0 作为 IdP。要为您的公司或组织创建 Auth0 账户，请访问 https://auth0.com/ (https://auth0.com/)。不过，在 Okta 和 Microsoft Entra ID 中的创建流程相似。
您必须在计算机上安装 Snowflake CLI。
要配置外部 OAuth，您必须在 Open Catalog 中拥有服务管理员角色。有关更多信息，请参阅用户角色。在 Snowflake CLI 中，此角色显示为 POLARIS_ACCOUNT_ADMIN。

准备工作¶

要配置外部 OAuth，您需要为 Open Catalog 创建一个 Snowflake CLI 连接。

要创建此连接，您需要完整的 Open Catalog 账户标识符，其中包括 Snowflake 组织名称和 Open Catalog 账户名称，例如：<orgname>.<my-snowflake-open-catalog-account-name>。

要查找您的 Snowflake 组织名称 (<orgname>)，请参阅 :ref:label-account_name_find。
要查找您的 Snowflake Open Catalog 账户名称 (<my-snowflake-open-catalog-account-name>)，请参阅 :doc:/user-guide/opencatalog/find-account-name。

创建 Snowflake CLI 连接¶

为您的 Open Catalog 账户创建一个 Snowflake CLI 连接，以便使用它为账户配置外部 OAuth。

第 1 步：为 Snowflake Open Catalog 添加 Snowflake CLI 连接¶

Add a connection with the following values. For all other parameters, press Enter to skip specifying a value for the parameter.

连接配置参数	值
Name for this connection	指定连接名称，例如 `myopencatalogconnection`。
Account name	按如下格式指定您的 Snowflake 组织名称，后接您的 Open Catalog 账户名称： `<orgname>-<my-snowflake-open-catalog-account-name>`。例如 `ABCDEFG-MYACCOUNT1`。要查找这些名称，请参阅 `准备工作`_。
Username	指定您的 Open Catalog 用户名；例如，`jsmith`。
Password [optional]	为 Open Catalog 创建连接时，该参数不是可选参数。输入您的 Open Catalog 密码；例如，`MyPassword123456789`。
Role for the connection [optional]	为 Open Catalog 创建连接时，该参数不是可选参数。您必须输入 `POLARIS_ACCOUNT_ADMIN`

第 2 步：测试 Snowflake CLI 连接¶

要测试 CLI 连接，请按照本例测试 myopencatalogconnection 的连接：

snow connection test -c myopencatalogconnection

Copy

响应应该如下所示：

+------------------------------------------------------------------------------+
| key              | value                                                     |
|----------------------------+-------------------------------------------------|
| Connection name  | myopencatalogconnection                                   |
| Status           | OK                                                        |
| Host             | ABCDEFG-MYACCOUNT1.snowflakecomputing.cn                 |
| Account          | ABCDEFG-MYACCOUNT1                                        |
| User             | jsmith                                                    |
| Role             | POLARIS_ACCOUNT_ADMIN                                     |
| Database         | not set                                                   |
| Warehouse        | not set                                                   |
+------------------------------------------------------------------------------+

Copy

第 3 步：设置默认 Snowflake CLI 连接¶

为确保您使用的连接始终具有所需的 POLARIS_ACCOUNT_ADMIN 角色，您可以将为 Open Catalog 创建的 Snowflake CLI 连接设置为默认连接。有关默认连接的更多信息，请参阅 :ref:label-cli_set_default_connection。

本例将 myopencatalogconnection 连接设为默认连接，请按照本例操作：
```
snow connection set-default myopencatalogconnection
```
Copy

要确认所用的用户和角色是否正确，请运行以下命令：

snow sql -q "Select current_user(); select current_role();"

Copy

响应将返回您的 Open Catalog 用户名，CURRENT ROLE 应为 POLARIS_ACCOUNT_ADMIN。

+----------------+
| CURRENT_USER() |
|----------------|
| JSMITH        |
+----------------+
select current_role();
+-----------------------+
| CURRENT_ROLE()        |
|-----------------------|
| POLARIS_ACCOUNT_ADMIN |
+-----------------------+

Copy

第 1 步：将 Auth0 设置为外部 OAuth 授权服务器¶

将 Auth0 设置为外部 OAuth 授权服务器。不过，将 Microsoft Entra ID 或 Okta 设置为外部 OAuth 授权服务器的步骤类似。

备注

要为您的公司或组织创建 Auth0 账户，请参阅 https://auth0.com/ (https://auth0.com/)。

定义 API¶

定义一个 API，以便您可以为其分配权限。

登录 Auth0 控制台。
在左侧窗格中，选择 Applications > APIs。
选择 + Create API。
输入 Name 和 Identifier，并接受默认设置。
选择 Create。

将权限添加到 API¶

将权限添加到 API，这样您就可以将这些权限授予客户端。

该客户端将在 Open Catalog 中作为主体，而您分配给它的权限将在 Open Catalog 中对应一个主体角色。

登录 Auth0 控制台。
在左侧窗格中，选择 Applications > APIs。
选择您的 API。
在 Permissions 选项卡中，添加权限：
1. 使用 Permission 和 Description 字段为您的 API 添加权限。使用格式 SESSION:ROLE:<custom_role_name>。例如：SESSION:ROLE:ENGINEER。
  
  重要
  
  若要生成服务管理员访问令牌，必须添加 SESSION:ROLE:POLARIS_ACCOUNT_ADMIN 权限，该权限允许您在 Open Catalog 中将具有权限的服务管理员角色分配给 API。
2. 选择 + Add。

创建应用程序¶

创建应用程序，以便您可以授予它访问前面创建的 API 的权限。

登录 Auth0 控制台。
在左侧窗格中，选择 Applications > Applications。
选择 + Create Application 创建一个应用程序。重复此步骤，创建配置外部 OAuth 所需的每个应用程序。

重要

确保创建一个用于生成服务管理员访问令牌的应用程序。稍后，您将为其授予 SESSION:ROLE:POLARIS_ACCOUNT_ADMIN 权限。

为 API 分配权限¶

按照以下步骤选择要授予客户端的权限：

登录 Auth0 控制台。
在左侧窗格中，选择 Applications > Applications。
选择您创建的应用程序。
选择 APIs 选项卡。
如有需要，开启您的 API 的 Authorized。
选择 API 的 Expand 图标。
在 Permissions 字段中，选中要分配给 API 的各项权限的复选框。
选择 Update。

对您创建的每个应用程序重复这些步骤。

重要

请确保选择用于生成服务管理员访问令牌的应用程序，并为其分配 SESSION:ROLE:POLARIS_ACCOUNT_ADMIN 权限至 API。否则，将无法生成服务管理员访问令牌。

第 2 步：检索您的组织名称和账户名称¶

在执行创建安全集成等任务时，您需要组织名称和 Snowflake Open Catalog 账户名称，并以连字符分隔。

要以此格式获取组织名称和 Snowflake Open Catalog 账户名称，请在 Snowflake CLI 中运行以下命令：
```
snow sql -q "SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME();"
```
Copy
在返回结果中复制相应的值，并将其粘贴到文本编辑器中备用。例如：ABCDEFG-MYACCOUNT1。

第 3 步：创建安全集成¶

要创建安全集成，请使用 Snowflake CREATE 连接运行 SECURITY INTEGRATION CLI 命令。

 snow sql -q "create or replace security integration external_oauth_auth0
    type = external_oauth
    enabled = true
    external_oauth_type = custom
    external_oauth_issuer = 'https://<Auth0_domain>/'
    external_oauth_jws_keys_url = 'https://<Auth0_domain>/.well-known/jwks.json'
    external_oauth_audience_list = ('https://<your_org_name>-<your_open_catalog_account_name>.snowflakecomputing.cn')
    external_oauth_token_user_mapping_claim = 'sub'
    external_oauth_snowflake_user_mapping_attribute = 'login_name'
    EXTERNAL_OAUTH_SCOPE_DELIMITER = ' '
    EXTERNAL_OAUTH_SCOPE_MAPPING_ATTRIBUTE = 'scope';"

Copy

其中：

<Auth0_domain> 是您的 Auth0 域。要查找此值，请在 Auth0 中导航至 Applications > Applications > [Name of your application] > Settings > Domain 字段。
<your_org_name>–<your_open_catalog_account_name> 是您的组织名称与 Snowflake Open Catalog 账户名称，中间以连字符连接。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅检索您的组织名称和账户名称。

第 4 步：生成服务管理员访问令牌¶

要以编程方式配置外部 OAuth，您需要一个服务管理员访问令牌。不过，您也可以使用 Open Catalog UI 执行部分外部 OAuth 配置任务。

如果您已为自己生成服务管理员访问令牌，并且该令牌仍有效，则可以跳过此步骤。

要生成服务管理员访问令牌，请在 Snowflake CLI 中执行以下命令，并将值复制到文本编辑器中保存：

ACCESS_TOKEN=$(curl -X POST https://<Auth0_domain>/oauth/token --header 'content-type: application/x-www-form-urlencoded' --data grant_type=client_credentials --data client_id=<client_id> --data client_secret=<client_secret> --data-urlencode "audience=https://<your_org_name>-<your_open_catalog_account_name>.snowflakecomputing.cn" --data "scope=SESSION:ROLE:POLARIS_ACCOUNT_ADMIN" | jq -r '.access_token')

Copy

其中：

<Auth0_domain> 是您的 Auth0 域。要查找此值，请在 Auth0 中导航至 Applications > Applications > [Name of your application] > Settings > Domain 字段。
<client_id> 是您在 Auth0 中的应用程序客户端 ID，该应用被授予 POLARIS_ACCOUNT_ADMIN 权限。要查找此值，请在 Auth0 中导航至 Applications > Applications > [Name of your application] > Settings > Client ID 字段。
<client_secret> 是您在 Auth0 中应用程序的客户端密钥，该应用被授予 POLARIS_ACCOUNT_ADMIN 权限。要查找此值，请在 Auth0 中导航到 Applications > Applications > [Name of your application] > Settings > Client Secret 字段。
<audience> 是您的 API 的标识符。要查找此值，请在 Auth0 中导航至 Applications > APIs > 选择您的 API > Settings > Identifier 字段。
<your_org_name>–<your_open_catalog_account_name> 是您的组织名称与 Snowflake Open Catalog 账户名称，中间以连字符连接。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅检索您的组织名称和账户名称。
POLARIS_ACCOUNT_ADMIN 是 Open Catalog 中内置的角色名称，该角色允许您执行包括配置外部 OAuth 在内的管理任务。在 Open Catalog UI 中，此角色称为服务管理员角色。

第 5 步：创建自定义角色¶

在此步骤中，您将使用 Snowflake CLI 连接创建一个自定义角色。

创建自定义角色，以便稍后您可以将目录角色授予它，并将该自定义角色授予服务主体，从而赋予服务主体相应的权限。有关自定义角色的详细信息，请参阅自定义角色。有关 Open Catalog 中 RBAC 模型的更多信息，请参阅 RBAC 模型。

备注

如果您设置的默认 Snowflake CLI 连接没有被授予 POLARIS_ACCOUNT_ADMIN 角色，则必须在命令中包含以下语句：USE ROLE POLARIS_ACCOUNT_ADMIN。

下面的示例创建了一个 OPEN_CATALOG_ADMIN 自定义角色：

snow sql -q "create role OPEN_CATALOG_ADMIN;"

Copy

第 6 步：将目录角色授予自定义角色¶

在本部分中，您将向您之前创建的自定义角色授予目录角色。

在将目录角色授予自定义角色之后，您可以将该自定义角色授予服务主体，从而使服务主体拥有授予给主体角色的目录角色所赋予的所有权限。有关 Open Catalog 中 RBAC 模型的更多信息，请参阅 RBAC 模型。

您可以向自定义角色授予具有目录的目录管理员权限或具有您指定的目录的一组权限的目录角色：

如果您希望授予服务主体目录管理员权限，请将具有目录管理员权限的目录角色授予自定义角色。有关目录管理员拥有的权限，请参阅目录管理员角色。
如果您希望授予服务主体您指定的一组权限，请将具有您指定的权限的目录角色授予自定义角色。例如，如果您希望将 cataLog_reader、catalog_writer 或 catalog_metadata_reader 目录角色授予自定义角色，可以选择此选项。

将具有目录管理员权限的目录角色授予自定义角色¶

在本部分中，您将具有目录管理员权限的目录角色授予自定义角色。工作流程如下：

创建目录角色¶

运行以下命令，在指定的目录中创建目录角色：

 curl -X POST \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/management/v1/catalogs/{catalogName}/catalog-roles" \
-H "Authorization: Bearer <service_admin_access_token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
   "name": "<catalog_role_name>"
   }'
Copy
其中：

<your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅 :ref:label-retrieve_org_account_name_external_oauth。

{Catalogname} 是您希望在 Open Catalog 中创建目录角色的目录名称。

<service_admin_access_token> 是 :ref:您生成的服务管理员访问令牌 <label-generate_service_admin_access_token_external_oauth>。

对于 <catalog_role_name>，指定目录角色的名称。例如：CatalogAdmin。

请参阅 Snowflake Labs 中的 目录 <https://github.com/Snowflake-Labs/polaris-cli-opencatalog-demo?tab=readme-ov-file#catalog-1>_。

请参阅 :doc:/user-guide/opencatalog/create-catalog-role。

运行以下命令：

curl -X PUT \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/management/v1/catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants" \
-H "Authorization: Bearer <service_admin_access_token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"grant": {"type": "catalog", "privilege": "CATALOG_MANAGE_CONTENT"}}'
Copy
其中：

<your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅 :ref:label-retrieve_org_account_name_external_oauth。

{Catalogname} 是您希望授予权限的 Open Catalog 中目录的名称。

{catalogRoleName} 是您希望授予权限的目录角色的名称。例如 TableReader。

<service_admin_access_token> 是 :ref:您生成的服务管理员访问令牌 <label-generate_service_admin_access_token_external_oauth>。

CATALOG_MANAGE_CONTENT 是 Open Catalog 中具有目录管理员权限的权限的名称。

请参阅 Snowflake Labs 中的 权限 <https://github.com/Snowflake-Labs/polaris-cli-opencatalog-demo?tab=readme-ov-file#privileges>_。如说明中所述，请确保将 CATALOG_MANAGE_CONTENT 权限授予目录角色。

请参阅 :ref:将目录权限授予目录角色 <label-grant_catalog_privileges_catalog_role> 并选择 CATALOG_MANAGE_CONTENT 权限。

将目录角色授予自定义角色¶

重要

自定义角色区分大小写。即使创建时使用了小写字母或大小写混合形式，在指定时也应使用全大写字母。

运行以下命令：

curl -X PUT \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/management/v1/principal-roles/{customRoleName}/catalog-roles/{catalogName}" \
-H "Authorization: Bearer <service_admin_access_token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"catalogRole": {"name": "<catalog_role_name>", "properties": {}, "entityVersion": 1}}'
Copy
其中：

<your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅 :ref:label-retrieve_org_account_name_external_oauth。

{customRoleName} 是您要授予具有目录管理员权限的目录角色的自定义角色的名称。例如 OPEN_CATALOG_ADMIN。

{catalogName} 是您要在 Open Catalog 中授予目录管理员权限的目录的名称。

<catalog_role_name> 是目录的目录角色的名称，该角色已获授目录管理员权限。例如：CatalogAdmin。

<service_admin_access_token> 是 :ref:您生成的服务管理员访问令牌 <label-generate_service_admin_access_token_external_oauth>。

请参阅 Snowflake Labs 中的 授权 <https://github.com/Snowflake-Labs/polaris-cli-opencatalog-demo?tab=readme-ov-file#grants>_。

请参阅 :doc:/user-guide/opencatalog/secure-catalogs。这些说明描述了如何将目录角色授予主体角色，但具体过程是相同的。您无需从列表中选择主体角色，而是选择要向其授予目录角色（具有 CATALOG_MANAGE_CONTENT 权限）的自定义角色。

如有需要，可重复此步骤，为自定义角色授予对其他目录的目录管理员权限。

向自定义角色授予具有您指定的一组权限的目录角色¶

工作流程如下：

创建目录角色。
向目录角色授予权限。这些权限允许服务主体在 Open Catalog 中执行操作。
将目录角色授予自定义角色。

创建目录角色¶

在本部分中，您将创建一个目录角色。有关目录角色的更多信息，请参阅目录角色。

运行以下命令，在指定的目录中创建目录角色：

 curl -X POST \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/management/v1/catalogs/{catalogName}/catalog-roles" \
-H "Authorization: Bearer <service_admin_access_token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
   "name": "<catalog_role_name>"
   }'
Copy
其中：

<your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅 :ref:label-retrieve_org_account_name_external_oauth。

{Catalogname} 是您希望在 Open Catalog 中创建目录角色的目录名称。

<service_admin_access_token> 是 :ref:您生成的服务管理员访问令牌 <label-generate_service_admin_access_token_external_oauth>。

对于 <catalog_role_name>，指定目录角色的名称。例如：TableReader。

请参阅 Snowflake Labs 中的 目录 <https://github.com/Snowflake-Labs/polaris-cli-opencatalog-demo?tab=readme-ov-file#catalog-1>_。

请参阅 :doc:/user-guide/opencatalog/create-catalog-role。

向目录角色授予权限¶

您可以向整个目录，或者目录中的命名空间或表授予权限：

运行以下命令：

curl -X PUT \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/management/v1/catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants" \
-H "Authorization: Bearer <service_admin_access_token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"grant": {"type": "catalog", "privilege": "<privilege_name>"}}'
Copy
其中：

<your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅 :ref:label-retrieve_org_account_name_external_oauth。

{Catalogname} 是您希望授予权限的 Open Catalog 中目录的名称。

{catalogRoleName} 是您希望授予权限的目录角色的名称。例如 TableReader。

<service_admin_access_token> 是 :ref:您生成的服务管理员访问令牌 <label-generate_service_admin_access_token_external_oauth>。

<privilege_name> 是您要授予目录角色的权限的名称。有关可用权限的列表，请参阅 访问控制权限 <https://other-docs.snowflake.com/en/opencatalog/access-control#access-control-privileges>_。

请参阅 Snowflake Labs 中的 权限 <https://github.com/Snowflake-Labs/polaris-cli-opencatalog-demo?tab=readme-ov-file#privileges>_。

备注

Snowflake Labs 中的示例授予了 CATALOG_MANAGE_CONTENT 权限，该权限会提供对目录的目录管理员权限。但是，有关其他可用权限的列表，请参阅 Open Catalog 文档中的 访问控制权限 <https://other-docs.snowflake.com/en/opencatalog/access-control#access-control-privileges>_。

请参阅 :ref:将目录权限授予目录角色 <label-grant_catalog_privileges_catalog_role>。

授予目录角色命名空间权限¶

运行以下命令：

curl -X PUT \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/management/v1/catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants" \
-H "Authorization: Bearer <service_admin_access_token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"grant": {"type": "namespace", "namespace": ["<namespace_name>"], "privilege": "<privilege_name>"}}'
Copy
其中：

<your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅 :ref:label-retrieve_org_account_name_external_oauth。

{Catalogname} 是您希望授予权限的 Open Catalog 中目录的名称。

{catalogRoleName} 是您希望授予权限的目录角色的名称。例如 TableReader。

<service_admin_access_token> 是 :ref:您生成的服务管理员访问令牌 <label-generate_service_admin_access_token_external_oauth>。

<namespace_name> is the name of the namespace you want to grant privileges to. To grant privileges to a nested namespace, specify it, along with each parent namespace, separated by a comma. For example: "ns1","ns1a"。

<privilege_name> 是您要授予目录角色的命名空间权限的名称。有关可用权限的列表，请参阅 访问控制权限 <https://other-docs.snowflake.com/en/opencatalog/access-control#access-control-privileges>_。

请参阅 Snowflake Labs 中的 权限 <https://github.com/Snowflake-Labs/polaris-cli-opencatalog-demo?tab=readme-ov-file#privileges>_。

备注

请参阅 :ref:授予目录角色命名空间权限 <label-grant_namespace_privileges_catalog_role>。

授予目录角色表权限¶

运行以下命令：

curl -X PUT \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/management/v1/catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants" \
-H "Authorization: Bearer <service_admin_access_token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"grant": {"type": "table", "namespace": ["<namespace_name>"], "tableName": "<table_name>", "privilege": "<privilege_name>"}}'
Copy
其中：

<your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅 :ref:label-retrieve_org_account_name_external_oauth。

{Catalogname} 是您希望授予权限的 Open Catalog 中目录的名称。

{catalogRoleName} 是您希望授予权限的目录角色的名称。例如 TableReader。

<service_admin_access_token> 是 :ref:您生成的服务管理员访问令牌 <label-generate_service_admin_access_token_external_oauth>。

<namespace_name> is the name of the namespace whose table you want to grant privileges to. To grant privileges on a table located under a nested namespace, specify the nested namespace, along with each parent namespace, separated by a comma. For example: "ns1","ns1a"。

<table_name> 是要授予权限的表的名称。

<privilege_name> 是您要授予目录角色的权限的名称。有关可用权限的列表，请参阅 访问控制权限 <https://other-docs.snowflake.com/en/opencatalog/access-control#access-control-privileges>_。

请参阅 Snowflake Labs 中的 权限 <https://github.com/Snowflake-Labs/polaris-cli-opencatalog-demo?tab=readme-ov-file#privileges>_。

备注

请参阅 :ref:授予目录角色表权限 <label-grant_table_privileges_catalog_role>。

将目录角色授予自定义角色¶

重要

自定义角色区分大小写。即使创建时使用了小写字母或大小写混合形式，在指定时也应使用全大写字母。

运行以下命令：

curl -X PUT \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/management/v1/principal-roles/{customRoleName}/catalog-roles/{catalogName}" \
-H "Authorization: Bearer <service_admin_access_token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"catalogRole": {"name": "<catalog_role_name>", "properties": {}, "entityVersion": 1}}'
Copy
其中：

<your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅 :ref:label-retrieve_org_account_name_external_oauth。

{customRoleName} 是您要向其授予目录角色的自定义角色的名称。

{catalogName} 是 Open Catalog 中目录的名称，您在其中创建了要授予权限的目录角色。

<service_admin_access_token> 是 :ref:您生成的服务管理员访问令牌 <label-generate_service_admin_access_token_external_oauth>。

<catalog_role_name> 是您要授予自定义角色的目录角色的名称。

请参阅 Snowflake Labs 中的 授权 <https://github.com/Snowflake-Labs/polaris-cli-opencatalog-demo?tab=readme-ov-file#grants>_。

请参阅 :doc:/user-guide/opencatalog/secure-catalogs。这些说明描述了如何将目录角色授予主体角色，但具体过程是相同的。您无需从列表中选择主体角色，而是选择自定义角色。

如果需要，请重复此工作流程，将您创建的其他目录角色授予自定义角色。

第 7 步：创建服务主体¶

在此步骤中，您使用 Snowflake CLI 连接创建服务主体。

备注

如果您设置的默认 Snowflake CLI 连接没有被授予 POLARIS_ACCOUNT_ADMIN 角色，则必须在命令中包含以下语句：USE ROLE POLARIS_ACCOUNT_ADMIN。

要通过外部 OAuth 连接到 Open Catalog，我们需要一个服务主体。在 Open Catalog 中，服务主体是 TYPE 参数设置为 service 的用户。因此，我们将使用 CREATE USER 命令创建一个 TYPE=service 用户。

要创建服务主体，请运行以下命令：

snow sql -q "CREATE USER <user_name> LOGIN_NAME='<client_id>@clients' TYPE='service';"

Copy

其中：

对于 <user_name>，请为服务主体指定一个名称。
对于 <client_id>，请为你的应用程序指定客户端 ID。要查找此值，请在 Auth0 中导航到 Applications > Applications > [Name of your application] > Settings > Client ID 字段。

第 8 步：授予服务主体自定义角色¶

在本部分中，您将使用您的 Snowflake CLI 连接将自定义角色授予一个或多个服务主体。因此，您会将授予自定义角色的任何目录角色的权限赋予该服务主体。有关 Open Catalog 中 RBAC 模型的更多信息，请参阅 RBAC 模型。

备注

如果您设置的默认 Snowflake CLI 连接没有被授予 POLARIS_ACCOUNT_ADMIN 角色，则必须在命令中包含以下语句：USE ROLE POLARIS_ACCOUNT_ADMIN。

重要

自定义角色区分大小写。即使创建时使用了小写字母或大小写混合形式，在指定时也应使用全大写字母。

下面的示例将 ENGINEER 自定义角色授予 service_principal1 服务主体。

snow sql -q "GRANT ROLE ENGINEER to user service_principal1;"

Copy

要验证角色是否已授予服务主体，请运行：

snow sql -q "show grants to user service_principal1;" 

Copy

在响应中，检查您创建的自定义角色（role 列）是否已分配给您创建的服务主体（grantee_name 列）。

（可选）第 9 步：生成访问令牌¶

在本节中，您可以生成访问令牌，使用它可以通过外部 OAuth 连接到 Open Catalog。但是，如果使用此方法连接，您必须手动刷新访问令牌。

或者，您可以跳过此步骤，稍后使用自动刷新令牌连接 Open Catalog，这是首选方法。

使用以下 curl 命令生成访问令牌：

ACCESS_TOKEN=$(curl -X POST https://<Auth0_domain>/oauth/token --header 'content-type: application/x-www-form-urlencoded' --data grant_type=client_credentials --data client_id=<client_id> --data client_secret=<client_secret> --data-urlencode "audience=https://<your_org_name>-<your_open_catalog_account_name>.snowflakecomputing.cn" --data "scope=SESSION:ROLE:<custom_role_name>" | jq -r '.access_token')

Copy

其中：

<Auth0_domain> 是您的 Auth0 域。要查找此值，请在 Auth0 中导航至 Applications > Applications > [Name of your application] > Settings > Domain 字段。
<client_id> 是您在 Auth0 中应用程序的客户端 ID。要查找此值，请在 Auth0 中导航到 Applications > Applications > [Name of your application] > Settings > Client ID 字段。
<client_secret> 是您在 Auth0 中应用程序的客户端密钥。要找到此值，在 Auth0 中导航到 Applications > Applications > [您的应用名称] > Settings > Client Secret 字段。
<audience> 是您的 API 的标识符。要查找此值，请在 Auth0 中导航到 Applications > APIs> 选择您的 API > 设置

Identifier 字段。
<your_org_name>–<your_open_catalog_account_name> 是您的组织名称与 Snowflake Open Catalog 账户名称，中间以连字符连接。

例如：ABCDEFG-MYACCOUNT1。

要以此格式检索这些值，请参阅检索您的组织名称和账户名称。
<custom_role_name> is the name of a custom role you granted with catalog roles, such as ENGINEER。

第 10 步：通过外部 OAuth 连接到 Open Catalog¶

在本部分中，您将通过外部 OAuth 将服务主体连接到 Open Catalog。有关说明，请参阅连接 Snowflake Open Catalog 与外部 OAuth，其中包括使用访问令牌或自动令牌刷新连接的说明。

在 Snowflake Open Catalog 中配置外部 OAuth¶

先决条件¶

准备工作¶

创建 Snowflake CLI 连接¶

第 1 步：为 Snowflake Open Catalog 添加 Snowflake CLI 连接¶

第 2 步：测试 Snowflake CLI 连接¶

第 3 步：设置默认 Snowflake CLI 连接¶

第 1 步：将 Auth0 设置为外部 OAuth 授权服务器¶

定义 API¶

将权限添加到 API¶

创建应用程序¶

为 API 分配权限¶

第 2 步：检索您的组织名称和账户名称¶

第 3 步：创建安全集成¶

第 4 步：生成服务管理员访问令牌¶

第 5 步：创建自定义角色¶

第 6 步：将目录角色授予自定义角色¶

将具有目录管理员权限的目录角色授予自定义角色¶

创建目录角色¶

将目录管理员权限授予目录角色¶

将目录角色授予自定义角色¶

向自定义角色授予具有您指定的一组权限的目录角色¶

创建目录角色¶

向目录角色授予权限¶

授予目录角色目录权限¶

授予目录角色命名空间权限¶

授予目录角色表权限¶

将目录角色授予自定义角色¶

第 7 步：创建服务主体¶

第 8 步：授予服务主体自定义角色¶

（可选）第 9 步：生成访问令牌¶

第 10 步：通过外部 OAuth 连接到 Open Catalog¶