Dela via

Skydda autentiseringsuppgifter med länkade tjänster med hjälp av mssparkutils

  • Artikel

Att komma åt data från externa källor är ett vanligt mönster. Om inte den externa datakällan tillåter anonym åtkomst är chansen stor att du behöver skydda anslutningen med en autentiseringsuppgift, hemlighet eller anslutningssträng.

Azure Synapse Analytics använder Microsoft Entra-genomströmning som standard för autentisering mellan resurser. Om du behöver ansluta till en resurs med andra autentiseringsuppgifter använder du mssparkutils direkt. Mssparkutils-paketet förenklar processen för att hämta SAS-token, Microsoft Entra-token, anslutningssträng och hemligheter som lagras i en länkad tjänst eller från ett Azure Key Vault.

Microsoft Entra-genomströmning använder behörigheter som tilldelats dig som användare i Microsoft Entra-ID i stället för behörigheter som tilldelats Synapse eller ett separat huvudnamn för tjänsten. Om du till exempel vill använda Microsoft Entra-genomströmning för att komma åt en blob i ett lagringskonto bör du gå till det lagringskontot och tilldela blobdeltagarerollen till dig själv.

När du hämtar hemligheter från Azure Key Vault rekommenderar vi att du skapar en länkad tjänst till ditt Azure Key Vault. Se till att den hanterade tjänstidentiteten för Synapse-arbetsytan (MSI) har secret get-behörigheter i ditt Azure Key Vault. Synapse autentiserar till Azure Key Vault med hjälp av den hanterade tjänstidentiteten för Synapse-arbetsytan. Om du ansluter direkt till Azure Key Vault utan en länkad tjänst autentiserar du med din användares Microsoft Entra-autentiseringsuppgifter.

Mer information finns i länkade tjänster.

Förbrukning

mssparkutils hjälp för token och hemligheter

Den här funktionen visar hjälpdokumentationen för hantering av hemligheter och token i Synapse.

mssparkutils.credentials.help()

mssparkutils.credentials.help()

Console.WriteLine(TokenLibrary.help());

Hämta resultat:

 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

Få åtkomst till Azure Data Lake Storage Gen2

Primär lagring i ADLS Gen2

Åtkomst till filer från den primära Azure Data Lake Storage använder Microsoft Entra-genomströmning för autentisering som standard och kräver inte explicit användning av mssparkutils. Identiteten som används i genomströmningsautentiseringen skiljer sig beroende på några faktorer. Som standard körs interaktiva notebook-filer med användarens identitet, men de kan ändras till den hanterade tjänstidentiteten för arbetsytan (MSI). Batch-jobb och icke-interaktiva körningar av notebook-filen använder MSI för arbetsytan.

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

ADLS Gen2-lagring med länkade tjänster

Azure Synapse Analytics tillhandahåller en integrerad upplevelse av länkade tjänster när du ansluter till Azure Data Lake Storage Gen2. Länkade tjänster kan konfigureras för att autentisera med hjälp av en kontonyckel, tjänstens huvudnamn, hanterad identitet eller autentiseringsuppgifter.

När den länkade tjänstautentiseringsmetoden är inställd på Kontonyckel autentiseras den länkade tjänsten med hjälp av den angivna lagringskontonyckeln, begär en SAS-nyckel och tillämpar den automatiskt på lagringsbegäran med hjälp av LinkedServiceBasedSASProvider.

Synapse gör det möjligt för användare att ange den länkade tjänsten för ett visst lagringskonto. Detta gör det möjligt att läsa/skriva data från flera lagringskonton i ett enda Spark-program/en fråga. När vi har angett spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName för varje lagringskonto som ska användas räknar Synapse ut vilken länkad tjänst som ska användas för en viss läs-/skrivåtgärd. Men om vårt Spark-jobb bara hanterar ett enda lagringskonto kan vi utelämna lagringskontots namn och använda spark.storage.synapse.linkedServiceName.

Kommentar

Det går inte att ändra autentiseringsmetoden för ABFS-standardlagringscontainern.

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

När den länkade tjänstautentiseringsmetoden är inställd på Hanterad identitet eller Tjänstens huvudnamn använder den länkade tjänsten token Hanterad identitet eller Tjänstens huvudnamn med providern 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()

Ange autentiseringsinställningar via Spark-konfiguration

Autentiseringsinställningar kan också anges via Spark-konfigurationer i stället för att köra spark-instruktioner. Alla Spark-konfigurationer ska vara prefix med spark. och alla hadoop-konfigurationer ska vara prefix med spark.hadoop..

Spark-konfigurationsnamn Konfigurationsvärde
spark.storage.synapse.teststorage.dfs.core.windows.net.linkedServiceName LÄNKAT TJÄNSTNAMN
spark.hadoop.fs.azure.account.oauth.provider.type.teststorage.dfs.core.windows.net microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider

ADLS Gen2-lagring utan länkade tjänster

