Créer et gérer les politiques de filtrage de lignes et de masquage de colonnes

Cette page décrit comment créer, modifier, afficher et supprimer des politiques de filtre de lignes et de masquage de colonnes ABAC dans Unity Catalog. Pour créer et gérer les politiques GRANT (bêta), consultez Politiques ABAC GRANT pour les modèles (bêta). Pour un aperçu des concepts de politique, consultez Concepts de base pour l’ABAC.

Exigences

Toutes les opérations de stratégie (créer, modifier, supprimer, afficher, décrire) nécessitent MANAGE sur l'objet sécurisable ou la propriété de l'objet. La création d’une politique nécessite également :

• Databricks Runtime 16.4 ou version ultérieure, ou compute serverless. Voir les exigences Compute.
• Pour la logique de filtrage ou de masquage, une fonction définie par l'utilisateur (UDF) dans Unity Catalog sur laquelle vous disposez de EXECUTE, ou une fonction SQL que vous définissez en ligne lors de la création de la politique.
• Balises régies appliquées aux objets cibles. Voir Governed tags.

Créer une politique

Vous pouvez créer une politique à l'aide de l'interface utilisateur de l'Explorateur de catalogues, de l'instruction SQL CREATE POLICY, ou des APIs REST, SDK et Terraform de Databricks.

Pour créer une stratégie, vous devez disposer de MANAGE sur l’objet sécurisable auquel la stratégie est associée (catalogue, schéma ou table) ou être propriétaire de l’objet sécurisable, et de EXECUTE sur l’UDF qui implémente la logique de filtrage ou de masquage.

Catalog Explorer

1. Dans votre workspace Databricks, cliquez sur Catalogue .

2. Sélectionnez l’objet qui détermine le périmètre de la stratégie, comme un catalogue, un schéma ou une table.

3. Cliquez sur l'onglet tab .

4. Cliquez sur Nouvelle politique .

5. Complétez la section Identification de la politique . Le tableau suivant synthétise chaque champ :

Champ	Description	Exemple
Nom	Un nom pour la politique. Doit être unique parmi toutes les politiques définies sur le même objet sécurisable.	hide_eu_customers, mask_ssn
Description	Facultatif. Une description de la politique. Apparaît dans les logs d'audit et aide les administrateurs à comprendre l'intention de la politique.	Restrict EU customer rows from US analysts, Mask SSN for all account users

Champ	Description	Exemple
Nom	Un nom pour la politique. Doit être unique parmi toutes les politiques définies sur le même objet sécurisable.	hide_eu_customers, mask_ssn
Description	Facultatif. Une description de la politique. Apparaît dans les logs d'audit et aide les administrateurs à comprendre l'intention de la politique.	Restrict EU customer rows from US analysts, Mask SSN for all account users

6. Complétez la section Principals et périmètre . Le tableau suivant synthétise chaque champ :

Champ	Description	Exemple
Appliqué à…	Les utilisateurs, groupes ou service principals soumis à la politique. Lorsque ces principaux query les tables dans le périmètre, le filtre de ligne ou le masque de colonne est appliqué. Pour appliquer la politique à tous les principaux du compte, sélectionnez All account users.	us_analysts, All account users
À l'exception de	Principaux exemptés de la politique. Les principaux exemptés ne sont pas soumis au filtrage ou au masquage et voient les données complètes et non modifiées.	admins, compliance_team
Portée	L'objet sécurisable auquel la politique est associée. La politique s'évalue par rapport à toutes les tables au sein de l'étendue sélectionnée. Sélectionnez un catalogue, un schéma ou une table. Databricks recommande d'appliquer les politiques au niveau le plus élevé applicable.	Sélectionnez le catalogue prod, puis sélectionnez le schéma customers.
Condition de table	Détermine les tables auxquelles la politique s'applique dans le périmètre. Aucune condition : Applique la politique à toutes les tables dans la portée. Tables correspondant à l'un de ces tags : Applique la politique à la liste spécifiée de clés de tag ou de paires clé-valeur de tag. Les tables qui ont l'une de ces caractéristiques correspondent à la politique. Tables correspondant à une expression personnalisée : Vous pouvez créer une expression booléenne à l'aide de has_tag et has_tag_value, combinée avec AND, OR et NOT pour une logique de correspondance plus complexe. Applique la politique aux tables où l'expression prend la valeur TRUE et correspond à la politique. Si une table dans la portée ne correspond pas à la condition, la règle ne s’applique pas à cette table.	Sélectionnez **Tables correspondant à l'un de ces tags**, puis choisissez sensitivity la clé de tag avec la valeur high pour limiter la politique aux tables sensibles uniquement.

