Authentifizieren mit einem Identitätsanbietertoken

Auf dieser Seite wird erläutert, wie Sie sich bei Azure Databricks mit einem token authentifizieren, das vom Identitätsanbieter Ihrer Organisation ausgestellt wurde.

Azure Databricks unterstützt OAuth 2.0 Token Exchange , damit Sie ein Verbundidentitätstoken für ein Databricks OAuth-Token austauschen können. Mit dem Tokenverbund können databricks CLI, SDKs und andere Tools diesen Austausch automatisch verarbeiten und Zugriffstoken für Sie verwalten.

Die Lebensdauer jedes Zugriffstokens wird von der Lebensdauer des von Ihnen bereitgestellten Verbundtokens abgeleitet, das am häufigsten eine Stunde ist, kann jedoch variieren. Die Tools aktualisieren Token bei Bedarf automatisch, sodass Sie keine Anmeldeinformationen manuell anfordern oder drehen müssen.

Authentifizierungsprozess

Um den Azure Databricks-API-Zugriff mit einem Token von einem Verbundidentitätsanbieter zu authentifizieren, legen Sie zuerst die erforderlichen Umgebungsvariablen oder Konfigurationsfelder fest. Ihr bevorzugtes Tool oder SDK ruft das JSON-Webtoken (JWT) aus dem von Ihnen angegebenen Speicherort ab, tauscht es für ein Azure Databricks OAuth-Token aus und verwendet das OAuth-Token zum Authentifizieren von Azure Databricks REST-API-Aufrufen.

Voraussetzungen

Führen Sie vor Beginn die folgenden Schritte aus:

1. Erstellen Sie eine Verbundrichtlinie für Ihr Konto oder Ihren Dienstprinzipal.
2. Rufen Sie einen gültigen JWT von Ihrem Identitätsanbieter ab, der der Richtlinie entspricht. Token müssen mit RS256 oder ES256 signiert werden. Die Schritte variieren je nach Anbieter. Wenden Sie sich also an die Dokumentation Ihres Anbieters, oder bitten Sie einen Administrator.

Konfigurieren Ihrer Umgebung

Konfigurieren Sie Ihre Umgebung basierend auf dem Ort, von dem Ihr Verbundtoken stammt. Legen Sie die folgenden Umgebungsvariablen, .databrickscfg Felder, Terraform-Felder oder Config Felder fest:

• Databricks-Host:https://accounts.azuredatabricks.net für Kontovorgänge oder die Ziel-URL pro Arbeitsbereich, z. B https://adb-1234567890123456.7.azuredatabricks.net . für Arbeitsbereichsvorgänge.
• Databricks-Konto-ID: Nur erforderlich, wenn der Host die Kontokonsolen-URL ist.
• Dienstprinzipalclient-ID: Nur für den Verbund der Workloadidentität erforderlich. Darf nicht festgelegt werden, wenn die Authentifizierung mithilfe einer kontoweiten Tokenverbundrichtlinie erfolgt.
• Databricks-Authentifizierungstyp:env-oidc wenn das Token aus einer Umgebungsvariable stammt. file-oidc wenn das Token aus einer Datei stammt.
• OIDC-Tokenumgebungsvariable: Der Name der Umgebungsvariable, die das Token enthält. Nur erforderlich, wenn die Authentifizierungsmethode lautet env-oidc. Wird standardmäßig auf DATABRICKS_OIDC_TOKEN festgelegt.
• OIDC-Tokendateipfad: Pfad zur Datei, die das Verbundtoken enthält. Nur erforderlich, wenn die Authentifizierungsmethode lautet file-oidc.

Eine vollständige Referenz zu allen Variablen und Konfigurationsfeldern der einheitlichen Authentifizierung finden Sie unter Umgebungsvariablen und -felder für die einheitliche Authentifizierung.

Wählen Sie Ihre bevorzugte Konfigurationsmethode aus, um die Authentifizierungsumgebung einzurichten:

Umwelt

Legen Sie die folgenden Umgebungsvariablen fest:

