在 Snowflake Open Catalog 中配置密钥对身份验证¶

本主题介绍如何在 Snowflake Open Catalog 中配置密钥对身份验证。此配置允许密钥对身份验证用户通过访问令牌以编程方式连接到 Open Catalog。为简便起见，除非另有说明，否则本主题的其余部分使用“用户”一词来指代密钥对身份验证用户。

通过密钥对身份验证，您可以允许用户以编程方式访问 Open Catalog，并基于不同自定义角色为其配置对指定目录的权限。例如：

ANALYST 自定义角色：只能访问 catalogA。
ENGINEER 自定义角色：只能访问 catalogB。

先决条件¶

在 Open Catalog 账户中创建目录。
您必须在计算机上安装 Snowflake CLI。此外，您还必须为 Open Catalog 创建一个 Snowflake CLI 连接。要创建此连接，请参阅下方的为 Open Catalog 创建 Snowflake CLI 连接。
要配置密钥对身份验证，您必须在 Open Catalog 中具有服务管理员角色。有关更多信息，请参阅用户角色。在 Snowflake CLI 中，此角色会显示为 POLARIS_ACCOUNT_ADMIN。
您必须在计算机上安装 SnowSQL。
您需要一个服务管理员访问令牌。此令牌用于以程序化方式配置密钥对身份验证，并且在授予用户目录管理员权限时必不可少。要生成此令牌，请参阅下方的生成服务管理员访问令牌。

准备工作¶

要配置密钥对身份验证，您需要一个适用于 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。

为 Open Catalog 创建 Snowflake CLI 连接¶

为您的 Open Catalog 账户创建 Snowflake CLI 连接，以便您使用它为账户配置密钥对身份验证。

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

为您希望配置密钥对身份验证的 Snowflake Open Catalog 账户添加连接。

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

响应应该如下所示：

+------------------------------------------------------------------------------+
| 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                                                   |
+------------------------------------------------------------------------------+

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

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

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

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

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

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

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

生成服务管理员访问令牌¶

要以编程方式配置密钥对身份验证，您需要一个服务管理员访问令牌。但是，您可以选择使用 Open Catalog UI 来执行部分密钥对身份验证的配置任务。

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

生成服务管理员访问令牌的步骤如下：

生成私钥和公钥¶

本部分介绍如何生成私钥和公钥。

要生成私钥，请使用以下命令：

openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt

要生成公钥，请使用以下命令：

openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

将公钥分配给自己。¶

使用您的 Snowflake CLI 连接，将公钥分配给自己。

备注

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

要将公钥分配给自己，请运行：
```
snow sql -q "alter user <your_username> set RSA_PUBLIC_KEY='<your_public_key>';"
```
其中：
- <your_username> 是您的 Open Catalog 用户名，用于登录 Open Catalog UI。
备注

如果您需要检索公钥，请运行：cat rsa_key.pub。
验证用户是否已设置公钥 (RSA_PUBLIC_KEY) 及用户的 RSA 公钥指纹 (RSA_PUBLIC_KEY_FP)：
```
snow sql -q "desc user <your_username>;"
```
其中：
- <your_username> 是您的 Open Catalog 用户名，用于登录 Open Catalog UI。

生成 JSON Web 令牌¶

在本部分中，您将生成一个 JSON Web 令牌 (JWT)，此令牌是生成访问令牌所必需的。

要使用 SnowSQL 生成 JWT，请运行：
```
snowsql --private-key-path rsa_key.p8 --generate-jwt -h <your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn -a <account-identifier> -u <your_user_name>
```
其中：
- <your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。
  
  例如：ABCDEFG-MYACCOUNT1。
  
  要以此格式检索这些值，请参阅检索您的组织名称和账户名称。
- <account-identifier> is the account identifier for your Snowflake Open Catalog account. To retrieve it, refer to your Open Catalog account URL. For example, abc12345in https://app.snowflake.cn/us-west-2/abc12345/#/。
- <your_user_name> 是您的 Open Catalog 用户名。
如果已将其加密，请输入密码，否则请按 Enter 键继续。您可能需要几秒钟才能收到 JWT。

