Autorisatie configureren in een Databricks-app

Het Databricks Apps-autorisatiemodel is gebaseerd op OAuth 2.0 en combineert de machtigingen die zijn toegewezen aan de app met die van de gebruiker die toegang tot de app heeft. Omdat apps toegang krijgen tot data en diensten binnen een werkruimte, moeten ze authenticatie en autorisatie gebruiken die toegangscontroles voor gegevens afdwingen en gebruikersrechten respecteren.

Ter ondersteuning van dit framework maakt Databricks Apps gebruik van twee aanvullende identiteitsmodellen:

• App-autorisatie geeft de app een eigen identiteit met een consistente set machtigingen.
• Met gebruikersautorisatie kan de app de identiteit en machtigingen van de gebruiker gebruiken die ermee communiceert.

App-autorisatie

Elke Azure Databricks-app heeft een toegewezen service-principal die fungeert als identiteit wanneer deze toegang heeft tot Azure Databricks resources. Deze service-principal is uniek voor het app-exemplaar en kan niet opnieuw worden gebruikt in alle apps. U kunt de service-principal die is toegewezen aan een app niet wijzigen of een bestaande service-principal opgeven tijdens het maken van de app. Azure Databricks gebruikt deze identiteit om de rechten van de app onafhankelijk van een gebruiker te evalueren, zodat de app alleen toegang heeft tot middelen die expliciet aan de app zijn toegekend, zelfs buiten de context van gebruikersinteractie.

Deze scheiding handhaaft beveiligingsgrenzen tussen apps. Het maakt ook app-activiteit auditbaar en ondersteunt scenario's zoals achtergrondverwerking of geautomatiseerde taken.

De service-principal wordt vertegenwoordigd door een unieke id. Kopieer deze vanuit het tabblad Autorisatie van de app:

Wanneer u een app maakt, richt Azure Databricks automatisch een toegewezen service-principal voor de app in. De service-principal blijft hetzelfde voor alle implementaties van de app. Wanneer u de app verwijdert, zal Azure Databricks de service-principal verwijderen.

Gebruik de service-principal voor acties die de app zelfstandig uitvoert, zonder dat hiervoor de context van een afzonderlijke gebruiker is vereist. Veelvoorkomende gebruiksvoorbeelden zijn:

• Achtergrondtaken uitvoeren
• Gedeelde configuratie of metagegevens lezen of schrijven
• Metrische gegevens over activiteiten of gebruik registreren
• Externe services aanroepen via beveiligde eindpunten

Alle acties die door de app worden gestart, gebruiken de machtigingen van de service-principal. Ververleent de service-principal toegang tot specifieke resources met behulp van standaardmachtigingstoewijzingen. Het biedt echter geen ondersteuning voor toegangsbeheer op gebruikersniveau. Alle gebruikers die met de app werken, delen dezelfde machtigingen die zijn gedefinieerd voor de service-principal, waardoor de app geen fijnmazig beleid afdwingt op basis van afzonderlijke gebruikersidentiteit.

In het volgende voorbeeld ziet u hoe een app de service-principal gebruikt om query's uit te voeren op gegevens in Unity Catalog:

In dit geval heeft de service-principal expliciete toegang nodig tot zowel het SQL-warehouse als de Unity Catalog-tabel waarin deze query's opgeeft.

Dit model werkt goed wanneer u wilt dat alle gebruikers van de app dezelfde gegevens zien of wanneer de app gedeelde bewerkingen uitvoert die niet zijn gekoppeld aan gebruikersspecifieke toegangsbeheer.

Haal app-autorisatiegegevens op

Voor app-autorisatie injecteert Azure Databricks automatisch service-principal-referenties in de omgeving van de app. De volgende omgevingsvariabelen bevatten de vereiste OAuth-clientwaarden:

Variable	Description
DATABRICKS_CLIENT_ID	OAuth-client-id voor service-principal
DATABRICKS_CLIENT_SECRET	OAuth-clientgeheim voor service-principal

Azure Databricks stelt de omgevingsvariabelen automatisch in de app-runtime in. De app gebruikt deze variabelen wanneer hij zichzelf authenticeert.

Python

import os

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

JavaScript

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

Note

Als u de Databricks SDK's gebruikt, hoeft u doorgaans geen handmatige toegang te krijgen tot deze omgevingsvariabelen. De SDK's volgen geïntegreerde verificatie en detecteren automatisch referenties in de omgeving.

