Konfigurowanie zasad federacji

Federacja tokenów OAuth usługi Databricks umożliwia bezpieczny dostęp do interfejsów API usługi Databricks za pomocą tokenów dostarczanych przez dostawcę tożsamości. Aby włączyć federację tokenów OAuth, należy skonfigurować politykę federacyjną, na poziomie całego konta Databricks lub dla poszczególnych obciążeń.

Na tej stronie opisano sposób tworzenia i konfigurowania zasad federacji tokenu OAuth.

Federacja tożsamości zadaniowej

Federacja tożsamości obciążeń roboczych umożliwia automatycznym obciążeniom działającym poza Azure Databricks na uzyskanie dostępu do interfejsów API Azure Databricks bez potrzeby używania wpisów tajnych Azure Databricks. Administratorzy kont mogą skonfigurować federację tożsamości dla obciążenia roboczego przy użyciu polityki federacji jednostki usługi.

Polityka federacji jednostki usługi jest powiązana z jednostką usługi na koncie Azure Databricks i określa:

  • Dostawca tożsamości (lub wystawca), za pomocą którego podmiot usługi może się uwierzytelniać.
  • Tożsamość robocza (lub podmiot), która może uwierzytelniać się jako główny użytkownik usługi Azure Databricks.

Na przykład, biorąc pod uwagę następującą politykę federacji nazwy głównej usługi dla obciążenia GitHub Actions:

  • Emitenta:https://token.actions.githubusercontent.com
  • Odbiorców:https://github.com/my-github-org
  • Temat:repo:my-github-org/my-repo:environment:prod

Tej treści JWT można użyć do uwierzytelniania w Azure Databricks:

{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://github.com/my-github-org",
  "sub": "repo:my-github-org/my-repo:environment:prod"
}

Note

Przykłady GitHub Actions na tej stronie używają formatu „tylko nazwa” sub. Repozytoria utworzone, przemianowane lub przeniesione 15 lipca 2026 roku lub później używają niezmiennego formatu, który obejmuje numeryczne identyfikatory organizacji i repozytorium, podobnie jak wcześniejsze repozytoria, które się na to zgadzają. Ponieważ Azure Databricks dokładnie dopasowuje podmiot zasad do sub claim, użyj formatu odpowiadającego twojemu repozytorium. Zobacz Włączanie federacji tożsamości obciążenia dla funkcji GitHub Actions.

Konfigurowanie zasad federacyjnych podmiotu głównego usługi

Administratorzy konta mogą skonfigurować zasady federacji jednostki usługi przy użyciu interfejsu wiersza polecenia usługi Databricks lub interfejsu API usługi Databricks. Można utworzyć maksymalnie 20 zasad federacyjnych jednostki usługi dla jednostki usługi na platformie Azure Databricks. Ten limit jest zgodny z innymi standardowymi implementacjami branżowymi i nie może być zwiększany.

Aby skonfigurować zasady federacji jednostki usługi, należy określić następujące elementy:

  • Adres URL wystawcy: Adres URL HTTPS identyfikujący dostawcę tożsamości obciążenia określony w iss oświadczeniu tokena tożsamości obciążenia.

  • Temat: Unikatowy identyfikator obciążenia w środowisku wykonawczym obciążenia. Jeśli nie zostanie określony, wartość domyślna to sub.

  • Odbiorcy: Zamierzony odbiorca tokenu, określony w oświadczeniu aud. Token jest traktowany jako dopasowanie, jeśli jego odbiorcy pasują do przynajmniej jednej grupy odbiorców w polityce. Jeśli nie określono, wartością domyślną jest twój identyfikator konta Azure Databricks.

  • Oświadczenie podmiotu: (opcjonalnie) Określa oświadczenie tokenu, które zawiera tożsamość zadania (nazywaną również podmiotem) tokenu. Jeśli nie jest ustawiona, Azure Databricks domyślnie używa sub. Usługa Databricks zaleca zachowanie domyślnego sub oświadczenia dla federacji tożsamości obciążenia. Wybierz tylko inne oświadczenie, jeśli sub nie jest odpowiednim lub stabilnym identyfikatorem podmiotu, co jest rzadkie. Aby uzyskać szczegółowe informacje, zobacz Przykładowe polityki federacyjne podmiotów usługi.

  • Weryfikacja podpisu tokenu: (opcjonalnie) Klucze publiczne lub ich adres URL w formacie zestawów kluczy sieci Web JSON (JWKS) używane do sprawdzania poprawności podpisów tokenu. Kod JWKS JSON obsługuje maksymalnie 5 kluczy. Jeśli dostawca tożsamości publikuje dodatkowe informacje, zamiast tego użyj identyfikatora URI JWKS.

    Jeśli nie określono, Azure Databricks pobiera klucze z dobrze znanego punktu końcowego wystawcy, co jest zalecanym podejściem. Dostawca tożsamości musi obsługiwać metadane dostawcy OpenID pod <issuer-url>/.well-known/openid-configuration, które zawierają jwks_uri określające lokalizację kluczy publicznych używanych do weryfikacji podpisów tokenów.