export DATABRICKS_HOST=<workspace-url-or-account-console-url>
export DATABRICKS_ACCOUNT_ID=<account-id>  # If DATABRICKS_HOST is the account console URL
export DATABRICKS_CLIENT_ID=<client-id>    # Only for workload identity federation
export DATABRICKS_AUTH_TYPE=<auth-method> # env-oidc or file-oidc
export DATABRICKS_OIDC_TOKEN_ENV=<token-env-name>  # If auth type is env-oidc
export DATABRICKS_OIDC_TOKEN_FILEPATH=<token-filepath-name> # If auth type is file-oidc

Profile

Erstellen oder Identifizieren eines .databrickscfgKonfigurationsprofils mit den folgenden Feldern:

[<profile-name>]
host = <workspace-url-or-account-console-url>
account_id = <account-id>  # If host is the account console URL
client_id = <client-id>    # Only for workload identity federation
auth_type = <auth-method>  # env-oidc or file-oidc
oidc_token_env = <token-env-name>  # If auth type is env-oidc
oidc_token_filepath = <token-filepath-name> # If auth type is file-oidc

Befehlszeilenschnittstelle (CLI)

Führen Sie für Databricks CLI eine der folgenden Aktionen aus:

• Legen Sie die Umgebungsvariablen auf der Registerkarte " Umgebung " wie angegeben fest.
• Legen Sie die Werte in Ihrer .databrickscfg Datei wie auf der Registerkarte "Profil" angegeben fest.

Umgebungsvariablen haben immer Vorrang vor den Werten in Ihrer .databrickscfg-Datei.

Verbinden

Für Databricks Connect können Sie eine der folgenden Aktionen ausführen:

• Verwenden eines Konfigurationsprofils: Legen Sie Arbeitsbereichswerte in Ihrer .databrickscfg Datei fest, wie auf der Registerkarte „Profil“ beschrieben. Setzen Sie außerdem die cluster_id URL auf die Arbeitsbereichsinstanz.
• Verwenden sie Umgebungsvariablen: Legen Sie die gleichen Werte wie auf der Registerkarte " Umgebung " fest. Legen Sie außerdem die DATABRICKS_CLUSTER_ID URL der Arbeitsbereichsinstanz fest.

Werte in .databrickscfg haben Vorrang vor Umgebungsvariablen.

Informationen zum Initialisieren von Databricks Connect mit diesen Einstellungen finden Sie unter Computekonfiguration für Databricks Connect.

VS-Code

Für die Databricks-Erweiterung für Visual Studio Code gehen Sie folgendermaßen vor:

1. Legen Sie die Werte in Ihrer .databrickscfg Datei für Vorgänge auf Arbeitsbereichsebene im Azure Databricks-Arbeitsbereich fest, wie auf der Registerkarte "Profil" angegeben.
2. Wählen Sie in der Databricks-Erweiterung für Visual Studio Code im Bereich Konfiguration die Option Databricks konfigurieren aus.
3. Geben Sie in der Befehlspalette als Databricks-Host Ihre arbeitsbereichsspezifische URL ein, z. B https://adb-1234567890123456.7.azuredatabricks.net, und drücken Sie dann Enter.
4. Wählen Sie in der Befehlspalette den Namen Ihres Zielprofils in der Liste für Ihre URL aus.

Weitere Informationen finden Sie unter Einrichten der Autorisierung für die Databricks-Erweiterung für Visual Studio Code.

Terraform

Für Vorgänge auf Kontoebene

provider "databricks" {
  alias = "accounts"
}

Für Vorgänge auf Arbeitsbereichsebene:

provider "databricks" {
  alias = "workspace"
}

Python

Für Vorgänge auf Arbeitsbereichsebene:

from databricks.sdk import WorkspaceClient

# Uses environment configuration automatically
w = WorkspaceClient()

Für Vorgänge auf Kontoebene:

from databricks.sdk import AccountClient

# Uses environment configuration automatically
a = AccountClient()

Java

Für Vorgänge auf Arbeitsbereichsebene:

import com.databricks.sdk.WorkspaceClient;

// Uses environment configuration automatically
WorkspaceClient w = new WorkspaceClient();

Für Vorgänge auf Kontoebene:

import com.databricks.sdk.AccountClient;