Anslut till ADLS Gen2-lagring direkt med hjälp av en SAS-nyckel. ConfBasedSASProvider Använd och ange SAS-nyckeln till konfigurationsinställningenspark.storage.synapse.sas. SAS-token kan anges på containernivå, kontonivå eller global. Vi rekommenderar inte att du ställer in SAS-nycklar på global nivå eftersom jobbet inte kan läsa/skriva från fler än ett lagringskonto.

SAS-konfiguration per lagringscontainer

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

SAS-konfiguration per lagringskonto

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

SAS-konfiguration av alla lagringskonton

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

Använda MSAL för att hämta token (med anpassade appautentiseringsuppgifter)

När ABFS-lagringsdrivrutinen är konfigurerad att använda MSAL direkt för autentiseringar cachelagrar inte providern token. Detta kan leda till tillförlitlighetsproblem. Vi rekommenderar att du använder ClientCredsTokenProvider är en del av 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))

ADLS Gen2-lagring med SAS-token (från Azure Key Vault)

Anslut till ADLS Gen2-lagring med hjälp av en SAS-token som lagras i Azure Key Vault-hemligheten.

%%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 för andra länkade tjänster

Om du vill ansluta till andra länkade tjänster kan du göra ett direktanrop till TokenLibrary.

getConnectionString()

Om du vill hämta anslutningssträng använder du getConnectionString funktionen och skickar det länkade tjänstnamnet.

%%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 är en hjälpfunktion som är tillgänglig i Scala och Python för att hämta alla egenskaper för en länkad tjänst

%%pyspark
import json
# retrieve connectionstring from mssparkutils

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

Utdata ser ut som

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

GetSecret()

Om du vill hämta en hemlighet som lagras från Azure Key Vault rekommenderar vi att du skapar en länkad tjänst till Azure Key Vault på Synapse-arbetsytan. Den hanterade tjänstidentiteten för Synapse-arbetsytan måste beviljas behörigheten GET Secrets till Azure Key Vault. Den länkade tjänsten använder den hanterade tjänstidentiteten för att ansluta till Azure Key Vault-tjänsten för att hämta hemligheten. I annat fall använder anslutning direkt till Azure Key Vault användarens Microsoft Entra-autentiseringsuppgifter. I det här fallet måste användaren beviljas behörigheterna Hämta hemlighet i Azure Key Vault.

Ange nyckelvaultens fullständigt kvalificerade domännamn i myndighetsmoln.

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

Om du vill hämta en hemlighet från Azure Key Vault använder du mssparkutils.credentials.getSecret() funktionen.


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

Länkade tjänstanslutningar som stöds från Spark-körningen

Azure Synapse Analytics stöder olika länkade tjänstanslutningar (från pipelines och andra Azure-produkter), men alla stöds inte från Spark-körningen. Här är listan över länkade tjänster som stöds:

  • Azure Blob Storage
  • Azure AI-tjänster
  • Azure Cosmos DB
  • Azure Data Explorer
  • Azure Database for MySQL
  • Azure Database for PostgreSQL
  • Azure Data Lake Store (Gen1)
  • Azure Key Vault
  • Azure Machine Learning
  • Azure Purview
  • Azure SQL Database
  • Azure SQL Data Warehouse (dedikerad och serverlös)
  • Azure Storage

mssparkutils.credentials.getToken()

När du behöver en OAuth-ägartoken för att komma åt tjänster direkt kan du använda getToken metoden. Följande resurser stöds:

Tjänstens namn Strängliteral som ska användas i API-anrop
Azure Storage Storage
Azure Key Vault Vault
Azure Management AzureManagement
Azure SQL Data Warehouse (Dedicated and Serverless) DW
Azure Synapse Synapse
Azure Data Lake Store DataLakeStore
Azure Data Factory ADF
Azure Data Explorer AzureDataExplorer
Azure Database for MySQL AzureOSSDB
Azure Database for MariaDB AzureOSSDB
Azure Database for PostgreSQL AzureOSSDB

Länkad tjänståtkomst som inte stöds från Spark-körningen

Följande metoder för att komma åt de länkade tjänsterna stöds inte från Spark-körningen:

  • Skicka argument till parametriserad länkad tjänst
  • Anslutningar med användartilldelade hanterade identiteter (UAMI)
  • Hämta ägartoken till Keyvault-resursen när notebook-filen/SparkJobDefinition körs som hanterad identitet
    • Som ett alternativ kan du i stället för att hämta en åtkomsttoken skapa en länkad tjänst till Keyvault och hämta hemligheten från notebook-/batchjobbet
  • Endast nyckelbaserad åtkomst stöds för Azure Cosmos DB-anslutningar. Tokenbaserad åtkomst stöds inte.

När du kör en notebook-fil eller ett Spark-jobb kan begäranden om att hämta en token/hemlighet med hjälp av en länkad tjänst misslyckas med ett felmeddelande som anger "BadRequest". Detta orsakas ofta av ett konfigurationsproblem med den länkade tjänsten. Om du ser det här felmeddelandet kontrollerar du konfigurationen av den länkade tjänsten. Om du har några frågor kontaktar du Microsoft Azure Support på Azure Portal.

Relaterat innehåll