Configurer l'autorisation dans une application Databricks

Databricks Apps prend en charge le développement d'applications sécurisées sur Databricks. Comme les applications accèdent aux données et aux services au sein d'un Workspace, elles doivent utiliser des mécanismes d'authentification et d'autorisation qui appliquent des contrôles d'accès aux données et respectent les autorisations des utilisateurs. Le modèle d'autorisation Databricks Apps est basé sur OAuth 2.0 et combine les autorisations attribuées à l'application avec celles de l'utilisateur qui y accède.

Pour prendre en charge ce cadre, Databricks Apps utilise deux modèles d'identité complémentaires :

• ** L'autorisation d'application ** confère à l'application sa propre identité avec un ensemble cohérent d'autorisations.
• L'autorisation de l'utilisateur permet à l'application d'utiliser l'identité et les autorisations de l'utilisateur qui interagit avec elle.

Autorisation de l’application

Chaque application Databricks dispose d'un Service Principal dédié qui lui sert d'identité lorsqu'elle accède aux Ressources Databricks. Ce Service Principal est unique à l'instance de l'application et ne peut pas être réutilisé pour d'autres applications. Vous ne pouvez pas modifier le Service Principal attribué à une application ni spécifier un Service Principal existant lors de la création de l'application. Databricks utilise cette identité pour évaluer les autorisations de l'application indépendamment de tout utilisateur, ce qui garantit que l'application ne peut accéder qu'aux Ressources qui lui sont explicitement accordées, même en dehors du contexte d'interaction avec l'utilisateur.

Cette séparation permet de renforcer les limites de sécurité, ce qui permet l'audit de l'activité des applications et prend en charge des scénarios tels que le traitement en arrière-plan ou les tâches automatisées.

Le Service Principal est représenté par un ID unique. Copiez-le depuis l’onglet Autorisation de l’application :

Lorsque vous créez une application, Databricks provisionne automatiquement un Service Principal dédié pour l'application. Le Service Principal reste le même pour tous les déploiements de l'application. Lorsque vous supprimez l'application, Databricks supprime le Service Principal.

Utilisez le Service Principal pour les actions que l'application effectue seule, sans nécessiter le contexte d'un utilisateur individuel. Les cas d’utilisation courants incluent :

• Exécution de tâches en arrière-plan
• Lecture ou écriture d'une configuration partagée ou de métadonnées
• Journalisation de l'activité ou des métriques d'utilisation
• Appel de services externes via des Endpoint sécurisés

Toutes les actions initiées par l'application utilisent les autorisations du service principal. Accordez au Service Principal l'accès à des Ressources spécifiques en utilisant des attributions d'autorisations standard. Cependant, il ne prend pas en charge le contrôle d'accès au niveau de l'utilisateur. Tous les utilisateurs qui interagissent avec l'application partagent les mêmes autorisations définies pour le Service Principal, ce qui empêche l'application d'appliquer des politiques détaillées basées sur l'identité de l'utilisateur individuel.

L'exemple suivant montre comment une application utilise son Service Principal pour interroger des données dans Unity Catalog :

Dans ce cas, le Service Principal a besoin d'un accès explicite au SQL Warehouse et à la table Unity Catalog qu'il interroge.

Ce modèle fonctionne bien lorsque vous voulez que tous les utilisateurs de l'application voient les mêmes données ou lorsque l'application effectue des Opérations partagées non liées à des contrôles d'accès spécifiques à l'utilisateur.

Récupérer les informations d'identification d'autorisation d'application

Pour l'autorisation de l'application, Databricks injecte automatiquement les identifiants du Service Principal dans l'environnement de l'application. Les variables d’environnement suivantes contiennent les valeurs client OAuth requises :

Variable	Description
DATABRICKS_CLIENT_ID	ID client OAuth du Service Principal
DATABRICKS_CLIENT_SECRET	Secret client OAuth du Service Principal

