Verwenden von programmatische Zugriffstoken für die Authentifizierung¶

Anforderungen der Netzwerkrichtlinie¶

Standardmäßig muss der Benutzer einer Netzwerkrichtlinie mit einer oder mehreren Netzwerkregeln unterliegen, um programmatische Zugriffstoken zu erzeugen oder zu verwenden:

• Für Dienstbenutzer (wobei TYPE=SERVICE für den Benutzer) können Sie nur dann ein Token erzeugen oder verwenden, wenn der Benutzer einer Netzwerkrichtlinie unterliegt.

  Diese Voraussetzung schränkt die Verwendung des Tokens auf Anfragen von einer bestimmten Gruppe von Adressen oder Bezeichnern des Netzwerks ein.

• Für menschliche Benutzer (bei denen TYPEPERSON für den Benutzer angegeben ist) können Sie ein Token generieren, auch wenn der Benutzer keiner Netzwerkrichtlinie unterliegt. Der Benutzer muss jedoch einer Netzwerkrichtlinie unterliegen, um sich mit diesem Token authentifizieren zu können.

  Wenn ein menschlicher Benutzer, der keiner Netzwerkrichtlinie unterliegt, ein programmatisches Zugriffstoken für die Authentifizierung verwenden muss, können Sie die Anforderung einer Netzwerkrichtlinie vorübergehend umgehen. Wir raten jedoch davon ab. Siehe Generierung eines programmatischen Zugriffstokens.

  Bemerkung

  Benutzer können die Netzwerkrichtlinie selbst nicht umgehen.

Die Netzwerkrichtlinie kann für alle Benutzer des Kontos oder für einen bestimmten Benutzer aktiviert werden.

Um diese Anforderung zu ändern, erstellen oder ändern Sie eine Authentifizierungsrichtlinie, die eine programmatische Access-Token-Richtlinie festlegt.

Führen Sie den Befehl CREATE AUTHENTICATION POLICY oder ALTER AUTHENTICATION POLICY aus. Setzen Sie NETWORK_POLICY_EVALUATION in der Klausel PAT_POLICY auf einen der folgenden Werte:

ENFORCED_REQUIRED (Standard-Verhaltensweise)

Der Benutzer muss einer Netzwerkrichtlinie unterliegen, um programmatische Zugriffstoken zu erstellen und zu verwenden.

Wenn der Benutzer einer Netzwerkrichtlinie unterliegt, wird die Netzwerkrichtlinie während der Authentifizierung durchgesetzt.

ENFORCED_NOT_REQUIRED

Der Benutzer muss nicht einer Netzwerkrichtlinie unterliegen, um programmatische Zugriffstoken zu erstellen und zu verwenden.

Wenn der Benutzer einer Netzwerkrichtlinie unterliegt, wird die Netzwerkrichtlinie während der Authentifizierung durchgesetzt.

NOT_ENFORCED

Der Benutzer muss nicht einer Netzwerkrichtlinie unterliegen, um programmatische Zugriffstoken zu erstellen und zu verwenden.

Wenn der Benutzer einer Netzwerkrichtlinie unterliegt, wird die Netzwerkrichtlinie nicht während der Authentifizierung durchgesetzt.

So können Sie beispielsweise eine Authentifizierungsrichtlinie erstellen, die die Netzwerkrichtlinienanforderung aufhebt, aber alle Netzwerkrichtlinien durchsetzt, denen der Benutzer unterliegt:

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED
  );

Dann wenden Sie die Authentifizierungsrichtlinie auf ein Konto oder einen Benutzer an.

Ein weiteres Beispiel ist die Änderung einer bestehenden Authentifizierungsrichtlinie, um die Anforderung der Netzwerkrichtlinie zu entfernen und die Durchsetzung von Netzwerkrichtlinien zu verhindern, denen der Benutzer unterliegt:

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    NETWORK_POLICY_EVALUATION = NOT_ENFORCED
  );

Anforderungen der Authentifizierungsrichtlinie¶