Champ	Description	Exemple
Appliqué à…	Les utilisateurs, groupes ou service principals soumis à la politique. Lorsque ces principaux query les tables dans le périmètre, le filtre de ligne ou le masque de colonne est appliqué. Pour appliquer la politique à tous les principaux du compte, sélectionnez All account users.	us_analysts, All account users
À l'exception de	Principaux exemptés de la politique. Les principaux exemptés ne sont pas soumis au filtrage ou au masquage et voient les données complètes et non modifiées.	admins, compliance_team
Portée	L'objet sécurisable auquel la politique est associée. La politique s'évalue par rapport à toutes les tables au sein de l'étendue sélectionnée. Sélectionnez un catalogue, un schéma ou une table. Databricks recommande d'appliquer les politiques au niveau le plus élevé applicable.	Sélectionnez le catalogue prod, puis sélectionnez le schéma customers.
Condition de table	Détermine les tables auxquelles la politique s'applique dans le périmètre. Aucune condition : Applique la politique à toutes les tables dans la portée. Tables correspondant à l'un de ces tags : Applique la politique à la liste spécifiée de clés de tag ou de paires clé-valeur de tag. Les tables qui ont l'une de ces caractéristiques correspondent à la politique. Tables correspondant à une expression personnalisée : Vous pouvez créer une expression booléenne à l'aide de has_tag et has_tag_value, combinée avec AND, OR et NOT pour une logique de correspondance plus complexe. Applique la politique aux tables où l'expression prend la valeur TRUE et correspond à la politique. Si une table dans la portée ne correspond pas à la condition, la règle ne s’applique pas à cette table.	Sélectionnez **Tables correspondant à l'un de ces tags**, puis choisissez sensitivity la clé de tag avec la valeur high pour limiter la politique aux tables sensibles uniquement.

7. Pour Type de politique , choisissez le type de contrôle d'accès à appliquer :

Option	Description	Quand utiliser
Filtre de ligne	Crée une politique de filtre de lignes. L'UDF évalue chaque ligne et renvoie une valeur booléenne. Les lignes où l'UDF renvoie FALSE sont exclues des résultats de la requête.	L'accès dépend des valeurs de chaque ligne, par exemple le filtrage par les valeurs d'une colonne qui contient des régions géographiques.
Masque de colonne	Crée une politique de masquage de colonne. L'UDF prend la valeur de colonne en entrée et renvoie la version originale ou masquée. Le type de retour doit pouvoir être converti vers le type de données de la colonne cible.	Vous devez masquer les champs sensibles, tels que les numéros de sécurité sociale, les numéros de téléphone ou les adresses e-mail, tout en permettant au principal d'exécuter la query sur la table.

Option	Description	Quand utiliser
Filtre de ligne	Crée une politique de filtre de lignes. L'UDF évalue chaque ligne et renvoie une valeur booléenne. Les lignes où l'UDF renvoie FALSE sont exclues des résultats de la requête.	L'accès dépend des valeurs de chaque ligne, par exemple le filtrage par les valeurs d'une colonne qui contient des régions géographiques.
Masque de colonne	Crée une politique de masquage de colonne. L'UDF prend la valeur de colonne en entrée et renvoie la version originale ou masquée. Le type de retour doit pouvoir être converti vers le type de données de la colonne cible.	Vous devez masquer les champs sensibles, tels que les numéros de sécurité sociale, les numéros de téléphone ou les adresses e-mail, tout en permettant au principal d'exécuter la query sur la table.