Voorbeeld: Query met appautorisatie

Python

In dit voorbeeld wordt het SDK-configuratieobject gebruikt, waarmee referenties van de service-principal worden opgehaald uit omgevingsvariabelen en OAuth-autorisatie wordt uitgevoerd.

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

In dit voorbeeld worden omgevingsvariabelen gebruikt om te verifiëren met een service-principal met behulp van OAuth en een query uit te voeren met het Databricks SQL-stuurprogramma voor Node.js.

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();

Gebruikersautorisatie

Met gebruikersautorisatie, ook wel on-behalf-of-user authorization genoemd, kan een Databricks Apps-app handelen met de identiteit van de app-gebruiker. Azure Databricks het toegangstoken van de gebruiker doorstuurt naar de app, die het token gebruikt om namens de gebruiker toegang te krijgen tot resources. Azure Databricks dwingt alle machtigingen af op basis van de bestaande Unity Catalog-beleidsregels van de gebruiker.

Voor het beheren van de beveiligingsrisico's van apps die namens een gebruiker handelen, gebruikt Azure Databricks toepassingsbereiken om te beperken welke handelingen een app kan uitvoeren via gebruikersautorisatie.

Pas gebruikersautorisatie toe wanneer de app afzonderlijke gebruikersmachtigingen moet respecteren. Typische gebruiksvoorbeelden zijn onder andere:

• Query's uitvoeren op tabellen of volumes
• Toegang tot SQL-warehouses of rekenkracht
• Taken of werkstromen uitvoeren die zijn gekoppeld aan gebruikersacties

Alle acties maken gebruik van de bestaande Unity Catalog-machtigingen van de gebruiker:

Met gebruikersautorisatie kunt u nauwkeurig toegangsbeheer toepassen door Unity Catalog-functies zoals filters op rijniveau en kolommaskers toe te passen op app-activiteit. Deze aanpak houdt toegangsbeheer consistent met werkruimtebeheer en vermijdt de logica voor het coderen van machtigingen in de app.

Fijnmazige rechten met gebruikersautorisatie

Wanneer u gebruikersautorisatie toevoegt aan een app, worden de bestaande Unity Catalog-machtigingen van de gebruiker afgedwongen, waaronder:

• Filters op rijniveau om zichtbare rijen te beperken
• Kolommaskers voor het redacteren of transformeren van gevoelige gegevens

Omdat Azure Databricks aanvragen voor gebruikersautorisatie evalueert met de identiteit van de gebruiker, worden deze beleidsregels automatisch toegepast wanneer de app toegang heeft tot gegevens. Als een tabel bijvoorbeeld een rijfilter bevat dat de zichtbaarheid per regio beperkt, retourneert de app alleen de rijen waarop de gebruiker een query mag uitvoeren. Er is geen extra filterlogica nodig in de app.

Deze aanpak voorkomt het dupliceren van logica voor toegangsbeheer in toepassingscode en zorgt voor consistentie met governance op werkruimteniveau. Wanneer beheerders Unity Catalog-beleid bijwerken, respecteert de app deze wijzigingen automatisch.

Escalatie van beveiliging en bevoegdheden op basis van bereik

Apps die gebruikersautorisatie gebruiken, moeten specifieke autorisatiebereiken declareren om te beperken wat de app namens de gebruiker kan doen. Scopes beperken de toegang tot specifieke API's of resourcetypen, zoals:

• sql voor het uitvoeren van query's op SQL-warehouses
• genie voor het beheren van uw Genie Agent
• files voor het beheren van uw bestanden en mappen

Als u geen scopes selecteert, wijst Azure Databricks een standaard-set toe waarmee de app basisgegevens over gebruikersidentiteit kan ophalen.

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

Deze standaardinstellingen zijn vereist voor de ondersteuning van de functionaliteit voor gebruikersautorisatie, maar ze staan geen toegang tot gegevens of rekenresources toe. Voeg extra machtigingen toe wanneer u de app maakt of bewerkt.

