示例 – 使用 OAuth 和引用进行外部访问¶

本主题提供了一个示例，介绍如何使用引用来允许提供商授予对 Snowflake 外部端点的访问权限。此示例使用 OAuth2 密钥和外部访问集成来允许访问。

重要

此示例展示了使用引用的手动方法，其中使用者必须自行创建集成。对于新应用程序，Snowflake 建议改用基于应用程序规范的自动化权限授予。请参阅用于外部访问集成的使用应用程序规范来请求外部访问集成 (EAIs) 和用于安全集成的请求应用程序规范的安全集成。

向清单文件中添加引用¶

若要使用 OAuth 启用对外部端点的访问，提供商可以在清单文件中添加以下条目：

具有 USAGE 权限的 EXTERNAL ACCESS INTEGRATION 引用
具有 READ 权限的 SECRET 引用

以下示例清单文件显示了如何定义这些引用：

manifest_version: 1
configuration:
  log_level: warn
  trace_level: off
...
references:
  - consumer_secret:
      label: "Consumer's Secret"
      description: "Needed to authenticate with xyz.com"
      privileges:
        - READ
      object_type: SECRET
      register_callback: config.register_my_secret
      configuration_callback: config.get_config_for_ref
  - consumer_external_access:
      label: "Default External Access Integration"
      description: "This is required to access xyz.com"
      privileges:
        - USAGE
      object_type: EXTERNAL ACCESS INTEGRATION
      register_callback: config.register_reference
      configuration_callback: config.get_config_for_ref
      required_at_setup: true

备注

不能将这些引用的 multi_valued 属性设置为 true。

对密钥和外部访问对象的引用也需要在安装脚本中使用 configuration_callback 函数。有关更多信息，请参阅向安装脚本中添加 configuration_callback 函数。

向安装脚本中添加 configuration_callback 函数¶

在为密钥和外部访问集成添加引用之后，必须向安装脚本中添加 configuration_callback 函数。要创建外部访问集成或密钥，应用程序必须能够确定主机端口、密钥类型、OAuth 授权和令牌端点等的值。configuration_callback 将此信息从使用者账户提供给应用程序。

Snowsight 运行此回调过程，以填充提示用户配置对象的配置对话框。该过程需要被授予应用程序角色才能执行。

备注

configuration_callback 仅支持外部访问集成和密钥对象。

回调函数具有以下要求：

回调函数必须接受包含引用名称的实参。这样可使同一个回调函数处理多个引用。
回调函数必须返回格式正确的 JSON 对象。JSON 对象包含以下属性：
- type
  
  指示消息的类型。有效值为：
  - CONFIGURATION：返回一个有效负载，其中包含基于对象类型的对象配置值。
  - ERROR：返回一个错误，其中包含 Snowsight 中显示的相关消息。
- payload
  
  包含基于 type 属性值和所配置的对象类型的响应内容。

配置回调的签名如下：

CREATE OR REPLACE PROCEDURE configuration_callback_name(ref_name string)
RETURNS STRING
language <language>
as
$$
  ...
$$

在安装脚本中，必须向用于配置应用程序的应用程序角色授予 USAGE 权限，以便它们有权调用存储过程。以下示例显示如何对存储过程授予 USAGE 权限：

GRANT USAGE ON PROCEDURE configuration_callback_name(string)
  TO APPLICATION ROLE app_role;

回调函数会返回 JSON 对象。有关更多信息，请参阅配置回调响应的 JSON 格式。

以下示例显示用于处理外部访问和密钥引用的典型回调函数。

此函数执行以下操作：

对于外部访问集成的引用，该过程返回一个包含所需配置信息的 JSON 对象。有关更多信息，请参阅外部访问集成的 JSON 格式。
对于密钥的引用，该过程返回一个 JSON 对象，其中包含 OAuth2 类型的密钥配置。有关更多信息，请参阅密钥引用的 JSON 格式。

  CREATE OR REPLACE PROCEDURE config.get_config_for_ref(ref_name STRING)
    RETURNS STRING
    LANGUAGE SQL
    AS
    $$
    BEGIN
      CASE (ref_name)
        WHEN 'CONSUMER_EXTERNAL_ACCESS' THEN
          RETURN '{
            "type": "CONFIGURATION",
            "payload":{
              "host_ports":["google.com"],
              "allowed_secrets" : "LIST",
              "secret_references":["CONSUMER_SECRET"]}}';
        WHEN 'CONSUMER_SECRET' THEN
          RETURN '{
            "type": "CONFIGURATION",
            "payload":{
              "type" : "OAUTH2",
              "security_integration": {
                "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
                "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
                "oauth_authorization_endpoint":
                    "https://accounts.google.com/o/oauth2/auth"}}}';
  END CASE;
  RETURN '';
  END;
  $$;

GRANT USAGE ON PROCEDURE config.get_config_for_ref(string)
  TO APPLICATION ROLE app_admin;

将 Python Permission SDK 用于密钥和外部访问集成¶

Python Permission SDK 支持密钥和外部访问集成对象。但是，这些对象的行为略有不同。

当提供商调用 permission.request_reference() 并传递 object_type 值为 SECRET 或 EXTERNAL ACCESS INTEGRATION 的引用的名称时，Snowsight 会自动执行以下操作：

调用安装脚本中的 configuration_callback 函数。
验证 configuration_callback 函数返回的值。
向使用者显示配置对话框。

备注

如果提供商在配置外部访问集成时，payload.allow_secrets 属性设置为 LIST，则无需单独调用来请求密钥引用。密钥配置隐式地包含在外部访问集成配置中。