Configurare una politica federativa

La federazione dei token OAuth di Databricks consente di accedere in modo sicuro alle API di Databricks usando i token del provider di identità (IdP). Per abilitare la federazione dei token OAuth, è necessario configurare un criterio federativo, sia a livello di account databricks che per i carichi di lavoro.

Questa pagina descrive come creare e configurare un criterio di federazione dei token OAuth.

Federazione delle identità dei carichi di lavoro

La federazione delle identità del workload consente ai carichi di lavoro automatizzati in esecuzione all'esterno di Azure Databricks di accedere alle API di Azure Databricks senza la necessità dei segreti di Azure Databricks. Gli amministratori dell'account possono configurare la federazione dell'identità dei carichi di lavoro utilizzando una policy di federazione del service principal.

Una politica di federazione dell'entità servizio è associata a un'entità servizio nell'account Azure Databricks e specifica:

• Provider di identità (o autorità emittente) da cui il principal del servizio possa autenticarsi.
• Identità del carico di lavoro (o soggetto) autorizzata ad autenticarsi come entità servizio di Azure Databricks.

Ad esempio, dati i seguenti criteri di federazione per un carico di lavoro di GitHub Actions del principale del servizio:

• Emittente:https://token.actions.githubusercontent.com
• Pubblico:https://github.com/my-github-org
• Oggetto:repo:my-github-org/my-repo:environment:prod

È possibile usare questo corpo JWT per eseguire l'autenticazione per Azure Databricks:

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

Configurare un criterio di federazione dell'entità servizio

Gli amministratori degli account possono configurare una politica di federazione dell'entità del servizio usando l'interfaccia della riga di comando di Databricks o l'API di Databricks. È possibile creare un massimo di 20 criteri di federazione per un principal del servizio Azure Databricks.

Per configurare un criterio di federazione dell'entità servizio, è necessario specificare quanto segue:

• URL dell'autorità di emissione: Un URL HTTPS che identifica il provider dell'identità del carico di lavoro, specificato nella dichiarazione iss dei token di identità del carico di lavoro.

• Oggetto: Identificatore univoco per il carico di lavoro nell'ambiente di runtime. Se non specificato, il valore predefinito è sub.

• Destinatari: Il destinatario previsto del token, specificato nell'attestazione aud. Il token viene considerato valido se i destinatari corrispondono ad almeno uno dei destinatari nella politica. Se non specificato, il valore predefinito è l'ID account Azure Databricks.

• Dichiarazione del soggetto: (facoltativo) specifica la dichiarazione del token che contiene l'identità del carico di lavoro (detta anche soggetto) del token. Se non è impostato, Azure Databricks usa sub per impostazione predefinita. Databricks consiglia di mantenere l'attestazione predefinita sub per la federazione dell'identità del workload. Scegliere un'attestazione diversa solo se sub non è un identificatore di soggetto adatto o stabile, che è raro. Per informazioni dettagliate, vedere Esempi di criteri di federazione dell'entità servizio.

• Convalida della firma del token: (facoltativo) Le chiavi pubbliche, o il relativo URL, in formato JWKS (JSON Web Key Sets) usato per convalidare le firme del token. JWKS JSON supporta fino a 5 chiavi. Se il provider di identità pubblica ulteriori informazioni, utilizzare invece un URI JWKS.

  Se non specificato, Azure Databricks recupera le chiavi dall'endpoint noto dell'autorità emittente, ovvero l'approccio consigliato. Il provider di identità deve fornire i metadati del provider OpenID in <issuer-url>/.well-known/openid-configuration che specificano il percorso delle chiavi pubbliche usate per verificare le firme dei token.

Interfaccia utente di Databricks

1. Come amministratore dell'account, accedere alla console dell'account Azure Databricks all'indirizzo https://accounts.azuredatabricks.net.
2. Fare clic su Gestione utenti.
3. Passare alla scheda Entità servizio.
4. Selezionare il principale del servizio per cui creare i criteri.
5. Passare alla scheda Credenziali e segreti .
6. Nella scheda Criteri di federazione fare clic su Crea criterio.
7. Selezionare un provider di credenziali federato e configurare i campi corrispondenti.
8. Fare clic su Crea criterio.

Interfaccia a riga di comando di Databricks