Bereiken dwingen het principe van minimale bevoegdheden af. Zorg ervoor dat u de app configureert om alleen de machtigingen aan te vragen die nodig zijn. Azure Databricks blokkeert de toegang tot functionaliteit buiten de goedgekeurde bereiken, zelfs als de gebruiker toestemming heeft. Als de app bijvoorbeeld alleen de sql scope aanvraagt, heeft deze geen toegang tot de model-serving eindpunten, zelfs niet als de gebruiker buiten de app wel toegang zou kunnen hebben.

Wanneer een gebruiker voor het eerst toegang krijgt tot een app, vraagt Azure Databricks hem of haar om de app toestemming te geven om binnen elke gevraagde scope te handelen. Na het verlenen van toestemming kunnen gebruikers deze niet intrekken. Beheerders kunnen optioneel toestemming verlenen namens gebruikers om de toegang af te stemmen op organisatiebeleid.

Bereiken toevoegen aan een app

Voeg autorisatiescopes toe in de Azure Databricks UI of met de Databricks CLI.

UI (Gebruikersinterface)

Configureer gebruikersautorisatie wanneer u een app maakt of bewerkt in de gebruikersinterface van Azure Databricks.

Klik onder Gebruikersautorisatie op +Scope toevoegen en selecteer de scopes die bepalen tot welke Azure Databricks API's of resources de app namens de gebruiker toegang heeft. Azure Databricks handhaaft deze scopes tijdens runtime en vereist toestemming van de gebruiker of beheerder voordat toegang wordt verleend.

CLI (Command Line Interface)

Geef user_api_scopes mee bij het maken of bijwerken van een app:

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

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

Zie de demo Databricks Apps-autorisatie op GitHub voor een volledig voorbeeld. De voorbeeld-app laat zien hoe u zowel app- als gebruikersautorisatiemodellen gebruikt, en bevat installatie-instructies en voorbeeldquery's met gebruikersautorisatie.

Ondersteunde toepassingsgebieden

Azure Databricks Apps ondersteunt de volgende Azure Databricks API scopes:

• ai-gateway
• apps
• files
• genie
• model-serving
• postgres
• sql
• vector-search
• sql:restricted-query (voert alleen-lezende SQL-queries uit)

Azure Databricks Apps ondersteunt ook de volgende SDK-scopes. Deze scopes kunnen de :read modifier gebruiken om de toegang tot GET eindpunten te beperken.

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

De volgende scopes zijn verouderd. Gebruik in plaats daarvan het huidige bereik.

Verouderde reikwijdte	Huidige reikwijdte
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

Gebruikersautorisatiebereiken beperken

Werkruimtebeheerders kunnen bepalen welke OAuth-scopes app-ontwikkelaars mogen toevoegen aan apps in de werkruimte.

UI (Gebruikersinterface)

1. Klik op uw gebruikersnaam in de bovenste balk van de Azure Databricks-werkruimte en selecteer Instellingen.
2. Klik op Ontwikkeling.
3. Zoek onder Apps de OAuth-bereiken voor apps beperken tot geselecteerde waardeninstelling en configureer de acceptatielijst.
4. Vernieuw de pagina om de wijziging van kracht te laten worden.

De standaardwaarde is Alle API's, wat alle ondersteunde scopes toestaat. Als u Geen selecteert, wordt gebruikersautorisatie uitgeschakeld.

CLI (Command Line Interface)

Gebruik de Databricks CLI om de scope-allowlist op te vragen of bij te werken.

Om de huidige instelling te krijgen:

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

Om specifieke toegestane scopes in te stellen:

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

Om alle scopes toe te staan (standaard):

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

Om gebruikersautorisatie uit te schakelen, stel allowed_scopes in op een lege array ([]).

Accountbeheerders kunnen scopes aan apps toevoegen, zelfs als die scopes niet in de allowlist van de werkruimte staan.

Note

Apps die al actief zijn, blijven werken met hun bestaande scopes. U kunt een app pas starten, uitrollen of bijwerken nadat u de niet-toegestane scopes hebt verwijderd.

Haal gebruikersautorisatiegegevens op

Voor gebruikersautorisatie stuurt Azure Databricks de identiteit en het toegangstoken van de gebruiker door naar de app in HTTP-headers. De app moet deze headers extraheren om namens de gebruiker te handelen.

Hoe u deze headers ophaalt, is afhankelijk van het framework dat u gebruikt.

Streamlit

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

Gradio

import gradio as gr

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