8. Les sections suivantes dépendent de votre sélection de type de stratégie . Développez la section qui correspond à votre sélection :

Filtre de ligne

Dans la section Fonction de filtre de ligne , choisissez comment spécifier la fonction de filtre de ligne :

• Sélectionner l’existant : Sélectionnez une UDF déjà définie dans Unity Catalog. L’UDF évalue chaque ligne et renvoie une valeur booléenne. Les lignes où la fonction renvoie FALSE sont exclues des résultats de la query. Vous devez avoir EXECUTE sur l’UDF.
• Créer : définissez une fonction SQL à utiliser comme logique de filtre de lignes.

Dans la section **Entrées de fonction**, fournissez une valeur pour chaque paramètre de fonction. Chaque entrée peut être une colonne associée par des tags, une colonne associée par une expression personnalisée ou une valeur constante.

Masque de colonne

Dans la section Conditions de colonne , choisissez comment identifier les colonnes à masquer :

• Colonnes correspondant à l’une de ces balises : spécifiez une liste de clés de balise ou de paires clé-valeur de balise. Les colonnes qui possèdent l'un de ces éléments sont masquées par la politique.
• **Colonnes correspondant à une expression personnalisée** : Créez une expression booléenne has_tag à has_tag_value l’aide de et, combinée AND à, OR et NOT pour une logique de correspondance plus complexe. Les colonnes où l'expression évalue à TRUE sont masquées.

Ensuite, choisissez la fonction de masquage à appliquer aux colonnes correspondantes :

• Sélectionner l’existant : Sélectionnez une UDF déjà définie dans Unity Catalog. L’UDF renvoie la valeur d’origine ou masquée. Le type de retour doit être compatible avec le type de données de la colonne cible. Vous devez disposer de EXECUTE sur l'UDF.
• Créer : Définir une fonction SQL à utiliser comme logique de masquage de colonne.

Dans la section Function inputs , fournissez une valeur pour chaque parameter de fonction supplémentaire. Chaque entrée peut être une colonne associée par des tags, une colonne associée par une expression personnalisée ou une valeur constante.

Cet exemple utilise une valeur constante de 4 pour afficher les 4 derniers caractères du numéro de sécurité sociale.

9. Cliquez sur Créer une politique .

SQL

Pour une documentation complète, consultez CREATE POLICY.

SQL

CREATE [OR REPLACE] POLICY policy_name
ON { CATALOG catalog_name | SCHEMA schema_name | TABLE table_name }
[COMMENT description]
{ row_filter_body | column_mask_body }

Corps du filtre de lignes :

SQL

ROW FILTER function_name
TO principal [, ...]
[EXCEPT principal [, ...]]
FOR TABLES
[WHEN condition]
[MATCH COLUMNS condition [[AS] alias] [, ...]]
[USING COLUMNS (function_arg [, ...])]

Corps du masque de colonne :

SQL

COLUMN MASK function_name
TO principal [, ...]
[EXCEPT principal [, ...]]
FOR TABLES
[WHEN condition]
[MATCH COLUMNS condition [[AS] alias] [, ...]]
ON COLUMN alias
[USING COLUMNS (function_arg [, ...])]

Paramètres :