Non è possibile usare l'interfaccia della riga di comando di Databricks nell'area di lavoro Azure Databricks web terminal per creare un criterio federativo.

1. Installare o aggiornare alla versione più recente dell'interfaccia della riga di comando di Databricks.

2. In qualità di amministratore dell'account, autenticati al tuo account Azure Databricks usando la riga di comando. Specificare il ACCOUNT_CONSOLE_URL e il tuo Azure Databricks ACCOUNT_ID:

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

3. Ottenere l'ID numerico del principal del servizio a cui verranno applicati i criteri di federazione. Ad esempio, 3659993829438643.)

   Se conosci in anticipo l'ID applicazione dell'entità servizio (di solito un valore GUID, come bc3cfe6c-469e-4130-b425-5384c4aa30bb), puoi determinare l'ID numerico dell'entità servizio utilizzando la CLI di Databricks.

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

4. Creare i criteri di federazione dell'entità servizio. Di seguito è riportato un esempio di creazione di criteri di federazione per un'azione 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"
     }
   }'
   

API dell'account Databricks

1. Ottieni l'ID numerico dell'Entità Servizio (ad esempio, ) dalla console dell'account o usando l'API Entità Servizio .

2. Creare i criteri di federazione dell'entità servizio. Specifica il ACCOUNT_CONSOLE_URL, il tuo Azure Databricks ACCOUNT_ID, il SERVICE_PRINCIPAL_NUMERIC_ID e un token di autorizzazione TOKEN per l'autenticazione.

   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"
       }
     }'
   

   Per la documentazione di riferimento dell'API completa, vedere Account Federation Policy API.

Esempi di criteri di federazione di principale di servizio di Databricks

La tabella seguente fornisce criteri di federazione di esempio per i principali del servizio e il corpo JWT corrispondente.

Per i passaggi di configurazione completi per abilitare la federazione delle identità del carico di lavoro per alcuni di questi provider di identità comuni, vedere Abilitare la federazione delle identità del carico di lavoro in CI/CD.

Procedure consigliate per i criteri di federazione dell'entità servizio

Ogni principale del servizio supporta fino a un massimo di 20 criteri di federazione. Seguire queste linee guida per evitare di raggiungere tale limite.

Eseguire il mapping di un'identità esterna per ogni entità servizio

Creare un'entità servizio dedicata per ogni identità distinta del carico di lavoro esterno. Più criteri di federazione su un singolo principale del servizio sono appropriati solo quando la stessa identità logica viene autenticata attraverso diversi provider di identità. Ad esempio, un carico di lavoro eseguito sia in GitHub Actions che in Azure DevOps richiede due criteri, uno per provider, nella stessa entità servizio.

Non usare più criteri per eseguire il mapping di carichi di lavoro diversi, ad esempio pod Kubernetes separati per area, a un unico principale del servizio. Creare invece un'entità servizio separata per ogni carico di lavoro. In questo modo si mantiene l'attribuzione del log di controllo e si revoca l'accesso per un carico di lavoro senza influire sugli altri.

Semplificare le autorizzazioni con i gruppi

Quando più entità servizio necessitano delle stesse autorizzazioni, aggiungerle come membri di un gruppo di Azure Databricks e assegnare autorizzazioni al gruppo. Vedere Procedure consigliate per l'identità.

Utilizzare la proprietà subject_claim per rivendicazioni alternative

Per impostazione predefinita, Azure Databricks usa l'attestazione sub dal token di identità per identificare il carico di lavoro. Se il provider di identità non usa il sub claim come identificatore stabile del carico di lavoro, impostare la proprietà subject_claim sul nome del claim che il provider utilizza. Per un esempio, vedere la configurazione CircleCI in Esempio di criteri di federazione del Service Principal di Databricks. .

Federazione di token a livello di account

Gli amministratori dell'account possono configurare la federazione dei token OAuth nell'account Azure Databricks usando un criterio di federazione dell'account. I criteri di federazione degli account consentono a tutti gli utenti e alle entità servizio nell'account Azure Databricks di accedere alle API di Databricks usando i token del provider di identità. Un criterio di federazione dell'account specifica:

• Provider di identità o autorità emittente da cui Azure Databricks accetterà i token.
• I criteri per la mappatura di un token all'utente di Azure Databricks o al principale del servizio corrispondente.

Ad esempio, dato un criterio di federazione con i campi seguenti:

