Location multiple pour les Agents Cortex¶

Comment fonctionne la location multiple¶

Lorsque vous appelez l’API agent:run, vous pouvez inclure un bloc variables qui définit un ou plusieurs attributs de session immuables. La politique d’accès aux lignes de votre table fait référence à ces attributs pour filtrer les données du locataire actuel.

Le flux d’exécution est le suivant :

1. Vous appelez une API agent:run avec un bloc variables qui inclut des valeurs spécifiques au locataire.

2. Avant d’exécuter du SQL généré, les attributs sont définis sur la session Snowflake.

3. Le SQL généré s’exécute dans la session où les variables sont actives.

4. La politique d’accès aux lignes sur la table évalue les attributs de session et filtre les lignes en conséquence.

Attributs de session¶

Le bloc variables prend en charge des attributs de session immuables, configurés à l’aide de is_immutable_session_attribute: true. Une fois que la valeur d’un attribut est définie, elle ne peut pas être modifiée par le SQL généré, l’exécution de code ou l’invocation d’outil pendant la session. Ainsi, le contexte du locataire ne peut pas être modifié pendant l’exécution de l’agent.

Pour configurer des attributs de session dans le bloc variables, dans l’API agent:run, utilisez le paramètre suivant :

Configurer les variables dans agent:run¶

Transmettez les variables dans l’API agent:run pour définir le contexte du locataire pour chaque appel :

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{agent_name}:run

{
    "variables": {
        "region": {
            "value": "NORTH",
            "type": "string",
            "is_immutable_session_attribute": true
        }
    }
}

Dans cet exemple, region est défini comme attribut de session immuable. La clé est region et la valeur est NORTH. La valeur est définie avant l’exécution de la requête, afin que la politique d’accès aux lignes puisse y faire référence. Les attributs de session persistent pendant la durée de l’interaction et ne peuvent pas être écrasés.

Politiques d’accès aux lignes avec des attributs de session¶

Pour appliquer l’isolation des locataires, Snowflake recommande fortement d’utiliser un attribut de session dans une politique d’accès aux lignes. La politique filtre les lignes de manière à ce que chaque locataire ne voie que ses propres données.

Créer une politique d’accès aux lignes

L’exemple suivant crée une politique d’accès aux lignes qui filtre les lignes en fonction de l’attribut de session region :

-- Create a row access policy that filters by the region session attribute
CREATE OR REPLACE ROW ACCESS POLICY rap_region_filter
  AS (region_col STRING) RETURNS BOOLEAN ->
    region_col = SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'region');

Appliquez la politique à votre table :

-- Apply the row access policy to the sales table
ALTER TABLE db1.schema1.sales
  ADD ROW ACCESS POLICY rap_region_filter ON (region);

Lorsque l’agent exécute une requête sur la table sales, la politique d’accès aux lignes évalue l’attribut de session region et ne renvoie que les lignes où la colonne region correspond à la valeur définie dans l’appel agent:run.

Meilleures pratiques¶

Suivez ces recommandations lors de la configuration de la location multiple avec des Agents Cortex :

• Utilisez des attributs de session immuables pour les politiques d’accès aux lignes. Définissez is_immutable_session_attribute: true pour n’importe quelle variable référencée par une politique d’accès aux lignes. Les attributs immuables ne peuvent pas être modifiés par du SQL généré ou une exécution d’outil.

• Limitez la portée des variables au strict minimum. Définissez uniquement les variables nécessaires à chaque invocation. Ne transmettez pas de variables dont l’agent n’a pas besoin pour la requête en cours.

• Testez vos politiques d’accès aux lignes indépendamment. Vérifiez que vos politiques d’accès aux lignes filtrent correctement en les testant avec des instructions SET en dehors de l’agent avant le déploiement.

Contrôle d’accès¶

Le tableau suivant décrit les privilèges requis pour la configuration de la location multiple :

Limitations¶

Les limites suivantes s’appliquent à la location multiple avec les Agents Cortex :

• Portée de la session : Les attributs de session persistent pendant la durée de l’interaction et ne peuvent pas être écrasés.

Snowflake fournit des attributs de session immuables et des politiques d’accès aux lignes comme outils d’isolation des locataires. Il vous appartient de les configurer correctement pour faire respecter les limites de votre locataire.