Zabezpieczanie poświadczeń za pomocą połączonych usług przy użyciu narzędzia mssparkutils

Uzyskiwanie dostępu do danych ze źródeł zewnętrznych jest typowym wzorcem. Jeśli zewnętrzne źródło danych nie zezwala na dostęp anonimowy, prawdopodobnie będziesz musiał zabezpieczyć swoje połączenie za pomocą poświadczeń, sekretu lub ciągu połączenia.

Usługa Azure Synapse Analytics domyślnie wykorzystuje funkcję Microsoft Entra passthrough do uwierzytelniania między zasobami. Jeśli musisz nawiązać połączenie z zasobem przy użyciu innych poświadczeń, użyj narzędzia mssparkutils bezpośrednio. Pakiet mssparkutils upraszcza proces pobierania tokenów SAS, tokenów Microsoft Entra, łańcuchów połączeń i wpisów tajnych przechowywanych w połączonej usłudze lub z usługi Azure Key Vault.

Usługa Microsoft Entra passthrough używa uprawnień przypisanych do Ciebie jako użytkownik w Microsoft Entra ID, a nie uprawnień przypisanych do usługi Synapse lub oddzielnej jednostki usługi. Jeśli na przykład chcesz użyć przekazywania usługi Microsoft Entra w celu uzyskania dostępu do obiektu blob na koncie magazynu, przejdź do tego konta magazynu i przypisz rolę współautora obiektów blob do siebie.

Podczas pobierania wpisów tajnych z usługi Azure Key Vault zalecamy utworzenie połączonej usługi z usługą Azure Key Vault. Upewnij się, że zarządzana tożsamość usługi (MSI) obszaru roboczego Synapse ma uprawnienia do pobierania wpisów tajnych w usłudze Azure Key Vault. Usługa Synapse będzie uwierzytelniać się w usłudze Azure Key Vault przy użyciu tożsamości usługi zarządzanej obszaru roboczego usługi Synapse. Jeśli łączysz się bezpośrednio z usługą Azure Key Vault bez połączonej usługi, uwierzytelnij się przy użyciu poświadczeń użytkownika Microsoft Entra.

Aby uzyskać więcej informacji, zobacz połączone usługi.

Użycie

pomoc mssparkutils dotycząca tokenów i sekretów

Ta funkcja wyświetla dokumentację pomocy dotyczącą zarządzania tajnymi danymi i tokenami w usłudze Synapse.

mssparkutils.credentials.help()

mssparkutils.credentials.help()

Console.WriteLine(TokenLibrary.help());

Uzyskaj wynik:

 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

Uzyskiwanie dostępu do usługi Azure Data Lake Storage Gen2

Magazyn podstawowy usługi ADLS Gen2

Uzyskiwanie dostępu do plików z podstawowej usługi Azure Data Lake Storage domyślnie używa przekazywania usługi Microsoft Entra do uwierzytelniania i nie wymaga jawnego użycia narzędzia mssparkutils. Tożsamość używana w uwierzytelnianiu przekazującym różni się w zależności od kilku czynników. Domyślnie notesy interaktywne są wykonywane przy użyciu tożsamości użytkownika, ale można to zmienić na tożsamość usługi zarządzanej przez obszar roboczy (MSI). Zadania wsadowe i nieinterakcyjne wykonania notesu używają pliku MSI obszaru roboczego.

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

Magazyn usługi ADLS Gen2 z połączonymi usługami

Usługa Azure Synapse Analytics zapewnia zintegrowane połączone środowisko usług podczas nawiązywania połączenia z usługą Azure Data Lake Storage Gen2. Połączone usługi można skonfigurować do uwierzytelniania przy użyciu klucza konta, jednostki usługi, tożsamości zarządzanej lub poświadczeń.

Gdy metoda uwierzytelniania połączonej usługi jest ustawiona na klucz konta, połączona usługa uwierzytelnia się przy użyciu podanego klucza konta magazynu, żąda klucza SYGNATURy dostępu współdzielonego i automatycznie zastosuje ją do żądania magazynu przy użyciu elementu LinkedServiceBasedSASProvider.

Usługa Synapse umożliwia użytkownikom ustawianie połączonej usługi dla określonego konta magazynu. Dzięki temu można odczytywać/zapisywać dane z wielu kont magazynujących w jednym zadaniu zapytania lub aplikacji Apache Spark. Po ustawieniu spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName dla każdego używanego konta magazynowego, Synapse ustala, którą połączoną usługę należy użyć dla określonej operacji odczytu/zapisu. Jeśli jednak nasze zadanie platformy Spark dotyczy tylko jednego konta magazynu, możemy pominąć nazwę konta magazynu i użyć polecenia 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()

Gdy metoda uwierzytelniania połączonej usługi jest ustawiona na tożsamość zarządzaną lub zasób główny usługi, połączona usługa używa tokenu tożsamości zarządzanej lub zasobu głównego usługi z dostawcą 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()

Ustawianie ustawień uwierzytelniania za pomocą konfiguracji platformy Spark

Ustawienia uwierzytelniania można również określić za pomocą konfiguracji platformy Spark zamiast uruchamiania instrukcji platformy Spark. Wszystkie konfiguracje platformy Spark powinny być poprzedzone prefiksem spark. i wszystkie konfiguracje hadoop powinny mieć prefiks .spark.hadoop.

Przechowywanie ADLS Gen2 bez połączonych usług