• policy_name: Un nom pour la politique. Doit être unique parmi toutes les politiques définies sur le même objet sécurisable.
• ON { CATALOG | SCHEMA | TABLE }: Le périmètre où la politique est attachée. La politique évalue toutes les tables qui sont des descendantes de cet objet sécurisable.
• function_name: Le nom entièrement qualifié de l'UDF qui implémente la logique de filtrage ou de masquage.
• TO principal [, ...]: Les utilisateurs, les groupes ou les Service Principal auxquels la politique s'applique.
• EXCEPT principal [, ...]: Principaux exemptés de la politique. Les principaux exemptés ne sont pas soumis au filtrage ou au masquage.
• FOR TABLES: Spécifie que la politique cible les tables. Les tables sont actuellement le seul type d'objet sécurisable pris en charge, ce qui inclut les tables de streaming et les vues matérialisées.
• WHEN condition: Une expression booléenne qui détermine les tables auxquelles la politique s'applique, en fonction de leurs tags. Utilise les fonctions intégrées has_tag('tag_name') et has_tag_value('tag_name', 'tag_value'). Si omis, default est TRUE (s'applique à toutes les tables dans l'étendue).
• MATCH COLUMNS condition [[AS] alias] [, ...]: Conditions de colonne qui identifient les colonnes ciblées par la politique. Chaque condition est une expression booléenne construite à partir de has_tag('tag_name') et has_tag_value('tag_name', 'tag_value'), éventuellement combinée avec AND, OR et NOT. Chaque condition peut se voir attribuer un alias pour une utilisation dans ON COLUMN et USING COLUMNS. Une politique peut inclure jusqu'à 3 expressions MATCH COLUMNS, et toutes doivent correspondre pour que la politique s'applique.
• ON COLUMN alias: Pour les stratégies de masque de colonne, spécifie la colonne correspondante à masquer, référencée par son alias à partir de MATCH COLUMNS.
• USING COLUMNS (function_arg [, ...]): Arguments passés à l'UDF. Chaque argument peut être un alias de MATCH COLUMNS ou un littéral constant.

Exemple : politique de masquage de colonne. Masquez toutes les colonnes balisées avec pii:ssn dans le schéma prod.customers, en affichant uniquement les 4 derniers caractères. La politique s’applique à us_analysts, sauf admins.

SQL

CREATE FUNCTION ssn_to_last_nr (ssn STRING, nr INT) RETURNS STRING
  RETURN right(ssn, nr);

CREATE POLICY mask_ssn
ON SCHEMA prod.customers
COLUMN MASK ssn_to_last_nr
TO us_analysts EXCEPT admins
FOR TABLES
MATCH COLUMNS has_tag_value('pii', 'ssn') AS ssn
ON COLUMN ssn
USING COLUMNS (4);

Exemple : politique de filtrage de lignes. Excluez les lignes contenant des clients européens des tables marquées avec sensitivity:high dans le schéma prod.customers. La politique s'applique à us_analysts et filtre les lignes en fonction d'une colonne geo_region.

SQL

CREATE FUNCTION non_eu_region (geo_region STRING) RETURNS BOOLEAN
  RETURN geo_region <> 'eu';

CREATE POLICY hide_eu_customers
ON SCHEMA prod.customers
COMMENT 'Exclude rows with European customers from sensitive tables'
ROW FILTER non_eu_region
TO us_analysts
FOR TABLES
WHEN has_tag_value('sensitivity', 'high')
MATCH COLUMNS has_tag('geo_region') AS region
USING COLUMNS (region);

Python SDK

Pour une documentation complète, veuillez consulter la documentation du SDK Databricks pour Python.

Cet exemple crée une politique de filtre de lignes qui exclut les lignes avec des clients européens pour les analystes basés aux États-Unis :

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import (
    FunctionArgument,
    MatchColumn,
    PolicyInfo,
    PolicyType,
    RowFilterOptions,
    SecurableType,
)

w = WorkspaceClient()

w.policies.create_policy(PolicyInfo(
    name="hide_eu_customers",
    comment="Exclude rows with European customers from sensitive tables",
    on_securable_type=SecurableType.SCHEMA,
    on_securable_fullname="prod.customers",
    for_securable_type=SecurableType.TABLE,
    policy_type=PolicyType.POLICY_TYPE_ROW_FILTER,
    to_principals=["us_analysts"],
    match_columns=[
        MatchColumn(condition="has_tag('geo_region')", alias="region"),
    ],
    row_filter=RowFilterOptions(
        function_name="prod.customers.non_eu_region",
        using=[FunctionArgument(alias="region")],
    ),
))