生成服务管理员访问令牌¶

在本部分中，您将生成一个服务管理员访问令牌，用于以编程方式配置密钥对身份验证。

要生成服务管理员访问令牌，请执行以下命令并将相关值复制到文本编辑器中：
```
curl -i -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "scope=session:role:POLARIS_ACCOUNT_ADMIN" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_secret=<your_JWT>" \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/catalog/v1/oauth/tokens"
```
其中：
- POLARIS_ACCOUNT_ADMIN 是 Open Catalog 中内置角色的名称，可用于在 Open Catalog 中执行管理任务，其中包括配置密钥对身份验证。在 Open Catalog UI 中，此角色称为服务管理员角色。
- <your_JWT> 是您在上一步中生成的 JWT。
- <your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。
  
  例如：ABCDEFG-MYACCOUNT1。
  
  要以此格式检索这些值，请参阅检索您的组织名称和账户名称。

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

在此步骤中，您将使用 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;"

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

在执行生成 JWT 或访问令牌等任务时，您需要使用组织名称和 Snowflake Open Catalog 账户名称，并用连字符分隔。

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

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

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

在将目录角色授予自定义角色后，您可以将该自定义角色授予用户，这样用户便会获得所有授予该主体角色的目录角色所拥有的权限。有关 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>"
   }'
其中：

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

例如：ABCDEFG-MYACCOUNT1。

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

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

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

对于 <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"}}'
其中：

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

例如：ABCDEFG-MYACCOUNT1。

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

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

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

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

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}}'
其中：

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

例如：ABCDEFG-MYACCOUNT1。

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

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

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

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

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

请参阅 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>"
   }'
其中：

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

例如：ABCDEFG-MYACCOUNT1。

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

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

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

对于 <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>"}}'
其中：

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

例如：ABCDEFG-MYACCOUNT1。

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

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

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

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

<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>"}}'
其中：

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

例如：ABCDEFG-MYACCOUNT1。

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

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

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

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

<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>"}}'
其中：

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

例如：ABCDEFG-MYACCOUNT1。

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

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

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

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

<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}}'
其中：

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

例如：ABCDEFG-MYACCOUNT1。

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

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

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

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

<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。这些说明描述了如何将目录角色授予主体角色，但具体过程是相同的。您无需从列表中选择主体角色，而是选择自定义角色。

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

第 4 步：创建用户¶

使用您的 Snowflake CLI 连接在 Open Catalog 中创建一个密钥对身份验证用户。此用户的凭据不能用于人工登录 Open Catalog UI。

备注

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

要创建用户，请运行以下命令：
```
snow sql -q "create user <username> login_name='<username>';"
```
其中：
- <username> 是您要分配给该密钥对身份验证用户的用户名。

第 5 步：向用户授予自定义角色¶

在本部分中，您将使用 Snowflake CLI 连接，将自定义角色授予一个或多个用户。通过此操作，用户将获得该自定义角色获授的所有目录角色的权限。有关 Open Catalog 中 RBAC 模型的更多信息，请参阅 RBAC 模型。

备注

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

重要

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

以下示例会向 keypairuser1 用户授予ENGINEER 自定义角色。

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

要验证是否已将角色授予用户，请运行：

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

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

第 6 步：为用户生成访问令牌¶

在本部分中，您将为用户生成一个访问令牌，该令牌稍后用于通过密钥对身份验证将用户连接到 Open Catalog。

步骤如下：

生成私钥和公钥¶

本部分介绍如何生成私钥和公钥。

要生成私钥，请使用以下命令：

openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt

要生成公钥，请使用以下命令：

openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

将公钥分配给用户¶

使用您的 Snowflake CLI 连接，将公钥分配给您创建的用户。

备注

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

要将公钥分配给您创建的用户，请运行：
```
snow sql -q "alter user <username> set RSA_PUBLIC_KEY='<your_public_key>';"
```
备注