Interfejs użytkownika usługi Databricks

  1. Jako administrator konta zaloguj się do konsoli konta Azure Databricks pod adresem https://accounts.azuredatabricks.net.
  2. Kliknij pozycję Zarządzanie użytkownikami.
  3. Przejdź do karty Podmioty usługi.
  4. Wybierz jednostkę usługi, dla której chcesz utworzyć politykę.
  5. Przejdź do karty Poświadczenia i wpisy tajne .
  6. Na karcie Zasady federacji kliknij pozycję Utwórz zasady.
  7. Wybierz dostawcę poświadczeń federacyjnych i skonfiguruj odpowiednie pola.
  8. Kliknij pozycję Create policy (Utwórz zasady).

Databricks CLI (Interfejs wiersza polecenia)

Nie można użyć Databricks CLI w terminalu web obszaru roboczego Azure Databricks do utworzenia polityki federacyjnej.

  1. Zainstaluj lub zaktualizuj najnowszą wersję CLI Databricks.

  2. Jako administrator konta uwierzytelnij się na koncie Azure Databricks przy użyciu interfejsu wiersza polecenia. Określ ACCOUNT_CONSOLE_URL i Azure Databricks ACCOUNT_ID:

    databricks auth login --host ${ACCOUNT_CONSOLE_URL} --account-id ${ACCOUNT_ID}

  3. Pobierz identyfikator liczbowy podmiotu usługi, do którego zostanie zastosowana zasada federacji. (Na przykład 3659993829438643.)

    Jeśli z wyprzedzeniem znasz identyfikator aplikacji jednostki usługi (zazwyczaj wartość identyfikatora GUID, na przykład bc3cfe6c-469e-4130-b425-5384c4aa30bb), możesz określić identyfikator liczbowy jednostki usługi przy użyciu interfejsu wiersza polecenia Databricks.

    databricks account service-principals list --filter 'applicationId eq "<service-principal-application-id>"'

  4. Utwórz politykę federacji głównego użytkownika usługi. Oto przykład tworzenia zasad federacyjnych dla akcji GitHub:

    databricks account service-principal-federation-policy create ${SERVICE_PRINCIPAL_NUMERIC_ID} --json \
'{
  "oidc_policy": {
    "issuer": "https://token.actions.githubusercontent.com",
    "audiences": [
      "https://github.com/my-github-org"
    ],
    "subject": "repo:my-github-org/my-repo:environment:prod"
  }
}'

Interfejs API dla konta Databricks

  1. Pobierz identyfikator liczbowy jednostki usługi (na przykład 3659993829438643) z konsoli konta lub przy użyciu interfejsu API jednostki usługi.

  2. Utwórz politykę federacji głównego użytkownika usługi. Określ ACCOUNT_CONSOLE_URL, Azure Databricks ACCOUNT_ID, SERVICE_PRINCIPAL_NUMERIC_ID i elementu nośnego TOKEN na potrzeby uwierzytelniania:

    curl --request POST \
  --header "Authorization: Bearer $TOKEN" \
  "${ACCOUNT_CONSOLE_URL}/api/2.0/accounts/${ACCOUNT_ID}/servicePrincipals/${SERVICE_PRINCIPAL_NUMERIC_ID}/federationPolicies" \
  --data '{
    "oidc_policy": {
      "issuer": "https://token.actions.githubusercontent.com",
      "audiences": [
        "https://github.com/my-github-org"
      ],
      "subject": "repo:my-github-org/my-repo:environment:prod"
    }
  }'

    Aby uzyskać pełną dokumentację interfejsu API odniesienia, zobacz Account Federation Policy API.

Przykładowe zasady federacji usługowej jednostki Databricks

Poniższa tabela zawiera przykładowe zasady federacji jednostki usługi i zgodną treść JWT.

Aby uzyskać pełne instrukcje dotyczące włączenia federacji tożsamości dla obciążeń dla niektórych z tych powszechnie używanych dostawców tożsamości, zobacz Włączanie federacji tożsamości dla obciążeń w CI/CD.

