Beispiel – Externer Zugriff mit OAuth und Referenzen¶

Referenzen zur Manifest-Datei hinzufügen¶

Um den Zugriff auf einen externen Endpunkt über OAuth zu ermöglichen, kann ein Anbietender die folgenden Einträge zur Manifest-Datei hinzufügen:

• EXTERNAL ACCESS INTEGRATION-Referenz mit der Berechtigung USAGE

• SECRET-Referenz mit der Berechtigung READ

Das folgende Beispiel einer Manifest-Datei zeigt, wie Sie diese Referenzen definieren:

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

Referenzen auf Geheimnisse und externe Zugriffsobjekte erfordern ebenfalls eine configuration_callback-Funktion im Setup-Skript. Weitere Informationen dazu finden Sie unter Funktion „configuration_callback“ zu Setup-Skript hinzufügen.

Funktion „configuration_callback“ zu Setup-Skript hinzufügen¶

Nachdem Sie die Verweise für die Integration das Geheimnis und die Integration für den externen Zugriff hinzugefügt haben, müssen Sie die Funktion configuration_callback in das Setup-Skript einfügen. Um eine Integration für den externen Zugriff oder ein Geheimnis zu erstellen, muss die Anwendung in der Lage sein, Werte für den Port des Hosts, den Typ des Geheimnisses, die Autorisierung und den Token-Endpunkt für OAuth usw. zu bestimmen. Mit der Funktion configuration_callback werden diese Informationen der Anwendung vom Verbraucherkonto bereitgestellt.

Snowsight führt diese Callback-Prozedur aus, um den Konfigurationsdialog zu füllen, der den Benutzer auffordert, die Objekte zu konfigurieren. Damit die Prozedur ausgeführt wird, muss sie einer App-Rolle zugewiesen werden.

Die Callback-Funktion hat die folgenden Voraussetzungen:

• Die Callback-Funktion muss ein Argument akzeptieren, das einen Referenznamen enthält. So kann dieselbe Callback-Funktion mehrere Referenzen verarbeiten.

• Die Callback-Funktion muss ein wohlgeformtes JSON-Objekt zurückgeben. Das JSON-Objekt enthält die folgenden Eigenschaften:

  • type

    Gibt den Typ der Meldung an. Gültige Werte:

    • CONFIGURATION: Gibt einen Payload mit den Konfigurationswerten für das Objekt basierend auf dem Objekttyp zurück.

    • ERROR: Gibt einen Fehler mit der zugehörigen Meldung zurück, die in Snowsight angezeigt wird.

  • payload

    Enthält den Inhalt der Antwort basierend auf dem Wert der Eigenschaft type und dem konfigurierten Objekttyp.

Die Signatur für den Konfigurations-Callback ist wie folgt:

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

Innerhalb des Setup-Skripts müssen Sie den Anwendungsrollen, die für die Konfiguration der App verwendet werden, die Berechtigung USAGE zuweisen, damit sie die gespeicherte Prozedur aufrufen dürfen. Das folgende Beispiel zeigt, wie Sie die Berechtigung USAGE einer gespeicherten Prozedur zuweisen:

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

Die Callback-Funktion gibt ein JSON-Objekt zurück. Weitere Informationen dazu finden Sie unter JSON-Format für die Konfigurations-Callback-Antwort.

Das folgende Beispiel zeigt eine typische Callback-Funktion für den Umgang mit Referenzen auf externe Zugriffe und Geheimnisse.

Diese Funktion macht Folgendes:

• Für eine Referenz auf eine Integration für den externen Zugriff gibt die Prozedur ein JSON-Objekt zurück, das die erforderlichen Konfigurationsinformationen enthält. Weitere Informationen dazu finden Sie unter JSON-Format für Integration für den externen Zugriff.

• Für eine Referenz auf ein Geheimnis gibt die Prozedur ein JSON-Objekt zurück, das eine Geheimniskonfiguration vom Typ OAuth2 enthält. Weitere Informationen dazu finden Sie unter JSON-Format bei Geheimnisreferenzen.

  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;

Verwenden der Python Permission SDK für Geheimnisse und Integrationen für den externen Zugriff¶

Das Python Permission SDK unterstützt Geheimnisse und Integrationen für den externen Zugriff. Allerdings ist das Verhalten bei diesen Objekten etwas anders.

Wenn ein Anbieter permission.request_reference() aufruft und den Namen einer Referenz mit einem object_type-Wert von SECRET oder EXTERNAL ACCESS INTEGRATION übergibt, führt Snowsight automatisch Folgendes aus:

• Ruft die Funktion configuration_callback im Setup-Skript auf.

• Validiert die von der Funktion configuration_callback zurückgegebenen Werte.

• Zeigt den Konfigurationsdialog für den Verbraucher an.