如果您需要检索公钥，请运行：cat rsa_key.pub。
验证用户是否已设置公钥 (RSA_PUBLIC_KEY) 及用户的 RSA 公钥指纹 (RSA_PUBLIC_KEY_FP)：
```
snow sql -q "desc user keypairuser1;"
```

为用户生成 JWT¶

在此步骤中，您将生成一个 JWT，此令牌是生成访问令牌所必需的。

要使用 SnowSQL 生成 JWT，请运行：
```
snowsql --private-key-path rsa_key.p8 --generate-jwt -h <your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn -a <account-identifier> -u <user_name>
```
其中：
- <your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。
  
  例如：ABCDEFG-MYACCOUNT1。
  
  要以此格式检索这些值，请参阅检索您的组织名称和账户名称。
- <account-identifier> is the account identifier for your Snowflake Open Catalog account. To retrieve it, refer to your Open Catalog account URL. For example, abc12345in https://app.snowflake.cn/us-west-2/abc12345/#/。
- <user_name> 是 Open Catalog 用户的用户名，且该用户已获分配公钥。
如果已将其加密，请输入密码，否则请按 Enter 键继续。您可能需要几秒钟才能收到 JWT。

为用户生成访问令牌¶

使用 JWT 为自定义角色或内置角色检索访问令牌：
```
curl -i -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "scope=session:role:<custom_role_name>" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_secret=<your_JWT>" \
"https://<your_org_name>-<your_open_catalogaccount_name>.snowflakecomputing.cn/polaris/api/catalog/v1/oauth/tokens"
```
其中
- <custom_role_name> is the name of a custom role you created, such as ENGINEER.
- <your_JWT> 是您在上一步中生成的 JWT。
- <your_org_name>–<your_open_catalogaccount_name> 是您的组织名称和 Snowflake Open Catalog 账户名称，中间用连字符分隔。
  
  例如：ABCDEFG-MYACCOUNT1。
  
  要以此格式检索这些值，请参阅检索您的组织名称和账户名称。
将访问令牌存储在变量 ($ACCESS_TOKEN) 中。

第 7 步：通过密钥对身份验证连接到 Open Catalog¶

在本部分中，您将通过密钥对身份验证将用户连接到 Open Catalog。有关说明，请参阅通过密钥对身份验证连接到 Snowflake Open Catalog。

配置密钥对轮换¶

Open Catalog 支持多个活动密钥，以实现无中断轮换。在 Open Catalog 中配置密钥对轮换的步骤与在 Snowflake 中配置密钥对轮换的步骤相同。有关说明，请参阅 Snowflake 文档中的配置密钥对轮换。

使用 Apache Polaris™（孵化中）CLI 管理目录¶

配置密钥对身份验证后，您可以生成服务管理员访问令牌，以使用 Apache Polaris™ （孵化中）CLI 在 Open Catalog 中设置和管理目录。有关说明，请参阅 Snowflake Labs 中的 Open Catalog with Polaris 指南 (https://github.com/Snowflake-Labs/polaris-cli-opencatalog-demo)。

在 Snowflake Open Catalog 中配置密钥对身份验证¶

先决条件¶

准备工作¶

为 Open Catalog 创建 Snowflake CLI 连接¶

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

第 2 步：测试 Snowflake CLI 连接¶

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

生成服务管理员访问令牌¶

生成私钥和公钥¶

将公钥分配给自己。¶

生成 JSON Web 令牌¶

生成服务管理员访问令牌¶

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

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

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

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

创建目录角色¶

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

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

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

创建目录角色¶

向目录角色授予权限¶

授予目录角色目录权限¶

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

授予目录角色表权限¶

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

第 4 步：创建用户¶

第 5 步：向用户授予自定义角色¶

第 6 步：为用户生成访问令牌¶

生成私钥和公钥¶

将公钥分配给用户¶

为用户生成 JWT¶

为用户生成访问令牌¶

第 7 步：通过密钥对身份验证连接到 Open Catalog¶

配置密钥对轮换¶

使用 Apache Polaris™（孵化中）CLI 管理目录¶