Połącz się bezpośrednio z magazynem usługi ADLS Gen2 przy użyciu klucza SAS. Użyj znacznika ConfBasedSASProvider i podaj klucz SAS do ustawienia konfiguracyjnego spark.storage.synapse.sas. Tokeny sygnatury dostępu współdzielonego można ustawić na poziomie kontenera, na poziomie konta lub na poziomie globalnym. Nie zalecamy ustawiania kluczy SAS na poziomie globalnym, ponieważ zadanie nie będzie mogło odczytywać/zapisywać z więcej niż jednego konta magazynowego.

Konfiguracja SAS na kontener magazynowy

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

Konfiguracja sygnatury dostępu współdzielonego dla każdego konta magazynowego

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

Konfiguracja sygnatur dostępu współdzielonego (SAS) dla wszystkich kont magazynowych

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

Uzyskiwanie tokenów za pomocą biblioteki MSAL (z wykorzystaniem niestandardowych poświadczeń aplikacji)

Jeśli sterownik magazynu ABFS jest skonfigurowany do bezpośredniego używania biblioteki MSAL do uwierzytelniania, to dostawca nie buforuje tokenów. Może to spowodować problemy z niezawodnością. Zalecamy użycie elementu ClientCredsTokenProvider, który jest częścią platformy 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))

Magazyn ADLS Gen2 z tokenem SAS (Azure Key Vault)

Połącz się z magazynem usługi ADLS Gen2 przy użyciu tokenu SAS przechowywanego w sekrecie usługi 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 dla innych połączonych usług

Aby nawiązać połączenie z innymi połączonymi usługami, możesz wykonać bezpośrednie wywołanie do TokenLibrary.

getConnectionString()

Aby pobrać parametry połączenia, użyj getConnectionString funkcji i przekaż połączoną nazwę usługi.

%%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 to funkcja pomocnika dostępna w języku Scala i Python, aby uzyskać wszystkie właściwości połączonej usługi

%%pyspark
import json
# retrieve connectionstring from mssparkutils

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

Dane wyjściowe będą wyglądać następująco:

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

GetSecret()

Aby pobrać wpis tajny przechowywany z usługi Azure Key Vault, zalecamy utworzenie połączonej usługi Azure Key Vault w obszarze roboczym usługi Synapse. Tożsamość usługi zarządzanej obszaru roboczego usługi synapse musi mieć uprawnienie GET Secrets do usługi Azure Key Vault. Powiązana usługa użyje tożsamości usługi zarządzanej, aby połączyć się z usługą Azure Key Vault w celu pobrania tajnej wartości. W przeciwnym razie nawiązanie połączenia bezpośrednio z usługą Azure Key Vault spowoduje użycie poświadczeń użytkownika Microsoft Entra. W takim przypadku użytkownik musi otrzymać uprawnienia do pobierania tajnych wpisów w usłudze Azure Key Vault.

W chmurach dla instytucji rządowych podaj w pełni kwalifikowaną nazwę domeny magazynu kluczy.

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

Aby pobrać wpis tajny z usługi Azure Key Vault, użyj funkcji 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);

Połączenia usług połączonych obsługiwane przez środowisko uruchomieniowe Spark.

Chociaż usługa Azure Synapse Analytics obsługuje różne połączone połączenia usług (z potoków i innych produktów platformy Azure), nie wszystkie z nich są obsługiwane przez środowisko uruchomieniowe platformy Spark. Oto lista obsługiwanych połączonych usług:

• Azure Blob Storage
• Usługi platformy Azure AI
• 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
• Usługa Azure SQL Data Warehouse (dedykowana i bezserwerowa)
• Azure Storage

mssparkutils.credentials.getToken()

Jeśli potrzebujesz tokenu dostępu OAuth, aby uzyskać bezpośredni dostęp do usług, możesz użyć metody getToken. Obsługiwane są następujące zasoby:

Nieobsługiwany dostęp do połączonej usługi ze środowiska uruchomieniowego platformy Spark

Następujące metody uzyskiwania dostępu do połączonych usług nie są obsługiwane w środowisku uruchomieniowym platformy Spark:

• Przekazywanie argumentów do sparametryzowanej połączonej usługi
• Połączenia z zarządzanymi tożsamościami przypisanymi przez użytkownika (UAMI)
• Pobieranie tokenu uwierzytelniającego do zasobu Keyvault, gdy notatnik lub SparkJobDefinition jest uruchamiany jako tożsamość zarządzana
  • Alternatywnie zamiast uzyskiwania tokenu dostępu można utworzyć połączoną usługę z usługą Keyvault i pobrać wpis tajny z zadania notesu/partii
• W przypadku połączeń usługi Azure Cosmos DB sam dostęp oparty na kluczach jest obsługiwany. Dostęp oparty na tokenach nie jest obsługiwany.

Podczas uruchamiania notesu lub zadania platformy Spark, żądania uzyskania tokenu lub sekretu przy użyciu połączonej usługi mogą zakończyć się niepowodzeniem z komunikatem o błędzie 'BadRequest'. Jest to często spowodowane problemem z konfiguracją połączonej usługi. Jeśli widzisz ten komunikat o błędzie, sprawdź konfigurację połączonej usługi. Jeśli masz jakiekolwiek pytania, skontaktuj się z pomocą techniczną platformy Microsoft Azure w witrynie Azure Portal.

Powiązana zawartość

• Zapisz do dedykowanej puli SQL
• Apache Spark w usłudze Azure Synapse Analytics
• Wprowadzenie do narzędzi Microsoft Spark