• Emittente:https://idp.mycompany.com/oidc
• Pubblico:databricks
• Dichiarazione del soggetto:sub

Usare questo corpo JWT per eseguire l'autenticazione per Azure Databricks come username@mycompany.com:

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

Configurare un criterio di federazione dell'account

Gli amministratori account possono configurare criteri di federazione degli account usando l'interfaccia utente Azure Databricks, l'interfaccia della riga di comando Databricks o l'API REST Databricks. È possibile specificare un massimo di 20 criteri di federazione dell'account nell'account Azure Databricks.

Per configurare un criterio di federazione dell'account, è necessario specificare quanto segue:

• URL dell'emittente: Un URL HTTPS che identifica il provider di identità, specificato nella dichiarazione iss dei token.

• Destinatari: Il destinatario previsto del token, specificato nell'attestazione aud. Il token viene considerato valido se i destinatari corrispondono ad almeno uno dei destinatari nella politica. Se non specificato, il valore predefinito è l'ID account Azure Databricks.

• Rivendicazione del soggetto: La rivendicazione del token che contiene il nome utente Azure Databricks dell'utente per cui è stato rilasciato il token. Se non specificato, il valore predefinito è sub.

• Convalida della firma del token: (facoltativo) Le chiavi pubbliche, o il relativo URL, in formato JWKS (JSON Web Key Sets) usato per convalidare le firme del token. JWKS JSON supporta fino a 5 chiavi. Se il provider di identità pubblica ulteriori informazioni, utilizzare invece un URI JWKS.

  Se non specificato, Azure Databricks recupera le chiavi dall'endpoint noto dell'autorità emittente, ovvero l'approccio consigliato. Il provider di identità deve fornire i metadati del provider OpenID in <issuer-url>/.well-known/openid-configuration che specificano il percorso delle chiavi pubbliche usate per verificare le firme dei token.

Interfaccia utente di Databricks

1. Come amministratore dell'account, accedere alla console dell'account Azure Databricks all'indirizzo https://accounts.azuredatabricks.net.
2. Fare clic su Sicurezza e passare alla scheda Autenticazione .
3. In Criteri di federazione fare clic su Crea criterio.
4. Immettere l'URL dell'emittente, le audience, il claim dell'oggetto e la convalida facoltativa della firma del token.
5. Fare clic su Crea criterio.

Interfaccia a riga di comando di Databricks

Non è possibile usare l'interfaccia della riga di comando di Databricks nell'area di lavoro Azure Databricks web terminal per creare un criterio federativo.

1. Installare o aggiornare alla versione più recente dell'interfaccia della riga di comando di Databricks.

2. In qualità di amministratore dell'account, autenticati al tuo account Azure Databricks usando la riga di comando. Specificare il ACCOUNT_CONSOLE_URL e il Azure Databricks ACCOUNT_ID.

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

3. Creare la politica di federazione dell'account. Per esempio:

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

API dell'account Databricks

La chiamata API REST seguente crea un criterio di federazione dell'account. Specificare il ACCOUNT_CONSOLE_URL, il Azure Databricks ACCOUNT_ID e un bearer TOKEN per l'autenticazione.

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"
    }
  }'

Per la documentazione di riferimento dell'API completa, vedere Account Federation Policy API.

Criteri di federazione degli account di esempio

La tabella seguente fornisce i criteri di federazione dell'account di esempio e il corpo JWT corrispondente.

Passaggi successivi

Dopo aver configurato un criterio federativo per l'account:

• Configurare il provider di identità (IdP) per generare token che gli utenti possono scambiare con Azure Databricks. Per i dettagli sulla configurazione, consultare la documentazione del tuo IdP. Per istruzioni su come abilitare la federazione delle identità di carico di lavoro con gli IdP comuni, vedere Abilitare la federazione delle identità di carico di lavoro in CI/CD.
• Utilizzare un token JWT dal tuo IdP per accedere all'API di Azure Databricks scambiandolo con un token OAuth di Azure Databricks. Includere il token OAuth Azure Databricks nell'intestazione Bearer: della chiamata API per completare la richiesta. Il token JWT deve essere valido e firmato usando gli algoritmi RS256 o ES256. Per informazioni dettagliate sull'implementazione, vedere Eseguire l'autenticazione con un token del provider di identità.