Variable	Description
DATABRICKS_CLIENT_ID	ID client OAuth du Service Principal
DATABRICKS_CLIENT_SECRET	Secret client OAuth du Service Principal

Databricks définit automatiquement les variables d'environnement dans l'environnement d'exécution de l'application. L'application utilise ces variables lorsqu'elle s'authentifie en tant que telle.

Python

Python

import os

client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')

JavaScript

JavaScript

const clientId = process.env.DATABRICKS_CLIENT_ID;
const clientSecret = process.env.DATABRICKS_CLIENT_SECRET;

remarque

Si vous utilisez les SDK Databricks, vous n'avez généralement pas besoin d'accéder manuellement à ces variables d'environnement. Les SDKs suivent une authentification unifiée et détectent automatiquement les identifiants dans l'environnement.

Exemple : Query avec autorisation d'application

Python

Cet exemple utilise l'objet Config du SDK, qui récupère les identifiants du service principal à partir des variables d'environnement et effectue l'autorisation OAuth.

Python

from databricks import sql
from databricks.sdk.core import Config

cfg = Config()

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    credentials_provider=lambda: cfg.authenticate,
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

JavaScript

Cet exemple utilise des variables d'environnement pour s'authentifier avec un Service Principal à l'aide d'OAuth et exécuter une query avec le Driver Databricks SQL pour Node.js.

JavaScript

import { DBSQLClient } from '@databricks/sql';

const client = new DBSQLClient();

const connection = await client.connect({
  authType: 'databricks-oauth',
  host: process.env.DATABRICKS_SERVER_HOSTNAME,
  path: process.env.DATABRICKS_HTTP_PATH,
  oauthClientId: process.env.DATABRICKS_CLIENT_ID,
  oauthClientSecret: process.env.DATABRICKS_CLIENT_SECRET,
});

const query = 'SELECT * FROM main.sandbox.sales_customers LIMIT 1000';
const cursor = await connection.cursor(query);

const rows = [];
for await (const row of cursor) {
  rows.push(row);
}

console.log(rows.slice(0, 5)); // Like df.head()

await connection.close();

Autorisation de l'utilisateur

info

Aperçu

L'autorisation utilisateur est en Aperçu public.

L'autorisation utilisateur, parfois appelée autorisation au nom de l'utilisateur , permet à une application Databricks Apps d'agir avec l'identité de l'utilisateur de l'application. Databricks transmet le jeton d'accès de l'utilisateur à l'application, qui utilise le jeton pour accéder aux ressources au nom de l'utilisateur. Databricks applique toutes les autorisations en fonction des politiques Unity Catalog existantes de l'utilisateur.

Pour gérer les risques de sécurité des applications agissant au nom d'un utilisateur, Databricks utilise des périmètres pour limiter les actions qu'une application peut effectuer via l'autorisation de l'utilisateur.

Appliquez l'autorisation utilisateur lorsque l'application doit respecter les autorisations individuelles de l'utilisateur. Les cas d'utilisation typiques incluent :

• Exécution de queries sur des tables ou des volumes
• Accéder aux SQL Warehouse ou au compute
• Exécution de Jobs ou de workflows liés aux actions de l'utilisateur

Toutes les actions utilisent les autorisations Unity Catalog existantes de l’utilisateur :

L'autorisation utilisateur permet un contrôle d'accès granulaire en appliquant des fonctionnalités d'Unity Catalog, telles que les filtres au niveau des lignes et les masques de colonne, à l'activité de l'application. Cette approche assure la cohérence du contrôle d'accès avec la gouvernance du Workspace et évite de coder en dur la logique d'autorisation dans l'application.

Autorisations granulaires avec autorisation de l'utilisateur

Lorsque vous ajoutez l'autorisation d'utilisateur à une application, celle-ci applique les autorisations Unity Catalog existantes de l'utilisateur, notamment :

• Filtres au niveau des lignes pour restreindre les lignes visibles
• Masques de colonne pour masquer ou transformer des données sensibles