Wenn es eine Authentifizierungsrichtlinie gibt, die die Authentifizierungsmethoden für einen Benutzer einschränkt, kann der Benutzer keine programmatischen Zugriffstoken erstellen und verwenden, es sei denn, die Liste der AUTHENTICATION_METHODS in dieser Richtlinie enthält 'PROGRAMMATIC_ACCESS_TOKEN'.

Angenommen eine Authentifizierungsrichtlinie beschränkt die Benutzer auf die Methoden OAuth und Kennwort zur Authentifizierung:

CREATE AUTHENTICATION POLICY my_auth_policy
  ...
  AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD')
  ...

Benutzer können keine programmgesteuerten Zugriffstoken erstellen und verwenden, wenn Sie 'PROGRAMMATIC_ACCESS_TOKEN' nicht zur Liste AUTHENTICATION_METHODS hinzufügen. Sie können den Befehl ALTER AUTHENTICATION POLICY verwenden, um diese Liste zu aktualisieren.

Beispiel:

ALTER AUTHENTICATION POLICY my_auth_policy
  SET AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD', 'PROGRAMMATIC_ACCESS_TOKEN');

Festlegen der maximalen Ablaufzeit¶

Standardmäßig können Sie für ein Token eine Ablaufzeit von bis zu 365 Tagen angeben. Wenn Sie diese Zeitspanne verkürzen möchten, erstellen oder ändern Sie eine Authentifizierungsrichtlinie, die eine programmatische Zugriffstokenrichtlinie mit einer maximalen Ablaufzeit festlegt.

Führen Sie den Befehl CREATE AUTHENTICATION POLICY oder ALTER AUTHENTICATION POLICY aus. Setzen Sie in der Klausel PAT_POLICY MAX_EXPIRY_IN_DAYS auf einen Wert zwischen 1 und 365.

Um beispielsweise eine Authentifizierungsrichtlinie zu erstellen, die das Maximum auf 100 Tage festlegt:

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    MAX_EXPIRY_IN_DAYS=100
  );

Dann wenden Sie die Authentifizierungsrichtlinie auf ein Konto oder einen Benutzer an.

Ein weiteres Beispiel: Sie möchten eine bestehende Authentifizierungsrichtlinie ändern und die Höchstdauer auf 90 Tage festlegen:

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    MAX_EXPIRY_IN_DAYS=90
  );

Festlegen der Standardablaufzeit¶

Standardmäßig läuft ein programmatisches Zugriffstoken nach 15 Tagen ab. Wenn Sie dies ändern möchten, erstellen oder ändern Sie eine Authentifizierungsrichtlinie, die eine programmatische Zugriffstoken-Richtlinie mit einem Standardablaufdatum angibt.

Führen Sie den Befehl CREATE AUTHENTICATION POLICY oder ALTER AUTHENTICATION POLICY aus. Legen Sie in der Klausel PAT_POLICY DEFAULT_EXPIRY_IN_DAYS auf einen Wert zwischen 1 und der maximalen Verfallszeit <label-pat_maximum_expiration_time> fest.

Um beispielsweise eine Authentifizierungsrichtlinie zu erstellen, die das Maximum auf 5 Tage festlegt:

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    DEFAULT_EXPIRY_IN_DAYS=5
  );

Dann wenden Sie die Authentifizierungsrichtlinie auf ein Konto oder einen Benutzer an.

Ein weiteres Beispiel: Sie möchten eine bestehende Authentifizierungsrichtlinie ändern, um die Standardeinstellung auf 30 Tage zu setzen:

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    DEFAULT_EXPIRY_IN_DAYS=30
  );

Verwendung eines programmatischen Zugriffstokens als Kennwort¶

Um sich mit einem programmatischen Zugriffstoken als Kennwort zu authentifizieren, können Sie den Token als Wert für das Kennwort in den Treibereinstellungen oder im Aufruf zum Herstellen einer Verbindung mit Snowflake angeben.