Tool Zasady federacji Przykład dopasowania tokenu
GitHub Actions Emitenta:https://token.actions.githubusercontent.comAudiencja:https://github.com/<github-org>Temat:repo:<github-org>/<repo>:environment:prod { "iss": "https://token.actions.githubusercontent.com", "aud": "https://github.com/<github-org>", "sub": "repo:<github-org>/<repo>:environment:prod" }
Kubernetes Emitenta:https://kubernetes.default.svcAudiencja:https://kubernetes.default.svcTemat:system:serviceaccount:namespace:serviceaccountnameJWKS JSON:{"keys":[{"kty":"rsa","e":"AQAB","use":"sig","kid":"<key-id>","alg":"RS256","n":"uPUViFv..."}]} { "iss": "https://kubernetes.default.svc", "aud": ["https://kubernetes.default.svc"], "sub": "system:serviceaccount:namespace:serviceaccountname" }
Azure DevOps Emitenta:https://vstoken.dev.azure.com/<org_id>Audiencja:api://AzureADTokenExchangeTemat:sc://my-org/my-project/my-connection { "iss": "https://vstoken.dev.azure.com/<org_id>", "aud": "api://AzureADTokenExchange", "sub": "sc://my-org/my-project/my-connection" }
GitLab Emitenta:https://gitlab.example.comAudiencja:https://gitlab.example.comTemat:project_path:my-group/my-project:... { "iss": "https://gitlab.example.com", "aud": "https://gitlab.example.com", "sub": "project_path:my-group/my-project:..." }
CircleCI Emitenta:https://oidc.circleci.com/org/<org_id>Audiencja:<org_id>Temat:7cc1d11b-46c8-4eb2-9482-4c56a910c7ceOświadczenie podmiotu:oidc.circleci.com/project-id { "iss": "https://oidc.circleci.com/org/<org_id>", "aud": "<org_id>", "oidc.circleci.com/project-id": "7cc1d11b-46c8-4eb2-9482-4c56a910c7ce" }
Federacja tożsamości wychodzącej usługi AWS IAM Wystawca:https://<uuid>.tokens.sts.global.api.aws (adres URL wystawcy specyficzny dla konta) Odbiorca:databricks (lub dowolna uzgodniona wartość przekazana do GetWebIdentityToken) Podmiot:arn:aws:iam::<account>:role/<role-name> { "iss": "https://<uuid>.tokens.sts.global.api.aws", "aud": ["databricks"], "sub": "arn:aws:iam::123456789012:role/my-workload-role" }

Note

W przypadku federacji tożsamości wychodzącej AWS IAM deklaracja sub w tokenie to ARN roli IAM obciążenia wywołującego (na przykład roli wykonawczej AWS Lambda, roli zadania ECS lub roli instancji EC2).

Najlepsze praktyki dotyczące zasad federacyjnych podmiotu usługi

Każda jednostka usługi obsługuje maksymalnie 20 zasad federacyjnych. Ten limit jest zgodny z innymi standardowymi implementacjami branżowymi i nie może być zwiększany. Postępuj zgodnie z tymi wytycznymi, aby uniknąć osiągnięcia tego limitu.

Mapuj jedną tożsamość zewnętrzną na jednostkę usługi

Utwórz dedykowaną jednostkę usługi dla każdej odrębnej tożsamości obciążenia zewnętrznego. Wiele polityk federacyjnych na jednym głównym obiekcie usługi jest właściwych tylko wtedy, gdy ta sama tożsamość logiczna uwierzytelnia się za pośrednictwem różnych dostawców tożsamości. Na przykład obciążenie, które działa zarówno w GitHub Actions, jak i Azure DevOps, wymaga dwóch polityk, jednej na dostawcę, na tym samym użytkowniku usługi.

Nie używaj wielu zasad do mapowania różnych obciążeń (takich jak oddzielne zasobniki Kubernetes na region) na jedną jednostkę usługi. Zamiast tego utwórz oddzielny profil usługi dla każdego obciążenia. Pozwala to zachować przypisanie dziennika inspekcji i umożliwia odwoływanie dostępu dla jednego obciążenia bez wpływu na inne.

Usprawnij uprawnienia za pomocą grup

Jeśli wiele jednostek usługi wymaga tych samych uprawnień, dodaj je jako członków grupy Azure Databricks i przypisz uprawnienia do grupy. Zobacz Najlepsze rozwiązania dotyczące tożsamości.