Puisque Databricks évalue les requêtes d'autorisation de l'utilisateur avec l'identité de l'utilisateur, ces politiques s'appliquent automatiquement lorsque l'application accède aux données. Par exemple, si une table inclut un filtre de ligne qui limite la visibilité par région, l'application ne renvoie que les lignes que l'utilisateur est autorisé à interroger. Aucune logique de filtrage supplémentaire n'est nécessaire dans l'application.

Cette approche évite de dupliquer la logique de contrôle d'accès dans le code de l'application et assure la cohérence avec la gouvernance au niveau du workspace. Lorsque les administrateurs mettent à jour les politiques Unity Catalog, l'application respecte automatiquement ces changements.

Sécurité basée sur la portée et escalade de privilèges

Les applications qui utilisent l'autorisation de l'utilisateur doivent déclarer des périmètres d'autorisation spécifiques afin de limiter ce que l'application peut faire au nom de l'utilisateur. Les portées restreignent l'accès à des APIs ou à des types de ressources spécifiques, tels que :

• sql pour interroger les SQL Warehouses
• genie pour la gestion de votre Genie Agent
• files pour gérer vos fichiers et répertoires

Si vous ne sélectionnez aucun périmètre, Databricks attribue un ensemble par default qui permet à l'application de récupérer les informations d'identité utilisateur de base :

• iam.access-control:read
• iam.current-user:read

Ces default sont nécessaires pour prendre en charge la fonctionnalité d'autorisation de l'utilisateur, mais ils n’autorisent pas l’accès aux données ou aux Ressources compute. Ajoutez des périmètres supplémentaires lorsque vous créez ou modifiez l'application.

Les portées appliquent le principe du moindre privilège. Assurez-vous de configurer l'application pour qu'elle ne demande que les étendues dont elle a besoin. Databricks bloque l’accès à toute fonctionnalité en dehors des étendues approuvées, même si l’utilisateur a l’autorisation. Par exemple, si l'application ne demande que le périmètre sql, elle ne peut pas accéder aux Endpoint de service de modèles, même si l'utilisateur le pouvait en dehors de l'application.

Lorsqu'un utilisateur accède pour la première fois à une application, Databricks lui demande d'autoriser explicitement l'application à agir dans les périmètres demandés. Après avoir accordé le consentement, les utilisateurs ne peuvent pas le révoquer.

Ajouter des étendues à une application

info

Aperçu

L'autorisation utilisateur est en préversion publique. L'administrateur de votre Workspace doit l'activer avant que vous ne puissiez ajouter des portées à votre application.

Après avoir activé l'autorisation utilisateur, vous devez redémarrer les applications existantes avant de pouvoir y ajouter des périmètres. Si vous désactivez l’autorisation utilisateur, vous devez redémarrer les applications existantes afin qu’elles cessent d’utiliser le jeton d’accès de l’utilisateur actuel pour accéder aux Ressources.

Configurez l’autorisation utilisateur lorsque vous créez ou modifiez une application dans l’interface utilisateur Databricks.

Sous Autorisation de l'utilisateur , cliquez sur +Ajouter un périmètre et sélectionnez les périmètres qui définissent les APIs ou les ressources Databricks auxquelles l'application peut accéder au nom de l'utilisateur. Databricks applique ces périmètres au moment de l'exécution et exige le consentement de l'utilisateur ou de l'administrateur avant d'accorder l'accès.

Pour un exemple complet, consultez la démonstration d'autorisation Databricks Apps sur GitHub. L'application exemple montre comment utiliser les modèles d'autorisation d'application et d'utilisateur, et inclut des instructions de configuration et des queries exemples avec autorisation de l'utilisateur.

Restreindre les périmètres d'autorisation utilisateur

Les administrateurs de Workspace peuvent contrôler les périmètres OAuth que les développeurs d'applications sont autorisés à ajouter aux applications dans le Workspace.

