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

Artikel
11/08/2023

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 hjälp av din microsoft entra-autentiseringsuppgift.

Mer information finns i länkade tjänster.

Användning

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

Komma åt 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 helt enkelt utelämna lagringskontots namn och använda 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()

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

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

ADLS Gen2-lagring med 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.

get Anslut ionString()

Om du vill hämta anslutningssträng använder du funktionen get Anslut ionString 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 det fullständigt kvalificerade domännamnet för keyvault 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 funktionen 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);

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

Azure Synapse Analytics stöder en mängd 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
AI-tjänster i Azure
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-hantering	`AzureManagement`
Azure SQL Data Warehouse (dedikerad och serverlös)	`DW`
Azure Synapse	`Synapse`
Azure Data Lake Store	`DataLakeStore`
Azure Data Factory	`ADF`
Öppna Azure-datautforskaren	`AzureDataExplorer`
Azure Database for MySQL	`AzureOSSDB`
Azure-databas för 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
Anslut med användartilldelade hanterade identiteter (UAMI)
Systemtilldelade hanterade identiteter stöds inte på Keyvault-resursen
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-supporten på Azure-portalen.