// Uses environment configuration automatically
AccountClient a = new AccountClient();

Go

Für Vorgänge auf Arbeitsbereichsebene:

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
w := databricks.Must(databricks.NewWorkspaceClient())

Für Vorgänge auf Kontoebene:

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
a := databricks.Must(databricks.NewAccountClient())

Weitere Informationen zur Authentifizierung mit Databricks-Tools und -SDKs, die Go verwenden und die einheitliche Databricks-Clientauthentifizierung implementieren, finden Sie unter Authentifizieren des Databricks SDK für Go bei Ihrem Azure Databricks-Konto oder -Arbeitsbereich.

Access Databricks-APIs

Nachdem Sie Ihre Umgebung konfiguriert haben, können Sie die Databricks CLI und SDKs normal verwenden. Sie behandeln automatisch den Tokenaustausch und verwenden das resultierende OAuth-Token für die API-Authentifizierung.

Befehlszeilenschnittstelle (CLI)

databricks clusters list

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()  # Uses environment configuration
clusters = w.clusters.list()

Java

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();
List<ClusterDetails> clusters = w.clusters().list();

Go

import "github.com/databricks/databricks-sdk-go"

w := databricks.Must(databricks.NewWorkspaceClient())
clusters := w.Clusters.ListAll(context.Background(), compute.List{})

Implementieren eines benutzerdefinierten Autorisierungsanbieters

Wenn Ihr Verbundtoken von einer anderen Quelle als Umgebungsvariablen oder einer Datei stammt, können Sie eine der Azure Databricks-SDKs verwenden, um eine benutzerdefinierte Implementierung zum Abrufen Ihres Verbundtokens zu schreiben.

Python

from databricks.sdk import oidc
from databricks.sdk.core import (Config, CredentialsProvider, credentials_strategy, oidc_credentials_provider)


class MyCustomIdTokenSource(oidc.IdTokenSource):
    def id_token(self) -> oidc.IdToken:
        token = ...  # Implement logic to return the ID token here
        return oidc.IdToken(jwt=token)


@credentials_strategy("my-custom-oidc", "")
def my_custom_oidc_strategy(cfg: Config) -> CredentialsProvider:
    return oidc_credentials_provider(cfg, MyCustomIdTokenSource())


if __name__ == "__main__":
    cfg = Config(
        host="https://my-workspace.cloud.databricks.com",
        credentials_strategy=my_custom_oidc_strategy
    )
    from databricks.sdk import WorkspaceClient
    w = WorkspaceClient(config=cfg)
    # Use the client...

Java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
import com.databricks.sdk.core.CredentialsProvider;
import com.databricks.sdk.core.oauth.IDTokenSource;
import com.databricks.sdk.core.oauth.IDToken;

public class CustomOIDCExample {

    // Custom IDTokenSource that returns an OIDC ID token
    static class MyCustomIdTokenSource implements IDTokenSource {
        @Override
        public IDToken getIDToken(String audience) {
            // TODO: Implement logic to fetch or generate the ID token
            String jwt = "...";  // your OIDC token here
            return new IDToken(jwt);
        }
    }

    public static void main(String[] args) {
        // TODO: Wrap MyCustomIdTokenSource in a CredentialsProvider
        // See the SDK documentation for the appropriate method
        CredentialsProvider provider = ...; // Configure with MyCustomIdTokenSource

        // Configure with workspace host and custom OIDC provider
        DatabricksConfig cfg = new DatabricksConfig()
            .setHost("https://my-workspace.cloud.databricks.com")
            .setCredentialsProvider(provider);

        // Initialize the workspace client
        WorkspaceClient w = new WorkspaceClient(cfg);

        System.out.println("Databricks client initialized: " + w);

        // Use the client...
    }
}

Go

package main

import (
    "context"
    "fmt"

    "github.com/databricks/databricks-sdk-go"
    "github.com/databricks/databricks-sdk-go/config"
    "github.com/databricks/databricks-sdk-go/credentials"
)

// MyCustomIdTokenSource implements a custom OIDC token source
type MyCustomIdTokenSource struct{}