Gradio injecteert het aanvraagobject automatisch in de functie van uw app als u het declareert als parameter. U hoeft de aanvraag niet handmatig samen te stellen of op te halen.

Dash en Flask

from flask import request

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

Shiny

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

Express

import express from 'express';

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

Voorbeeld: Vraag met gebruikersautorisatie

In dit geval geeft de app het toegangstoken van de gebruiker rechtstreeks door aan de connector en Azure Databricks de machtigingen van de gebruiker op de query toepast.

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

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);

Best practices voor gebruikersautorisatie

Wanneer u apps bouwt die acties uitvoeren namens gebruikers, volgt u deze aanbevolen procedures om veilige en controleerbare toegang te garanderen:

• Sla app-code op in mappen die alleen toegankelijk zijn voor de eigenaar van de app of een kleine set vertrouwde gebruikers.
• Verken CAN MANAGE alleen machtigingen aan vertrouwde senior ontwikkelaars die verantwoordelijk zijn voor app-onderhoud en beoordeling. Verwijs CAN USE alleen machtigingen aan specifieke gebruikers of groepen die zijn goedgekeurd om de app uit te voeren.
• Print niet, log of schrijf geen tokens naar bestanden. Dit geldt voor alle logboekregistratie-instructies, foutopsporingsprogramma's en fouthandlers. Bijvoorbeeld, in plaats van print(f"User token: {token}") te gebruiken headers = {"Authorization": f"Bearer {token}"}.
• Configureer elke app om alleen de minimaal vereiste autorisatiebereiken aan te vragen die nodig zijn voor de functionaliteit ervan.
• Controleer tijdens het controleren van de code of de bereik- en machtigingsinstellingen zijn afgestemd op beveiligingsvereisten en geef geen onnodige toegang.
• Peer review afdwingen voor alle app-code voordat ze worden geïmplementeerd in productieomgevingen.
• Registreer gestructureerde auditlogs voor elke actie die je app namens gebruikers uitvoert, inclusief de gebruikersidentiteit, actietype, doelbron en status.

Verificatiemethoden

Voor het verkrijgen van tokens voor Databricks-apps worden zowel gebruikers als service-principals geverifieerd met behulp van standaard OAuth 2.0-stromen. De methode is afhankelijk van of de aanroeper een gebruiker of een geautomatiseerde workload is.

Voor aanmelding bij de werkruimte (alleen gebruikers):

• Eenmalige aanmelding (SSO): Gebruikers verifiëren zich via uw id-provider wanneer eenmalige aanmelding (SSO) is geconfigureerd.
• Eenmalig wachtwoord (OTP): Gebruikers ontvangen een tijdelijk wachtwoord als eenmalige aanmelding niet is geconfigureerd.

Voor OAuth-stromen (apps en workloads):

• OAuth van gebruiker naar machine (U2M): Gebruikers verifiëren en de resulterende tokens maken gebruikersautorisatie mogelijk, zodat de app namens de gebruiker kan handelen.
• OAuth van machine-naar-machine (M2M): Service-principalen authenticeren met behulp van clientreferenties of federatie. Deze tokens ondersteunen app-autorisatie, waarbij de app als zichzelf fungeert in plaats van een gebruiker.

Zie Verbinding maken met een API Databricks-app met behulp van tokenverificatie voor instructies voor het aanroepen van een Databricks-app met behulp van tokenverificatie.

Modellen vergelijken en combineren

Databricks-apps kunnen app- en gebruikersautorisatie onafhankelijk of samen gebruiken. Deze modellen dienen verschillende doeleinden en zijn ontworpen om parallel te werken.

Autorisatiemodel	Wanneer te gebruiken	Voorbeelden van gebruikssituaties
App-autorisatie	Wanneer de app bewerkingen uitvoert die niet afhankelijk zijn van de identiteit van de gebruiker	Logboeken schrijven, toegang krijgen tot gedeelde configuratie, externe services aanroepen
Gebruikersautorisatie	Wanneer de app toegang nodig heeft tot resources in de context van de huidige gebruiker	Query's uitvoeren op Unity Catalog-gegevens, berekening starten, machtigingen op rijniveau afdwingen
Both	Wanneer de app zowel gedeelde als gebruikersspecifieke bewerkingen uitvoert	Metrische gegevens vastleggen met app-identiteit, gefilterde gegevens opvragen met gebruikersidentiteit