Użyj właściwości subject_claim dla alternatywnych oświadczeń

Domyślnie Azure Databricks używa oświadczenia sub z tokenu tożsamości do identyfikacji obciążenia. Jeśli dostawca tożsamości nie używa sub jako stabilnego identyfikatora obciążenia, dokonaj ustawienia właściwości subject_claim na nazwę atrybutu używaną przez dostawcę. Aby zapoznać się z przykładem, zobacz konfigurację CircleCI w przykładowych zasadach federacji jednostki usługi Databricks. .

Federacja tokenów dla całego konta

Administratorzy kont mogą skonfigurować federację tokenów OAuth na koncie Azure Databricks przy użyciu zasad federacji kont. Zasady federacji kont umożliwiają wszystkim użytkownikom i jednostkom usługi na koncie Azure Databricks uzyskiwanie dostępu do interfejsów API usługi Databricks przy użyciu tokenów od dostawcy tożsamości. Zasady federacji kont określają:

  • Dostawca tożsamości lub wystawca, od którego Azure Databricks będzie akceptować tokeny.
  • Kryteria mapowania tokenu do odpowiadającego użytkownika lub jednostki usługi w Azure Databricks.

Na przykład, mając politykę federacji z następującymi polami:

  • Emitenta:https://idp.mycompany.com/oidc
  • Odbiorców:databricks
  • Oświadczenie podmiotu:sub

Ta treść JWT służy do uwierzytelniania w Azure Databricks jako username@mycompany.com:

{
  "iss": "https://idp.mycompany.com/oidc",
  "aud": "databricks",
  "sub": "username@mycompany.com"
}

Konfigurowanie zasad federacji kont

Administratorzy kont mogą skonfigurować zasady federacji kont przy użyciu interfejsu użytkownika Azure Databricks, interfejsu wiersza polecenia usługi Databricks lub interfejsu API REST usługi <>Databricks. W ramach konta Azure Databricks można określić maksymalnie 20 zasad federacji kont.

Aby skonfigurować zasady federacji kont, należy określić następujące elementy:

  • Adres URL wystawcy: Adres URL PROTOKOŁU HTTPS identyfikujący dostawcę tożsamości określony w oświadczeniu iss tokenów.

  • Odbiorcy: Zamierzony odbiorca tokenu, określony w oświadczeniu aud. Token jest traktowany jako dopasowanie, jeśli jego odbiorcy pasują do przynajmniej jednej grupy odbiorców w polityce. Jeśli nie określono, wartością domyślną jest twój identyfikator konta Azure Databricks.

  • Roszczenie podmiotu: Oświadczenie tokenu zawierające nazwę użytkownika Azure Databricks, dla którego token został wystawiony. Jeśli nie zostanie określony, wartość domyślna to sub.

  • Weryfikacja podpisu tokenu: (opcjonalnie) Klucze publiczne lub ich adres URL w formacie zestawów kluczy sieci Web JSON (JWKS) używane do sprawdzania poprawności podpisów tokenu. Kod JWKS JSON obsługuje maksymalnie 5 kluczy. Jeśli dostawca tożsamości publikuje dodatkowe informacje, zamiast tego użyj identyfikatora URI JWKS.

    Jeśli nie określono, Azure Databricks pobiera klucze z dobrze znanego punktu końcowego wystawcy, co jest zalecanym podejściem. Dostawca tożsamości musi obsługiwać metadane dostawcy OpenID pod <issuer-url>/.well-known/openid-configuration, które zawierają jwks_uri określające lokalizację kluczy publicznych używanych do weryfikacji podpisów tokenów.

Important

W przypadku federacji dla całego konta zarejestruj tylko dostawcę tożsamości, który jest w pełni zarządzany i zaufany przez organizację, takie jak własny dostawca tożsamości firmy. Nie należy konfigurować federacji całego konta z zewnętrznymi dostawcami tożsamości, nad którymi nie masz kontroli, takimi jak dostawcy zarządzani przez klientów lub partnerów.

Interfejs użytkownika usługi Databricks

  1. Jako administrator konta zaloguj się do konsoli konta Azure Databricks pod adresem https://accounts.azuredatabricks.net.
  2. Kliknij Bezpieczeństwo i przejdź do zakładki Konfiguracja dostawcy tożsamości .
  3. W obszarze Zasady federacji kliknij pozycję Utwórz zasady.
  4. Wprowadź adres URL wystawcy, odbiorców, oświadczenie podmiotu i opcjonalną weryfikację podpisu tokenu.
  5. Kliknij pozycję Create policy (Utwórz zasady).