func (s *MyCustomIdTokenSource) IDToken(ctx context.Context) (*credentials.IDToken, error) {
    // TODO: Implement logic to return the ID token
    token := "..."
    return &credentials.IDToken{JWT: token}, nil
}

// myCustomOIDCStrategy is a custom credentials strategy
func myCustomOIDCStrategy(cfg *config.Config) (credentials.CredentialsProvider, error) {
    return credentials.NewOIDCCredentialsProvider(cfg, &MyCustomIdTokenSource{}), nil
}

func main() {
    cfg := &config.Config{
        Host: "https://my-workspace.cloud.databricks.com",
    }

    // Register the custom credentials strategy
    credentials.Register("my-custom-oidc", myCustomOIDCStrategy)

    // Initialize the Databricks workspace client with custom auth
    w, err := databricks.NewWorkspaceClientWithConfig(cfg)
    if err != nil {
        panic(err)
    }

    fmt.Println("Databricks client initialized:", w)
    // Use the client...
}

Manuelles Austauschen eines Tokens

Wenn Sie keine Azure Databricks-SDKs, CLI oder andere Tools verwenden, die die einheitliche Authentifizierung unterstützen, können Sie einen JWT manuell von Ihrem Identitätsanbieter für ein Databricks OAuth-Token austauschen. Senden Sie dazu eine Anforderung an den Azure Databricks-Tokenendpunkt mithilfe von OAuth 2.0 Token Exchange (RFC 8693).

Rufen Sie zuerst einen Verbund-JWT von Ihrem Identitätsanbieter ab, nachdem sie die Dokumentation ausgeführt haben. Tauschen Sie dann das JWT für ein Databricks OAuth-Token aus und verwenden Sie dieses Token für den Zugriff auf Databricks-REST-APIs:

Tauschen Sie ein föderiertes JWT gegen ein Databricks-OAuth-Token ein

Bei kontoweiten Verbundrichtlinien tauscht dieser Befehl einen Verbund-JWT für ein Databricks OAuth-Token aus:

curl --request POST https://<databricks-workspace-host>/oidc/v1/token \
  --data "subject_token=${FEDERATED_JWT_TOKEN}" \
  --data 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data 'scope=all-apis'

Fügen Sie für Dienstprinzipalverbundrichtlinien die Client-ID in die Anforderung ein:

curl --request POST https://<databricks-workspace-host>/oidc/v1/token \
  --data "client_id=${CLIENT_ID}" \
  --data "subject_token=${FEDERATED_JWT_TOKEN}" \
  --data 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data 'scope=all-apis'

Ersetzen Sie CLIENT_ID durch den Dienstprinzipal UUID (z. B. 7cb2f8a4-49a7-4147-83db-35cb69e5cede).

Wenn das Token von Ihrem Identitätsanbieter gültig ist und Ihrer Verbundrichtlinie entspricht, erhalten Sie eine standardmäßige JSON-Antwort, die ein Databricks OAuth-Token im feld access_token enthält. Dieses OAuth-Token kann für den Zugriff auf Databricks-APIs verwendet werden. Das resultierende Databricks OAuth-Token hat den gleichen Ablaufanspruch (exp) wie der im subject_token-Parameter bereitgestellte JWT.

Beispielantwort:

{
  "access_token": "eyJraWQ...odi0WFNqQw",
  "scope": "all-apis",
  "token_type": "Bearer",
  "expires_in": 3600
}

Verwenden des OAuth-Tokens zum Aufrufen von Databricks-APIs

Anschließend können Sie das resultierende OAuth-Token "Databricks" als Bearertoken verwenden, um auf Databricks-APIs zuzugreifen. Um beispielsweise die Databricks SCIM Me-API aufzurufen, um Ihren Databricks-Benutzer und Anzeigenamen abzurufen:

TOKEN='<your-databricks-oauth-token>'

curl --header "Authorization: Bearer $TOKEN" \
  --url https://${DATABRICKS_WORKSPACE_HOSTNAME}/api/2.0/preview/scim/v2/Me

Die Antwort sollte ähnlich wie folgt aussehen:

{
  "userName": "username@mycompany.com",
  "displayName": "Firstname Lastname"
}