Защита учетных данных с помощью связанных служб с помощью 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 служба хранилища использует сквозное руководство 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-го поколения. Связанные службы можно настроить для проверки подлинности с помощью ключа учетной записи, субъекта-службы, управляемого удостоверения или учетных данных.

Если в качестве метода аутентификации для связанной службы выбран ключ учетной записи, связанная служба будет выполнять аутентификацию с использованием предоставленного ключа учетной записи хранения, запрашивать ключ SAS и автоматически применять его к запросу хранилища через поставщика LinkedServiceBasedSASProvider.

Synapse позволяет пользователям указывать связанную службу для определенной учетной записи хранения. Благодаря этому можно считывать и записывать данные в нескольких учетных записях хранения в одном приложении или запросе Spark. После установки параметра spark.storage.synapse.{полное_имя_исходной_учетной_записи}.linkedServiceName для каждой используемой учетной записи хранения Synapse определяет, какая связанная служба будет применяться для определенной операции чтения/записи. Однако если задание Spark работает только с одной учетной записью хранения, можно просто опустить имя учетной записи хранения и использовать 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()

Если в качестве метода аутентификации для связанной службы выбрано управляемое удостоверение или субъект-служба, связанная служба будет использовать управляемое удостоверение или маркер субъекта-службы с поставщиком 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 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))

Хранилище ADLS 2-го поколения с 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
Azure Key Vault	Vault
Управление и безопасность	AzureManagement
Хранилище данных SQL Azure (выделенное и бессерверное)	DW
Azure Synapse	Synapse
Azure Data Lake Store	DataLakeStore
Azure Data Factory	ADF
Azure Data Explorer	AzureDataExplorer
База данных Azure для MySQL	AzureOSSDB
База данных Azure для MariaDB	AzureOSSDB
База данных Azure для PostgreSQL	AzureOSSDB

Неподдерживаемый доступ к связанной службе из среды выполнения Spark

Следующие методы доступа к связанным службам не поддерживаются из среды выполнения Spark:

• Передача аргументов параметризованной связанной службе
• Подключение ions с назначенными пользователем управляемыми удостоверениями (UAMI)
• Управляемые удостоверения, назначенные системой, не поддерживаются в ресурсе Keyvault
• Для подключений Azure Cosmos DB поддерживается только доступ на основе ключей. Доступ на основе маркеров не поддерживается.

При выполнении задания Записной книжки или Spark запросы на получение маркера или секрета с помощью связанной службы могут завершиться ошибкой с сообщением об ошибке, указывающее "BadRequest". Это часто вызвано проблемой конфигурации связанной службы. Если вы видите это сообщение об ошибке, проверка конфигурацию связанной службы. Если у вас возникли вопросы, обратитесь в службу поддержки Microsoft Azure в портал Azure.

Связанный контент

• Запись в выделенный пул SQL
• Ключевые концепции Apache Spark в Azure Synapse Analytics
• Общие сведения о Microsoft Spark Utilities