Databricks CLI (Interfejs wiersza polecenia)

Nie można użyć Databricks CLI w terminalu web obszaru roboczego Azure Databricks do utworzenia polityki federacyjnej.

  1. Zainstaluj lub zaktualizuj do najnowszej wersji interfejsu wiersza polecenia usługi Databricks.

  2. Jako administrator konta uwierzytelnij się na koncie Azure Databricks przy użyciu interfejsu wiersza polecenia. Określ ACCOUNT_CONSOLE_URL i Azure Databricks ACCOUNT_ID.

    databricks auth login --host ${ACCOUNT_CONSOLE_URL} --account-id ${ACCOUNT_ID}

  3. Utwórz zasady federacji kont. Przykład:

    databricks account federation-policy create --json \
'{
  "oidc_policy": {
    "issuer": "https://idp.mycompany.com/oidc",
    "audiences": [
      "databricks"
    ],
    "subject_claim": "sub"
  }
}'

Interfejs API dla konta Databricks

Następujące wywołanie interfejsu API REST tworzy zasady federacji kont. Określ ACCOUNT_CONSOLE_URL, Azure Databricks ACCOUNT_ID i elementu nośnego TOKEN na potrzeby uwierzytelniania.

curl --request POST \
  --header "Authorization: Bearer $TOKEN" \
  "${ACCOUNT_CONSOLE_URL}/api/2.0/accounts/${ACCOUNT_ID}/federationPolicies" \
  --data '{
    "oidc_policy": {
      "issuer": "https://idp.mycompany.com/oidc",
      "audiences": [
        "databricks"
      ],
      "subject_claim": "sub"
    }
  }'

Aby uzyskać pełną dokumentację interfejsu API odniesienia, zobacz Account Federation Policy API.

Przykładowe zasady federacji kont

Poniższa tabela zawiera przykładowe zasady federacji kont i zgodną treść JWT.

Zasady federacji Przykład dopasowania tokenu
Emitenta:https://idp.mycompany.com/oidcAudiencja:2ff814a6-3304-4ab8-85cb-cd0e6f879c1d { "iss": "https://idp.mycompany.com/oidc", "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "sub": "username@mycompany.com" }
Wystawca:https://idp.mycompany.com/oidcOdbiorca:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dRoszczenie podmiotu:preferred_username { "iss": "https://idp.mycompany.com/oidc", "aud": ["2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "other-audience"], "preferred_username": "username@mycompany.com", "sub": "some-other-ignored-value" }
Wydawca:https://idp.mycompany.com/oidcOdbiorcy:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dJWKS JSON:{"keys":[{"kty":"RSA","e":"AQAB","use":"sig","kid":"<key-id>","alg":"RS256","n":"uPUViFv..."}]} { "iss": "https://idp.mycompany.com/oidc", "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "sub": "username@mycompany.com" } (podpis zweryfikowany przy użyciu klucza publicznego w zasadach)
Wystawca:https://idp.mycompany.com/oidcOdbiorca:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dIdentyfikator URI JWKS:https://idp.mycompany.com/jwks.json { "iss": "https://idp.mycompany.com/oidc", "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "sub": "username@mycompany.com" } (podpis zweryfikowany przy użyciu klucza publicznego pobranego z jwks_uri)

Dalsze kroki

Po skonfigurowaniu zasad federacji dla konta:

  • Skonfiguruj dostawcę tożsamości (IdP), aby wygenerować tokeny, które użytkownicy mogą wymieniać za pomocą Azure Databricks. Aby uzyskać szczegółowe informacje o konfiguracji, zapoznaj się z dokumentacją dostawcy tożsamości. Aby uzyskać instrukcje dotyczące włączania federacji tożsamości dla obciążeń z typowymi IdP-ami, zobacz Włączanie federacji tożsamości dla obciążeń w CI/CD.
  • Użyj tokenu JWT od dostawcy tożsamości, aby uzyskać dostęp do interfejsu API Azure Databricks, najpierw wymieniając go na token OAuth Azure Databricks. Dołącz token OAuth Azure Databricks do nagłówka Bearer: wywołania interfejsu API, aby ukończyć żądanie. Zestaw JWT musi być prawidłowy i podpisany przy użyciu algorytmów RS256 lub ES256. Aby uzyskać szczegółowe informacje o implementacji, zobacz Uwierzytelnianie przy użyciu tokenu dostawcy tożsamości.
  • Ostatnia aktualizacja o