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, istnieje potrzeba zabezpieczenia połączenia przy użyciu poświadczeń, wpisu tajnego lub parametry połączenia.

Usługa Azure Synapse Analytics domyślnie używa przekazywania usługi Microsoft Entra na potrzeby 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, parametry połączenia 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 identyfikatorze Entra firmy Microsoft, 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 tożsamość usługi zarządzanej obszaru roboczego usługi Synapse (MSI) ma uprawnienia Uzyskiwanie 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 dotycząca tokenów i wpisów tajnych narzędzia mssparkutils

Ta funkcja wyświetla dokumentację pomocy dotyczącą zarządzania wpisami tajnymi 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 je zmienić na tożsamość usługi zarządzanej obszaru roboczego (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 magazynu w jednej aplikacji/zapytaniu platformy Spark. Po ustawieniu spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName dla każdego konta magazynu, które będzie używane, usługa Synapse ustala, która połączona usługa ma być używana 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 połączona metoda uwierzytelniania usługi jest ustawiona na tożsamość zarządzaną lub jednostkę usługi, połączona usługa używa tokenu tożsamości zarządzanej lub jednostki 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.

Magazyn usługi ADLS Gen2 bez połączonych usług

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

Konfiguracja sygnatury dostępu współdzielonego na kontener magazynu

%%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 na konto magazynu

%%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 sygnatury dostępu współdzielonego dla wszystkich kont magazynu

%%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 przy użyciu biblioteki MSAL (przy użyciu poświadczeń aplikacji niestandardowych)

Jeśli sterownik magazynu ABFS jest skonfigurowany do bezpośredniego używania biblioteki MSAL do uwierzytelniania, dostawca nie buforuje tokenów. Może to spowodować problemy z niezawodnością. Zalecamy użycie elementu ClientCredsTokenProvider 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 usługi ADLS Gen2 z tokenem SAS (z usługi Azure Key Vault)

Połącz się z magazynem usługi ADLS Gen2 przy użyciu tokenu SAS przechowywanego w wpisie tajnym 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 tokenuLibrary.

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. Połączona usługa użyje tożsamości usługi zarządzanej do nawiązania połączenia z usługą Azure Key Vault w celu pobrania wpisu tajnego. 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 Uzyskiwanie wpisu tajnego 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 mssparkutils.credentials.getSecret() funkcji .

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 połączonej usługi obsługiwane przez środowisko uruchomieniowe platformy 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 elementu nośnego OAuth, aby uzyskać bezpośredni dostęp do usług, możesz użyć getToken metody . 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 tożsamościami zarządzanymi przypisanymi przez użytkownika (UAMI)
• Pobieranie tokenu elementu nośnego do zasobu usługi Keyvault, gdy notes/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/wpisu tajnego przy użyciu połączonej usługi mogą zakończyć się niepowodzeniem z komunikatem o błędzie wskazującym błąd "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ść

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