Proteggere le credenziali con i servizi collegati tramite mssparkutils

L'accesso ai dati da origini esterne è uno schema comune. A meno che l'origine dati esterna non consenta l'accesso anonimo, è probabile che sia necessario proteggere la connessione con una credenziale, un segreto o una stringa di connessione.

Per impostazione predefinita, Azure Synapse Analytics usa il passthrough di Microsoft Entra per l'autenticazione tra risorse. Se è necessario connettersi a una risorsa usando altre credenziali, usare direttamente mssparkutils. Il pacchetto mssparkutils semplifica il processo di recupero di token SAS, token di Microsoft Entra, stringhe di connessione e segreti archiviati in un servizio collegato o in Azure Key Vault.

Il passthrough di Microsoft Entra usa le autorizzazioni assegnate all'utente come utente in Microsoft Entra ID, anziché le autorizzazioni assegnate a Synapse o a un'entità servizio separata. Ad esempio, se si desidera usare il passthrough Microsoft Entra per accedere a un BLOB in un account di archiviazione, è necessario andare a tale account di archiviazione e assegnare il ruolo di collaboratore BLOB a sé stessi.

Quando si recuperano i segreti da Azure Key Vault, è consigliabile creare un servizio collegato alla propria istanza di Azure Key Vault. Assicurarsi che l'identità del servizio gestita dell'area di lavoro di Synapse abbia privilegi Secret Get per Azure Key Vault. Synapse eseguirà l'autenticazione in Azure Key Vault usando l'identità del servizio gestita dell'area di lavoro di Synapse. Se ci si connette direttamente ad Azure Key Vault senza un servizio collegato, si esegue l'autenticazione con le credenziali utente di Microsoft Entra.

Per altre informazioni, vedere Servizi collegati.

Utilizzo

Guida di mssparkutils per token e segreti

Questa funzione visualizza la documentazione della Guida per la gestione dei segreti e dei token in Synapse.

mssparkutils.credentials.help()

mssparkutils.credentials.help()

Console.WriteLine(TokenLibrary.help());

Ottenere il risultato:

 getToken(audience: String, name: String): returns AAD token for a given audience, name (optional)
 isValidToken(token: String): returns true if token hasn't expired
 getConnectionStringOrCreds(linkedService: String): returns connection string or credentials for the linked service
 getFullConnectionString(linkedService: String): returns full connection string with credentials for the linked service
 getPropertiesAll(linkedService: String): returns all the properties of the linked service
 getSecret(akvName: String, secret: String, linkedService: String): returns AKV secret for a given AKV linked service, akvName, secret key using workspace MSI
 getSecret(akvName: String, secret: String): returns AKV secret for a given akvName, secret key using user credentials
 getSecretWithLS(linkedService: String, secret: String): returns AKV secret for a given linked service, secret key
 putSecret(akvName: String, secretName: String, secretValue: String): puts AKV secret for a given akvName, secretName
 putSecret(akvName: String, secretName: String, secretValue: String, linkedService: String): puts AKV secret for a given akvName, secretName
 putSecretWithLS(linkedService: String, secretName: String, secretValue: String): puts AKV secret for a given linked service, secretName

Accedere ad Azure Data Lake Storage Gen2

Archiviazione primaria di ADLS Gen2

Per l'accesso ai file dall’Azure Data Lake Storage primario per impostazione predefinita viene usato il passthrough di Microsoft Entra per l'autenticazione e non è richiesto l'uso esplicito di mssparkutils. L'identità usata nell'autenticazione passthrough varia in base a alcuni fattori. Per impostazione predefinita, i notebook interattivi vengono eseguiti usando l'identità dell'utente, ma possono essere modificati nell'identità del servizio gestito (MSI) dell'area di lavoro. I processi batch e le esecuzioni non interattive del notebook usano la MSI dell'area di lavoro.

val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")
display(df.limit(10))

df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')
display(df.limit(10))

Archiviazione di ADLS Gen2 con servizi collegati

Azure Synapse Analytics offre un'esperienza integrata di servizi collegati per la connessione ad Azure Data Lake Storage Gen2. I servizi collegati possono essere configurati per eseguire l'autenticazione tramite chiave dell'account, entità servizio, identità gestita o credenziali.