Cet exemple crée une politique de masquage de colonne qui masque les numéros de sécurité sociale pour les analystes américains, à l'exception de ceux du groupe admins :

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import (
    ColumnMaskOptions,
    FunctionArgument,
    MatchColumn,
    PolicyInfo,
    PolicyType,
    SecurableType,
)

w = WorkspaceClient()

w.policies.create_policy(PolicyInfo(
    name="mask_ssn",
    comment="Mask social security numbers",
    on_securable_type=SecurableType.SCHEMA,
    on_securable_fullname="prod.customers",
    for_securable_type=SecurableType.TABLE,
    policy_type=PolicyType.POLICY_TYPE_COLUMN_MASK,
    to_principals=["us_analysts"],
    except_principals=["admins"],
    match_columns=[
        MatchColumn(condition="has_tag_value('pii', 'ssn')", alias="ssn"),
    ],
    column_mask=ColumnMaskOptions(
        function_name="prod.customers.ssn_to_last_nr",
        on_column="ssn",
        using=[FunctionArgument(constant="4")],
    ),
))

Modifier une politique

Catalog Explorer

1. Dans votre workspace Databricks, cliquez sur Catalogue .
2. Sélectionnez l'objet auquel la politique est attachée.
3. Cliquez sur l'onglet tab .
4. Sélectionnez la politique que vous souhaitez modifier.
5. Mettez à jour tous les champs que vous souhaitez modifier. Vous pouvez modifier la description, les principaux, le type de politique, les conditions et les mappages d'entrée de fonction. Le nom de la politique et l'objet sécurisable où la politique est appliquée ne peuvent pas être modifiés. Pour les descriptions de champs, consultez Créer une politique.
6. Cliquez sur **Mettre à jour la politique**.

SQL

CREATE OR REPLACE POLICY remplace l'intégralité de la définition de la politique. Spécifiez toutes les clauses, pas seulement les champs que vous souhaitez modifier. La politique de remplacement doit avoir le même nom et se trouver sur le même objet sécurisable.

SQL

CREATE OR REPLACE POLICY mask_ssn
ON SCHEMA prod.customers
COLUMN MASK ssn_to_last_nr
TO us_analysts EXCEPT admins, compliance_team
FOR TABLES
MATCH COLUMNS has_tag_value('pii', 'ssn') AS ssn
ON COLUMN ssn
USING COLUMNS (4);

Python SDK

Contrairement à CREATE OR REPLACE POLICY dans SQL, update_policy prend en charge les mises à jour partielles. Utilisez le paramètre update_mask pour spécifier les champs à modifier. Seuls ces champs sont mis à jour. Si update_mask est "*" ou vide, tous les champs de policy_info sont appliqués.

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import PolicyInfo

w = WorkspaceClient()

w.policies.update_policy(
    on_securable_type="SCHEMA",
    on_securable_fullname="prod.customers",
    name="mask_ssn",
    policy_info=PolicyInfo(
        except_principals=["admins", "compliance_team"],
    ),
    update_mask="except_principals",
)

Supprimer une politique

Catalog Explorer

1. Dans votre workspace Databricks, cliquez sur Catalogue .
2. Sélectionnez l'objet auquel la politique est attachée.
3. Cliquez sur l'onglet tab .
4. Sélectionnez la politique.
5. Cliquez sur Supprimer la politique .

SQL

Utilisez DROP POLICY pour supprimer une politique.

SQL

DROP POLICY policy_name ON { CATALOG | SCHEMA | TABLE } securable_name

Exemples :

SQL

DROP POLICY mask_ssn ON SCHEMA prod.customers;
DROP POLICY hide_eu_customers ON SCHEMA prod.customers;

Python SDK

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.policies.delete_policy(
    on_securable_type="SCHEMA",
    on_securable_fullname="prod.customers",
    name="mask_ssn",
)

Afficher les politiques

Utilisez SHOW POLICIES pour lister les politiques définies sur un objet sécurisable. Utilisez SHOW EFFECTIVE POLICIES pour également inclure des politiques à partir de portées parentes, telles que les politiques de niveau catalogue qui affectent une table.

