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
.
Uwaga
Nie można zmienić metody uwierzytelniania domyślnego kontenera magazynu ABFS.
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.
Nazwa konfiguracji platformy Spark | Wartość konfiguracji |
---|---|
spark.storage.synapse.teststorage.dfs.core.windows.net.linkedServiceName |
NAZWA POŁĄCZONEJ USŁUGI |
spark.hadoop.fs.azure.account.oauth.provider.type.teststorage.dfs.core.windows.net |
microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider |
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:
Nazwa usługi | Literał ciągu do użycia w wywołaniu interfejsu API |
---|---|
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 |
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.