Configurer l'autorisation dans une application Databricks

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. Comme les applications accèdent aux données et aux services au sein d’un Workspace, elles doivent utiliser une authentification et une autorisation qui appliquent les contrôles d’accès aux données et respectent les permissions des utilisateurs.

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 fait office 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é entre plusieurs 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, de sorte que l'application ne peut accéder qu'aux ressources qui lui ont été explicitement accordées, même en dehors du contexte d'interaction avec l'utilisateur.

Cette séparation applique des limites de sécurité entre les applications. Cela rend également l'activité de l'application auditable 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 de l'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 : requête 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

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.

Permissions granulaires avec autorisation 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 à une application pour la première fois, Databricks l'invite à accorder à l'application l'autorisation d'agir dans le cadre de chaque périmètre demandé. Après avoir accordé leur consentement, les utilisateurs ne peuvent pas le révoquer. Les administrateurs peuvent, s'ils le souhaitent, accorder leur consentement au nom des utilisateurs afin d'aligner l'accès sur les politiques de l'organisation.

Ajouter des étendues à une application

Ajoutez des portées d'autorisation dans l'interface utilisateur Databricks ou avec la CLI Databricks.

UI

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.

CLI

Transmettez user_api_scopes lors de la création ou de la mise à jour d'une application :

Bash

databricks apps create <app-name> \
  --json '{
    "user_api_scopes": ["sql", "files"]
  }'

Bash

databricks apps create-update <app-name> \
  --json '{
    "update_mask": "user_api_scopes",
    "app": {
      "user_api_scopes": ["sql", "files"]
    }
  }'

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.

Périmètres pris en charge

Databricks Apps prend en charge les étendues d'API Databricks suivantes :

• ai-gateway
• apps
• files
• genie
• model-serving
• postgres
• sql
• vector-search
• sql:restricted-query (exécuter des requêtes SQL en lecture seule)

Databricks Apps prend également en charge les portées SDK suivantes. Ces portées peuvent utiliser le modificateur :read pour restreindre l'accès aux endpoints GET.

• catalog.catalogs
• catalog.connections
• catalog.schemas
• catalog.tables
• workspace.workspace

Les périmètres suivants sont obsolètes. Utilisez plutôt le périmètre actuel.

Portée obsolète	Portée actuelle
dashboards.genie	genie
files.files	files
serving.serving-endpoints	model-serving
serving.serving-endpoints-data-plane	model-serving
sql.alerts	sql
sql.alerts-legacy	sql
sql.dashboards	sql
sql.data-sources	sql
sql.dbsql-permissions	sql
sql.queries	sql
sql.queries-legacy	sql
sql.query-history	sql
sql.statement-execution	sql
sql.warehouses	sql
vectorsearch.vector-search-endpoints	vector-search
vectorsearch.vector-search-indexes	vector-search

Portée obsolète	Portée actuelle
dashboards.genie	genie
files.files	files
serving.serving-endpoints	model-serving
serving.serving-endpoints-data-plane	model-serving
sql.alerts	sql
sql.alerts-legacy	sql
sql.dashboards	sql
sql.data-sources	sql
sql.dbsql-permissions	sql
sql.queries	sql
sql.queries-legacy	sql
sql.query-history	sql
sql.statement-execution	sql
sql.warehouses	sql
vectorsearch.vector-search-endpoints	vector-search
vectorsearch.vector-search-indexes	vector-search

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.

UI

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 All APIs , ce qui autorise tous les périmètres pris en charge. La sélection de None désactive l’autorisation utilisateur.

CLI

Utilisez la CLI Databricks pour obtenir ou mettre à jour la liste des autorisations de scope.

Pour obtenir le paramètre actuel :

Bash

databricks workspace-settings-v2 get-public-workspace-setting allowedAppsUserApiScopes

Pour définir des périmètres autorisés spécifiques :

Bash

databricks workspace-settings-v2 patch-public-workspace-setting allowedAppsUserApiScopes \
  --json '{
    "allowed_apps_user_api_scopes": {
      "allowed_scopes": ["sql", "files"]
    },
    "name": "allowedAppsUserApiScopes"
  }'

Pour autoriser tous les périmètres (default) :

Bash

databricks workspace-settings-v2 patch-public-workspace-setting allowedAppsUserApiScopes \
  --json '{
    "allowed_apps_user_api_scopes": {
      "allowed_scopes": ["*"]
    },
    "name": "allowedAppsUserApiScopes"
  }'

Pour désactiver l'autorisation utilisateur, définissez allowed_scopes sur un tableau vide ([]).

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 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 utilisateur

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.
• N'imprimez pas, ne consignez pas dans des logs et n'écrivez pas de jetons dans des fichiers. Ceci s'applique à toutes les instructions de journalisation, aux outils de debugging et aux 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.
• Enregistrez des logs d'audit structurés pour chaque action effectuée par votre application au nom des utilisateurs, y compris l'identité de l'utilisateur, le type d'action, la ressource cible et le statut.

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