SQL

SHOW [EFFECTIVE] POLICIES ON { CATALOG | SCHEMA | TABLE } securable_name

Le résultat inclut le nom de la politique, le type de politique et le catalogue, le schéma ou la table où chaque politique est définie.

La consultation des politiques effectives pour une table ne nécessite pas d'autorisations sur le catalogue ou le schéma parent. Ceci permet à un administrateur de table de voir les règles qui s'appliquent sans avoir d'accès en lecture aux politiques des tables sœurs.

Exemple :

SQL

SHOW EFFECTIVE POLICIES ON SCHEMA prod.customers;

policy_name	policy_type	catalogue	Schéma	Commentaire
hide_eu_customers	Filtre de ligne	prod	Clients
mask_ssn	Masque de colonne	prod	Clients

policy_name	policy_type	catalogue	Schéma	Commentaire
hide_eu_customers	Filtre de ligne	prod	Clients
mask_ssn	Masque de colonne	prod	Clients

Décrire une politique

Utilisez DESCRIBE POLICY pour afficher les détails d'une politique spécifique. Nécessite MANAGE sur l'objet sécurisable cible ou la propriété de l'objet.

SQL

{ DESC | DESCRIBE } POLICY policy_name ON { CATALOG | SCHEMA | TABLE } securable_name

Le résultat affiche les propriétés de la politique sous forme de paires clé-valeur, y compris le nom, le type d'objet sécurisable, le nom d'objet sécurisable, les principaux, les conditions, le nom de la fonction et les Timestamp.

Exemple :

SQL

DESCRIBE POLICY hide_eu_customers ON SCHEMA prod.customers;

info_name	info_value
Nom	hide_eu_customers
Sur le type sécurisable	Schéma
Sur Sécurisable	prod.clients
À Principals	us_analysts
Pour le type sécurisable	Table
Faire correspondre les colonnes	has_tag('geo_region') AS région
Type de politique	ROW_FILTER
Nom de la fonction	prod.clients.non_eu_region
Utilisation des colonnes	Région

info_name	info_value
Nom	hide_eu_customers
Sur le type sécurisable	Schéma
Sur Sécurisable	prod.clients
À Principals	us_analysts
Pour le type sécurisable	Table
Faire correspondre les colonnes	has_tag('geo_region') AS région
Type de politique	ROW_FILTER
Nom de la fonction	prod.clients.non_eu_region
Utilisation des colonnes	Région

Journalisation d'audit

Databricks enregistre les opérations de politique de tag et ABAC régies dans la table système des logs d'audit. Vous trouverez ci-dessous des exemples de queries. Pour plus d'informations, consultez Audit Logs.

SQL

-- All tag assignment and deletion events from the audit log
SELECT
  event_time,
  action_name,
  user_identity.email AS actor,
  request_params.workspace_id,
  request_params.metastore_id,
  request_params.tag_assignment,
  response.status_code,
  source_ip_address
FROM system.access.audit
WHERE service_name = 'unityCatalog'
  AND action_name IN (
    'createEntityTagAssignment',
    'deleteEntityTagAssignment'
  )
ORDER BY event_time DESC;

-- All ABAC policy CRUD operations
SELECT
  event_time,
  action_name,
  user_identity.email AS actor,
  request_params.name AS policy_name,
  request_params.on_securable_type,
  request_params.on_securable_fullname,
  request_params.policy_info,
  response.status_code
FROM system.access.audit
WHERE service_name = 'unityCatalog'
  AND action_name IN ('createPolicy', 'deletePolicy', 'getPolicy', 'listPolicies')
ORDER BY event_time DESC;

Ressources supplémentaires

• Concepts fondamentaux pour l'ABAC
• Évaluation des politiques de filtre de lignes et de masque de colonne et comportement d'exécution
• Considérations de performances pour les politiques de filtrage de lignes et de masquage de colonnes
• Didacticiels ABAC
• Tags gouvernés
• Fonctions définies par l'utilisateur Unity Catalog