1. Cliquez sur votre nom d'utilisateur dans la barre supérieure du workspace Databricks et sélectionnez **Paramètres**.
2. Cliquez sur Développement .
3. Sous **Applications**, recherchez le paramètre **Restreindre les étendues OAuth pour les applications aux valeurs sélectionnées** et configurez la liste blanche.
4. Refresh la page pour que la modification prenne effet.

La valeur **default** est **Toutes les APIs**, ce qui autorise tous les périmètres pris en charge. La sélection de Aucun(e) désactive l'autorisation de l'utilisateur.

Les administrateurs de compte peuvent ajouter des étendues aux applications même si ces étendues ne figurent pas dans la liste verte du workspace.

remarque

Les applications déjà en cours d'exécution continuent de s'exécuter avec leurs étendues existantes. Vous ne pouvez pas start, déployer ou mettre à jour une application tant que vous n'avez pas supprimé les étendues non autorisées.

Récupérer les informations d'identification d'autorisation utilisateur

Pour l'autorisation de l'utilisateur, Databricks transmet l'identité et le jeton d'accès de l'utilisateur à l'application dans des en-têtes HTTP. L'application doit extraire ces en-têtes pour agir au nom de l'utilisateur.

La manière dont vous récupérez ces en-têtes dépend du framework que vous utilisez.

Streamlit

Python

import streamlit as st
user_access_token = st.context.headers.get('x-forwarded-access-token')

Gradio

Python

import gradio as gr

def query_fn(message, history, request: gr.Request):
    access_token = request.headers.get("x-forwarded-access-token")
    ...

Gradio injecte automatiquement l’objet de demande dans la fonction de votre application si vous le déclarez comme un parameter. Vous n’avez pas à construire ou à récupérer la demande manuellement.

Dash and Flask

Python

from flask import request

headers = request.headers
user_token = headers.get('x-forwarded-access-token')

Shiny

Python

user_token = session.http_conn.headers.get('x-forwarded-access-token')

Express

JavaScript

import express from 'express';

const userAccessToken = req.header('x-forwarded-access-token');

Exemple : query avec autorisation d’utilisateur

Dans ce cas, l'application transmet le jeton d'accès de l'utilisateur directement au connecteur, et Databricks applique les autorisations de l'utilisateur à la query.

Python

Python

from databricks import sql
from databricks.sdk.core import Config
from flask import request

cfg = Config()
user_token = request.headers.get("x-forwarded-access-token")

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    access_token=user_token
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

JavaScript

JavaScript

import { DBSQLClient } from '@databricks/sql';
import express from 'express';

const app = express();

app.get('/', async (req, res) => {
  const userToken = req.header('x-forwarded-access-token');

  const client = new DBSQLClient();
  const connection = await client.connect({
    authType: 'access-token',
    host: process.env.DATABRICKS_SERVER_HOSTNAME,
    path: process.env.DATABRICKS_HTTP_PATH,
    token: userToken,
  });

  const query = 'SELECT * FROM main.sandbox.sales_customers LIMIT 1000';
  const cursor = await connection.cursor(query);

  const rows = [];
  for await (const row of cursor) {
    rows.push(row);
  }

  console.log(rows.slice(0, 5));
  await connection.close();

  res.send('Query complete');
});

app.listen(3000);

Bonnes pratiques pour l'autorisation des utilisateurs

Lorsque vous créez des applications qui effectuent des actions au nom des utilisateurs, suivez ces meilleures pratiques pour garantir un accès sécurisé et vérifiable :

