Exemplo: acesso externo usando OAuth e referências¶

Adição de referências ao arquivo do manifesto¶

Para habilitar o acesso a um ponto de extremidade externo usando OAuth, um provedor pode adicionar as seguintes entradas no arquivo de manifesto:

• Referência do EXTERNAL ACCESS INTEGRATION ao privilégio USAGE

• Referência do SECRET ao privilégio READ

O exemplo de arquivo de manifesto a seguir mostra como definir essas referências:

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

Referências a segredos e objetos de acesso externo também exigem uma função configuration_callback no script de configuração. Consulte Adição da função configuration_callback ao script de configuração para obter mais informações.

Adição da função configuration_callback ao script de configuração¶

Após adicionar referências para a integração de acesso secreto e externo, você deve adicionar a função configuration_callback ao script de configuração. Para criar uma integração de acesso externo ou segredo, o aplicativo deve ser capaz de determinar valores para a porta do host, o tipo de segredo, a autorização e o ponto de extremidade do token para OAuth etc. O configuration_callback fornece essas informações da conta do consumidor para o aplicativo.

O Snowsight executa este procedimento de retorno de chamada para preencher a caixa de diálogo de configuração que solicita ao usuário que configure os objetos. O procedimento precisa ser concedido a uma função de aplicativo para execução.

A função de retorno de chamada tem os seguintes requisitos:

• A função de retorno de chamada deve aceitar um argumento contendo um nome de referência. Isso permite que a mesma função de retorno de chamada manipule múltiplas referências.

• A função de retorno de chamada deve retornar um objeto JSON bem formado. O objeto JSON contém as seguintes propriedades:

  • type

    Indica o tipo de mensagem. Os valores válidos são:

    • CONFIGURATION: retorna uma carga útil com os valores de configuração para o objeto com base no tipo de objeto.

    • ERROR: retorna um erro com a mensagem associada que é exibida em Snowsight.

  • payload

    Contém o conteúdo da resposta com base no valor da propriedade type e o tipo de objeto que está sendo configurado.

A assinatura para o retorno de chamada de configuração é:

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

No script de instalação, você deve conceder o privilégio USAGE para as funções do aplicativo que são usadas para configurar o aplicativo para que elas tenham permissão para chamar o procedimento armazenado. O exemplo a seguir mostra como conceder o privilégio USAGE em um procedimento armazenado:

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

A função de retorno de chamada retorna um objeto JSON. Consulte Formato JSON para a resposta de retorno de chamada de configuração para obter mais informações.

O exemplo a seguir mostra uma função de retorno de chamada típica para manipular acesso externo e referências de segredo.

Esta função faz o seguinte:

• Para uma referência a uma integração de acesso externo, o procedimento retorna um objeto JSON contendo as informações de configuração necessárias. Consulte Formato JSON para integração de acesso externo para obter mais informações.

• Para uma referência a um segredo, o procedimento retorna um objeto JSON contendo uma configuração de segredo do tipo OAuth2. Consulte Formato JSON para referências de segredo para obter mais informações.

  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;

Como usar a permissão Python SDK para segredos e integrações de acesso externo¶

Python Permission SDK suporta objetos de integração de acesso externo e de segredo. No entanto, o comportamento é ligeiramente diferente para esses objetos.

Quando um provedor chama permission.request_reference() e passa o nome de uma referência com um object_type valor de SECRET ou EXTERNAL ACCESS INTEGRATION, Snowsight executa automaticamente o seguinte:

• Chama a função configuration_callback no script de configuração.

• Valida os valores retornados pela função configuration_callback.

• Exibe a caixa de diálogo de configuração para o consumidor.