Защита учетных данных с помощью связанных служб с помощью mssparkutils
Доступ к данным из внешних источников является распространенным шаблоном. Если внешний источник данных разрешает анонимный доступ, то, вероятно, потребуется защитить подключение с помощью учетных данных, секрета или строки подключения.
Azure Synapse Analytics использует сквозное руководство Microsoft Entra по умолчанию для проверки подлинности между ресурсами. Если необходимо подключиться к ресурсу с помощью других учетных данных, используйте mssparkutils напрямую. Пакет mssparkutils упрощает процесс получения маркеров SAS, маркеров Microsoft Entra, строка подключения и секретов, хранящихся в связанной службе или из Azure Key Vault.
Сквозное руководство Microsoft Entra использует разрешения, назначенные пользователю в идентификаторе Microsoft Entra, а не разрешения, назначенные Synapse или отдельному субъекту-службе. Например, если вы хотите использовать сквозное руководство Microsoft Entra для доступа к большому двоичному объекту в учетной записи хранения, перейдите к этой учетной записи хранения и назначьте роль участника BLOB-объектов себе.
Для получения секретов из Azure Key Vault мы рекомендуем создать службу, связанную с Azure Key Vault. При этом нужно предоставить удостоверению управляемой службы рабочей области Synapse привилегии на получение секретов из такого хранилища Azure Key Vault. Чтобы аутентифицироваться в Azure Key Vault, Synapse будет использовать удостоверение управляемой службы рабочей области Synapse. Если вы подключаетесь непосредственно к Azure Key Vault без связанной службы, выполните проверку подлинности с помощью учетных данных Microsoft Entra.
Дополнительные сведения см. в статье о связанных службах.
Использование
Mssparkutils помогает для маркеров и секретов
Эта функция отображает справочную документацию по управлению секретами и токенами в Synapse.
mssparkutils.credentials.help()
mssparkutils.credentials.help()
Console.WriteLine(TokenLibrary.help());
Полученный результат:
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
Доступ Azure Data Lake Storage 2-го поколения
Основное хранилище Azure Data Lake Storage 2-го поколения
Доступ к файлам из основного azure Data Lake Storage использует сквозное руководство Microsoft Entra для проверки подлинности по умолчанию и не требует явного использования mssparkutils. Удостоверение, используемое в сквозной проверке подлинности, отличается на основе нескольких факторов. По умолчанию интерактивные записные книжки выполняются с помощью удостоверения пользователя, но его можно изменить на удостоверение управляемой службы рабочей области (MSI). Пакетные задания и неинтерактивные выполнения записной книжки используют MSI рабочей области.
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 2-го поколения со связанными службами
Azure Synapse Analytics предоставляет интегрированные связанные службы при подключении к Azure Data Lake Storage 2-го поколения. Связанные службы можно настроить для проверки подлинности с помощью ключа учетной записи, субъекта-службы, управляемого удостоверения или учетных данных.
Если для метода проверки подлинности связанной службы задано значение Account Key, связанная служба проходит проверку подлинности с помощью предоставленного ключа учетной записи хранения, запрашивает ключ SAS и автоматически применяет его к запросу хранилища с помощью LinkedServiceBasedSASProvider.
Synapse позволяет пользователям указывать связанную службу для определенной учетной записи хранения. Благодаря этому можно считывать и записывать данные в нескольких учетных записях хранения в одном приложении или запросе Spark. После установки spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName каждой учетной записи хранения, которая будет использоваться, Synapse определяет, какая связанная служба будет использоваться для определенной операции чтения и записи. Однако если задание Spark работает только с одной учетной записью хранения, мы можем опустить имя учетной записи хранения и использовать spark.storage.synapse.linkedServiceName.
Примечание.
Невозможно изменить метод проверки подлинности контейнера хранилища 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()
Если для метода проверки подлинности связанной службы задано значение Managed Identity или Service Principal, связанная служба использует маркер управляемого удостоверения или субъекта-службы с поставщиком 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()
Настройка параметров проверки подлинности с помощью конфигурации Spark
Параметры проверки подлинности также можно указать с помощью конфигураций Spark, а не с помощью инструкций Spark. Все конфигурации Spark должны быть префиксированы с spark. префиксом и все конфигурации hadoop должны быть префиксированы с spark.hadoop.помощью .
| Имя конфигурации Spark | Значение конфигурации |
|---|---|
spark.storage.synapse.teststorage.dfs.core.windows.net.linkedServiceName |
ИМЯ СВЯЗАННОЙ СЛУЖБЫ |
spark.hadoop.fs.azure.account.oauth.provider.type.teststorage.dfs.core.windows.net |
microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider |
Хранилище ADLS 2-го поколения без связанных служб
Подключитесь к хранилищу ADLS 2-го поколения непосредственно с помощью ключа SAS. ConfBasedSASProvider Используйте и укажите ключ SAS для spark.storage.synapse.sas параметра конфигурации. Маркеры SAS можно задать на уровне контейнера, уровне учетной записи или глобальном. Не рекомендуется устанавливать ключи SAS на глобальном уровне, так как задание не сможет читать и записывать данные из нескольких учетных записей хранения.
Конфигурация SAS для контейнера хранилища
%%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 для учетной записи хранения
%%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 всех учетных записей хранения
%%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))
Использование MSAL для получения маркеров (с помощью пользовательских учетных данных приложения)
Если драйвер хранилища ABFS настроен для использования MSAL непосредственно для проверки подлинности, поставщик не кэширует маркеры. Это может привести к проблемам надежности. Рекомендуется использовать ClientCredsTokenProvider компонент 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 2-го поколения с маркером SAS (из Azure Key Vault)
Вы можете подключиться к хранилищу ADLS 2-го поколения с помощью маркера SAS, сохраненного в секрете 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 для других связанных служб
Чтобы подключиться к другим связанным службам, можно выполнить прямой вызов TokenLibrary.
getConnectionString()
Чтобы получить строка подключения, используйте getConnectionString функцию и передайте имя связанной службы.
%%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 — это вспомогательные функции, доступные в Scala и Python, чтобы получить все свойства связанной службы.
%%pyspark
import json
# retrieve connectionstring from mssparkutils
json.loads(mssparkutils.credentials.getPropertiesAll("<LINKED SERVICE NAME>"))
Выходные данные будут выглядеть следующим образом.
{
'AuthType': 'Key',
'AuthKey': '[REDACTED]',
'Id': None,
'Type': 'AzureBlobStorage',
'Endpoint': 'https://storageaccount.blob.core.windows.net/',
'Database': None
}
GetSecret()
Для получения секрета, хранящегося в Azure Key Vault, мы рекомендуем создать связанную службу для Azure Key Vault в рабочей области Synapse. При этом удостоверению управляемой службы рабочей области Synapse потребуется предоставить права на получение секретов из Azure Key Vault. Связанная служба будет использовать удостоверение управляемой службы для подключения к службе Azure Key Vault, чтобы получить секрет. В противном случае подключение непосредственно к Azure Key Vault будет использовать учетные данные Microsoft Entra пользователя. В такой ситуации необходимо будет предоставить пользователю разрешения на получение секретов из Azure Key Vault.
В облаках государственных организаций укажите полное доменное имя ключа.
mssparkutils.credentials.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>" [, <LINKED SERVICE NAME>])
Чтобы получить секрет из Azure Key Vault, используйте функцию 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);
Подключения связанной службы, поддерживаемые средой выполнения Spark
Хотя Azure Synapse Analytics поддерживает различные подключения к связанной службе (из конвейеров и других продуктов Azure), не все из них поддерживаются из среды выполнения Spark. Ниже приведен список поддерживаемых связанных служб:
- Хранилище BLOB-объектов Azure
- Службы ИИ Azure
- Azure Cosmos DB
- Azure Data Explorer
- База данных Azure для MySQL
- База данных Azure для PostgreSQL
- Azure Data Lake Store (1-го поколения)
- Azure Key Vault
- Машинное обучение Azure
- Azure Purview
- База данных SQL Azure
- Хранилище данных SQL Azure (выделенное и бессерверное)
- Хранилище Azure
mssparkutils.credentials.getToken()
Если вам нужен маркер носителя OAuth для доступа к службам напрямую, можно использовать getToken этот метод. Поддерживаются следующие ресурсы:
| Имя службы | Строковый литерал, используемый в вызове 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 |
Неподдерживаемый доступ к связанной службе из среды выполнения Spark
Следующие методы доступа к связанным службам не поддерживаются из среды выполнения Spark:
- Передача аргументов параметризованной связанной службе
- Подключения с управляемыми удостоверениями, назначаемыми пользователем (UAMI)
- Получение маркера носителя в ресурс Keyvault при запуске записной книжки или SparkJobDefinition в качестве управляемого удостоверения
- Вместо получения маркера доступа можно создать связанную службу в Keyvault и получить секрет из записной книжки или пакетного задания.
- Для подключений Azure Cosmos DB поддерживается только доступ на основе ключей. Доступ на основе маркеров не поддерживается.
При выполнении задания Записной книжки или Spark запросы на получение маркера или секрета с помощью связанной службы могут завершиться ошибкой с сообщением об ошибке, указывающее "BadRequest". Это часто вызвано проблемой конфигурации связанной службы. Если вы видите это сообщение об ошибке, проверьте конфигурацию связанной службы. Если у вас возникли вопросы, обратитесь в службу поддержки Microsoft Azure на портал Azure.