• Stockez le code de l'application dans des dossiers accessibles uniquement au propriétaire de l'application ou à un petit groupe d'utilisateurs de confiance.
• N'accordez les autorisations CAN MANAGE qu'aux développeurs seniors de confiance qui sont responsables de la maintenance et de la révision des applications. Accordez uniquement les autorisations CAN USE à des utilisateurs ou groupes spécifiques autorisés à exécuter l'application.
• Assurez-vous que les jetons ne sont pas imprimés, journalisés ou écrits dans des fichiers. Ceci s'applique à toutes les déclarations de journalisation, les outils de debugging et les gestionnaires d'erreurs. Par exemple, au lieu de print(f"User token: {token}"), utilisez headers = {"Authorization": f"Bearer {token}"}.
• Configurez chaque application de manière à ne demander que les périmètres d'autorisation minimaux requis pour son fonctionnement.
• Lors de l'examen du code, vérifiez que les paramètres de portée et d'autorisations sont conformes aux exigences de sécurité et n'accordent pas un accès inutile.
• Appliquez l'examen par les pairs pour tout le code de l'application avant de le déployer dans les environnements de production.
• Assurez-vous que le code de votre application enregistre des Logs d'audit structurés pour chaque action effectuée au nom des utilisateurs, y compris l'identité de l'utilisateur, le type d'action, la Ressource cible et l'état.

Méthodes d'authentification

Pour obtenir des jetons pour Databricks Apps, les utilisateurs et les Service Principal s'authentifient en utilisant les flux OAuth 2.0 standards. La méthode dépend du fait que l'appelant est un utilisateur ou une charge de travail automatisée.

Pour la connexion au Workspace (utilisateurs uniquement) :

• Single Sign On (SSO) : les utilisateurs s'authentifient auprès de votre fournisseur d'identité lorsque le Single Sign On (SSO) est configuré.
• Mot de passe à usage unique (OTP) : Les utilisateurs reçoivent un mot de passe temporaire si le SSO n'est pas configuré.

Pour les flux OAuth (applications et charges de travail) :

• OAuth d'utilisateur à machine (U2M): Les utilisateurs s'authentifient, et les jetons qui en résultent permettent l'autorisation de l'utilisateur afin que l'application puisse agir au nom de l'utilisateur.
• ** OAuth machine-to-machine (M2M):** Les service principals s'authentifient à l'aide d'identifiants client ou de la fédération. Ces jetons sont à la base de l'autorisation d'application, où l'application agit en son nom plutôt qu'au nom d'un utilisateur.

Pour les instructions sur l'appel d'une application Databricks à l'aide de l'authentification par jeton, consultez Connectez-vous à une application Databricks API à l'aide de l'authentification par jeton.

Comparez et combinez les modèles

Les Databricks Apps peuvent utiliser l'autorisation d'application et d'utilisateur indépendamment ou conjointement. Ces modèles servent à des fins différentes et sont conçus pour fonctionner en parallèle.

Modèle d'autorisation	Quand utiliser	Exemples de cas d'usage
Autorisation d'application	Lorsque l'application effectue des opérations qui ne dépendent pas de l'identité de l'utilisateur	Écriture des logs, accès à la configuration partagée, appel de services externes
Autorisation utilisateur	Lorsque l'application a besoin d'accéder aux ressources dans le contexte de l'utilisateur actuel	Interrogation des données Unity Catalog, lancement de compute, application des autorisations au niveau des lignes
Les deux	Lorsque l'application effectue à la fois des opérations partagées et des opérations spécifiques à l'utilisateur	Journalisation des métriques avec l’identité de l’application, interrogation des données filtrées avec l’identité de l’utilisateur

Modèle d'autorisation	Quand utiliser	Exemples de cas d'usage
Autorisation d'application	Lorsque l'application effectue des opérations qui ne dépendent pas de l'identité de l'utilisateur	Écriture des logs, accès à la configuration partagée, appel de services externes
Autorisation utilisateur	Lorsque l'application a besoin d'accéder aux ressources dans le contexte de l'utilisateur actuel	Interrogation des données Unity Catalog, lancement de compute, application des autorisations au niveau des lignes
Les deux	Lorsque l'application effectue à la fois des opérations partagées et des opérations spécifiques à l'utilisateur	Journalisation des métriques avec l’identité de l’application, interrogation des données filtrées avec l’identité de l’utilisateur