Se il metodo di autenticazione del servizio collegato è impostato su Chiave dell'account, l'autenticazione viene eseguita con la chiave dell'account di archiviazione specificata, verrà chiesta una chiave di firma di accesso condiviso che verrà automaticamente applicata alla richiesta di archiviazione tramite LinkedServiceBasedSASProvider.

Synapse consente agli utenti di impostare il servizio collegato per un account di archiviazione specifico. In questo modo è possibile leggere/scrivere dati da più account di archiviazione in un'unica applicazione/query Spark. Dopo aver impostato spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName per ogni account di archiviazione che verrà usato, Synapse individua il servizio collegato da usare per una particolare operazione di lettura/scrittura. Tuttavia, se il processo Spark gestisce solo un singolo account di archiviazione, è possibile omettere il nome dell'account di archiviazione e usare spark.storage.synapse.linkedServiceName.

val sc = spark.sparkContext
val source_full_storage_account_name = "teststorage.dfs.core.windows.net"
spark.conf.set(s"spark.storage.synapse.$source_full_storage_account_name.linkedServiceName", "<LINKED SERVICE NAME>")
sc.hadoopConfiguration.set(s"fs.azure.account.auth.type.$source_full_storage_account_name", "SAS")
sc.hadoopConfiguration.set(s"fs.azure.sas.token.provider.type.$source_full_storage_account_name", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedSASProvider")

val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")

display(df.limit(10))

%%pyspark
# Set the required configs
source_full_storage_account_name = "teststorage.dfs.core.windows.net"
spark.conf.set(f"spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName", "<lINKED SERVICE NAME>")
sc._jsc.hadoopConfiguration().set(f"fs.azure.account.auth.type.{source_full_storage_account_name}", "SAS")
sc._jsc.hadoopConfiguration().set(f"fs.azure.sas.token.provider.type.{source_full_storage_account_name}", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedSASProvider")

# Python code
df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<DIRECTORY PATH>')

df.show()

Se il metodo di autenticazione del servizio collegato è impostato su Identità gestita o su Entità servizio, viene usato il token dell'identità gestita o dell'entità servizio con il provider LinkedServiceBasedTokenProvider.

val sc = spark.sparkContext
val source_full_storage_account_name = "teststorage.dfs.core.windows.net"
spark.conf.set(s"spark.storage.synapse.$source_full_storage_account_name.linkedServiceName", "<LINKED SERVICE NAME>")
sc.hadoopConfiguration.set(s"fs.azure.account.oauth.provider.type.$source_full_storage_account_name", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider") 
val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")

display(df.limit(10))

%%pyspark
# Python code
source_full_storage_account_name = "teststorage.dfs.core.windows.net"
spark.conf.set(f"spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName", "<LINKED SERVICE NAME>")
sc._jsc.hadoopConfiguration().set(f"fs.azure.account.oauth.provider.type.{source_full_storage_account_name}", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider")

df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<DIRECTORY PATH>')

df.show()

Impostare le impostazioni di autenticazione tramite la configurazione di Spark

È anche possibile specificare le impostazioni di autenticazione tramite configurazioni Spark, anziché eseguire istruzioni Spark. Tutte le configurazioni spark devono essere precedute da un prefisso spark. e tutte le configurazioni hadoop devono essere precedute da spark.hadoop..

Archiviazione di ADLS Gen2 senza servizi collegati

Connettersi direttamente all'archiviazione di ADLS Gen2 usando una chiave SAS. Usare ConfBasedSASProvider e specificare la chiave SAS per l'spark.storage.synapse.sasimpostazione di configurazione. I token SAS possono essere impostati a livello di contenitore, a livello di account o globale. Non è consigliabile impostare le chiavi SAS a livello globale, perché il processo non sarà in grado di leggere/scrivere da più account di archiviazione.

Configurazione SAS per ogni contenitore di archiviazione

%%spark
sc.hadoopConfiguration.set("fs.azure.account.auth.type.<ACCOUNT>.dfs.core.windows.net", "SAS")
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.<CONTAINER>.<ACCOUNT>.dfs.core.windows.net.sas", "<SAS KEY>")

val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")

display(df.limit(10))

%%pyspark

sc._jsc.hadoopConfiguration().set("fs.azure.account.auth.type.<ACCOUNT>.dfs.core.windows.net", "SAS")
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.<CONTAINER>.<ACCOUNT>.dfs.core.windows.net.sas", "<SAS KEY>")

df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')

display(df.limit(10))

Configurazione SAS per account di archiviazione

%%spark
sc.hadoopConfiguration.set("fs.azure.account.auth.type.<ACCOUNT>.dfs.core.windows.net", "SAS")
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.<ACCOUNT>.dfs.core.windows.net.sas", "<SAS KEY>")

val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")

display(df.limit(10))

%%pyspark

sc._jsc.hadoopConfiguration().set("fs.azure.account.auth.type.<ACCOUNT>.dfs.core.windows.net", "SAS")
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.<ACCOUNT>.dfs.core.windows.net.sas", "<SAS KEY>")

df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')

display(df.limit(10))

Configurazione SAS di tutti gli account di archiviazione

%%spark
sc.hadoopConfiguration.set("fs.azure.account.auth.type", "SAS")
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.sas", "<SAS KEY>")

val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")

display(df.limit(10))

%%pyspark

sc._jsc.hadoopConfiguration().set("fs.azure.account.auth.type", "SAS")
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.sas", "<SAS KEY>")

df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')

display(df.limit(10))

Usare MSAL per acquisire i token (usando le credenziali dell'app personalizzate)

Quando il driver di archiviazione ABFS è configurato per l'uso diretto di MSAL per le autenticazioni, il provider non memorizza nella cache i token. Ciò può causare problemi di affidabilità. È consigliabile usare il ClientCredsTokenProvider fa parte di Synapse Spark.

%%spark
val source_full_storage_account_name = "teststorage.dfs.core.windows.net"
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id.$source_full_storage_account_name", "<Entra AppId>")
spark.conf.set("fs.azure.account.oauth2.client.secret.$source_full_storage_account_name", "<Entra app secret>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint.$source_full_storage_account_name", "https://login.microsoftonline.com/<tenantid>")

val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")

display(df.limit(10))

%%pyspark
source_full_storage_account_name = "teststorage.dfs.core.windows.net"
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ClientCredsTokenProvider")
spark.conf.set(f"fs.azure.account.oauth2.client.id.{source_full_storage_account_name}.linkedServiceName", "<Entra AppId>")
spark.conf.set(f"fs.azure.account.oauth2.client.secret.{source_full_storage_account_name}.linkedServiceName", "<Entra app secret>")
spark.conf.set(f"fs.azure.account.oauth2.client.endpoint.{source_full_storage_account_name}.linkedServiceName", "https://login.microsoftonline.com/<tenantid>")

df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')
display(df.limit(10))

Archiviazione di ADLS Gen2 con token di firma di accesso condiviso (da Azure Key Vault)

Connettersi all'archiviazione di ADLS Gen2 usando un token di firma di accesso condiviso archiviato in un segreto di Azure Key Vault.

%%spark
sc.hadoopConfiguration.set("fs.azure.account.auth.type", "SAS")
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.AkvBasedSASProvider")
spark.conf.set("spark.storage.synapse.akv", "<AZURE KEY VAULT NAME>")
spark.conf.set("spark.storage.akv.secret", "<SECRET KEY>")

val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")

display(df.limit(10))

%%pyspark
sc._jsc.hadoopConfiguration().set("fs.azure.account.auth.type", "SAS")
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.AkvBasedSASProvider")
spark.conf.set("spark.storage.synapse.akv", "<AZURE KEY VAULT NAME>")
spark.conf.set("spark.storage.akv.secret", "<SECRET KEY>")

df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')

display(df.limit(10))

TokenLibrary per altri servizi collegati

Per connettersi ad altri servizi, è possibile effettuare una chiamata diretta a TokenLibrary.

getConnectionString()

Per recuperare la stringa di connessione, usare la funzione getConnectionString e passare il nome del servizio collegato.

%%spark
// retrieve connectionstring from mssparkutils

mssparkutils.credentials.getFullConnectionString("<LINKED SERVICE NAME>")

%%pyspark
# retrieve connectionstring from mssparkutils

mssparkutils.credentials.getFullConnectionString("<LINKED SERVICE NAME>")

%%csharp
// retrieve connectionstring from TokenLibrary

using Microsoft.Spark.Extensions.Azure.Synapse.Analytics.Utils;

string connectionString = TokenLibrary.GetConnectionString(<LINKED SERVICE NAME>);
Console.WriteLine(connectionString);

getPropertiesAll()

GetPropertiesAll è una funzione helper disponibile in Scala e Python per ottenere tutte le proprietà di un servizio collegato

%%pyspark
import json
# retrieve connectionstring from mssparkutils

json.loads(mssparkutils.credentials.getPropertiesAll("<LINKED SERVICE NAME>"))

L'output sarà simile al seguente

{
    'AuthType': 'Key',
    'AuthKey': '[REDACTED]',
    'Id': None,
    'Type': 'AzureBlobStorage',
    'Endpoint': 'https://storageaccount.blob.core.windows.net/',
    'Database': None
}

GetSecret()

Per recuperare un segreto da Azure Key Vault, è consigliabile creare un servizio collegato ad Azure Key Vault all'interno dell'area di lavoro di Synapse. All'identità del servizio gestita dell'area di lavoro di Synapse sarà necessario concedere l'autorizzazione GET Secrets per Azure Key Vault. Il servizio collegato userà l'identità del servizio gestita per connettersi al servizio Azure Key Vault e recuperare il segreto. Altrimenti, se ci si connette direttamente ad Azure Key Vault, verranno usate le credenziali utente di Microsoft Entra. In questo caso, all'utente sarà necessario concedere le autorizzazioni Get Secret per Azure Key Vault.

Nei cloud per enti pubblici specificare il nome di dominio completo dell'insieme di credenziali delle chiavi.

mssparkutils.credentials.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>" [, <LINKED SERVICE NAME>])

Per recuperare un segreto da Azure Key Vault, usare la funzione mssparkutils.credentials.getSecret().

mssparkutils.credentials.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>", "<LINKED SERVICE NAME>")

mssparkutils.credentials.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>", "<LINKED SERVICE NAME>")

using Microsoft.Spark.Extensions.Azure.Synapse.Analytics.Utils;

string connectionString = TokenLibrary.GetSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>", "<LINKED SERVICE NAME>");
Console.WriteLine(connectionString);

Connessioni al servizio collegato supportate dal runtime di Spark

Anche se Azure Synapse Analytics supporta varie connessioni al servizio collegato (da pipeline e altri prodotti Azure), non tutte sono supportate dal runtime di Spark. Qui di seguito è fornito l'elenco dei servizi collegati supportati:

• Archiviazione BLOB di Azure
• Servizi di Azure AI
• Azure Cosmos DB
• Azure Data Explorer
• Database di Azure per MySQL
• Database di Azure per PostgreSQL
• Azure Data Lake Store (Gen1)
• Azure Key Vault
• Azure Machine Learning
• Azure Purview
• Database SQL di Microsoft Azure
• Azure SQL Data Warehouse (dedicato e serverless)
• Archiviazione di Azure

mssparkutils.credentials.getToken()

Quando è necessario un token di connessione OAuth per accedere direttamente ai servizi, è possibile usare il metodo getToken. Sono supportate le risorse seguenti:

Accesso al servizio collegato non supportato dal runtime di Spark

I metodi seguenti per accedere ai servizi collegati non sono supportati dal runtime di Spark:

• Passaggio di argomenti al servizio collegato con parametri
• Connessioni con identità gestite assegnate dall'utente (UAMI)
• Ottenere il token di connessione alla risorsa Keyvault quando il notebook/SparkJobDefinition viene eseguito come identità gestita
  • In alternativa, invece di ottenere un token di accesso, è possibile creare un servizio collegato all'insieme di credenziali delle chiavi e ottenere il segreto dal notebook/processo batch
• Per le connessioni di Azure Cosmos DB, è supportato solo l'accesso basato su chiavi. L'accesso basato su token non è supportato.

Durante l'esecuzione di un notebook o di un processo Spark, le richieste di ottenere un token/segreto usando un servizio collegato potrebbero non riuscire e potrebbe essere visualizzato il messaggio di errore "BadRequest". Questo problema è spesso causato da un problema di configurazione con il servizio collegato. Se viene visualizzato questo messaggio di errore, verificare la configurazione del servizio collegato. Per eventuali domande, contattare il supporto tecnico di Microsoft Azure nel portale di Azure.

Contenuto correlato

• Scrivere nel pool SQL dedicato
• Apache Spark in Azure Synapse Analytics
• Introduzione alle utilità di Microsoft Spark