Wenn Sie zum Beispiel den Snowflake Connector für Python verwenden, können Sie das programmatische Zugriffstoken als password Argument angeben, wenn Sie die Methode snowflake.connector.connect aufrufen.

conn = snowflake.connector.connect(
    user=USER,
    password=<programmatic_access_token>,
    account=ACCOUNT,
    warehouse=WAREHOUSE,
    database=DATABASE,
    schema=SCHEMA
)

Auf die gleiche Weise können Sie in Anwendungen von Drittanbietern (wie Tableau oder PowerBI) programmatische Zugriffstoken anstelle eines Kennworts verwenden. Fügen Sie das programmatische Zugriffstoken in das Feld für das Kennwort ein.

Verwendung eines programmatischen Zugriffstokens zur Authentifizierung bei einem Endpunkt¶

Um sich mit einem programmatischen Zugriffstoken zu authentifizieren, setzen Sie die folgenden HTTP-Header in der Anfrage:

• Authorization: Bearer token_secret

• X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN (optional)

Wenn Sie zum Beispiel cURL verwenden, um eine Anfrage an einen Snowflake REST-API-Endpunkt zu senden:

curl --location 'https://myorganization-myaccount.snowflakecomputing.com/api/v2/databases' \
  --header "Authorization: Bearer <token_secret>"

Ein weiteres Beispiel: Sie verwenden cURL, um eine Anfrage an den Snowflake SQL API-Endpunkt zu senden:

curl -si -X POST https://myorganization-myaccount.snowflakecomputing.com/api/v2/statements \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer <token_secret>" \
  --data '{"statement": "select 1"}'

Wenn die Anfrage mit einem PAT_INVALID-Fehler fehlschlägt, kann der Fehler aus einem der folgenden Gründe aufgetreten sein:

• Der Benutzer, der mit dem programmatischen Zugriffstoken verbunden ist, wurde nicht gefunden.

• Validierung fehlgeschlagen.

• Die mit dem programmatischen Zugriffstoken verbundene Rolle wurde nicht gefunden.

• Der Benutzer ist nicht mit dem angegebenen programmatischen Zugriffstoken verbunden.

Auflistung der programmatischen Zugriffstoken¶

Sie können das programmatische Zugriffstoken für einen Benutzer in Snowsight auflisten oder indem Sie SQL-Befehle ausführen.

SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER example_user;

Umbenennen eines programmatischen Zugriffstokens¶

Sie können den Namen eines programmatischen Zugriffstokens in Snowsight oder durch die Ausführung von SQL-Befehlen ändern.

Rotieren eines programmatischen Zugangstokens¶

Sie können ein programmatisches Zugriffstoken in Snowsight oder durch die Ausführung von SQL-Befehlen rotieren.

Das Rotieren eines Tokens liefert ein neues Token-Geheimnis, das denselben Namen und eine verlängerte Ablaufzeit hat. Durch das Rotieren eines Tokens erlischt auch das bestehende Token-Geheimnis. Verwenden Sie das neue Token für die Authentifizierung bei Snowflake.

ALTER USER IF EXISTS example_user ROTATE PROGRAMMATIC ACCESS TOKEN example_token;

ALTER USER IF EXISTS example_user
  ROTATE PROGRAMMATIC ACCESS TOKEN example_token
  EXPIRE_ROTATED_TOKEN_AFTER_HOURS = 0;

+---------------+-----------------+-------------------------------------+
| token_name    | token_secret    | rotated_token_name                  |
|---------------+-----------------+-------------------------------------|
| EXAMPLE_TOKEN | ... (token) ... | EXAMPLE_TOKEN_ROTATED_1744239049066 |
+---------------+-----------------+-------------------------------------+

Widerrufen eines programmatischen Zugriffstokens¶

Sie können ein programmatisches Zugriffstoken in Snowsight oder durch die Ausführung von SQL-Befehlen widerrufen.

ALTER USER IF EXISTS example_user REMOVE PROGRAMMATIC ACCESS TOKEN example_token;