Zabezpečení přihlašovacích údajů pomocí propojených služeb pomocí nástroje mssparkutils

Přístup k datům z externích zdrojů je běžný vzor. Pokud externí zdroj dat neumožňuje anonymní přístup, pravděpodobně potřebujete zabezpečit připojení pomocí přihlašovacích údajů, tajného kódu nebo připojovací řetězec.

Azure Synapse Analytics ve výchozím nastavení používá předávání Microsoft Entra pro ověřování mezi prostředky. Pokud se potřebujete připojit k prostředku pomocí jiných přihlašovacích údajů, použijte nástroje mssparkutils přímo. Balíček mssparkutils zjednodušuje proces načítání tokenů SAS, tokenů Microsoft Entra, připojovací řetězec a tajných kódů uložených v propojené službě nebo ze služby Azure Key Vault.

Předávání Microsoft Entra používá oprávnění přiřazená vám jako uživatel v ID Microsoft Entra, nikoli oprávnění přiřazená k Synapse nebo samostatnému instančnímu objektu. Pokud například chcete pro přístup k objektu blob v účtu úložiště použít předávání Microsoft Entra, měli byste přejít na tento účet úložiště a přiřadit roli přispěvatele objektů blob sami sobě.

Při načítání tajných kódů ze služby Azure Key Vault doporučujeme vytvořit propojenou službu se službou Azure Key Vault. Ujistěte se, že identita spravované služby pracovního prostoru Synapse (MSI) má ve službě Azure Key Vault oprávnění k získání tajných kódů. Synapse se ověří ve službě Azure Key Vault pomocí identity spravované služby pracovního prostoru Synapse. Pokud se připojujete přímo ke službě Azure Key Vault bez propojené služby, ověřte se pomocí přihlašovacích údajů Microsoft Entra.

Další informace najdete v odkazovaných službách.

Využití

Nápověda pro tokeny a tajné kódy nástroje mssparkutils

Tato funkce zobrazí dokumentaci nápovědy ke správě tajných kódů a tokenů ve službě Synapse.

mssparkutils.credentials.help()

mssparkutils.credentials.help()

Console.WriteLine(TokenLibrary.help());

Získání výsledku:

 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

Přístup ke službě Azure Data Lake Storage Gen2

Primární úložiště ADLS Gen2

Přístup k souborům z primární služby Azure Data Lake Storage používá pro ověřování ve výchozím nastavení předávání Microsoft Entra a nevyžaduje explicitní použití nástrojů mssparkutils. Identita použitá v předávacím ověřování se liší na základě několika faktorů. Ve výchozím nastavení se interaktivní poznámkové bloky spouštějí pomocí identity uživatele, ale dají se změnit na identitu spravované služby pracovního prostoru (MSI). Dávkové úlohy a neinteraktivní spouštění poznámkového bloku používají MSI pracovního prostoru.

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

Úložiště ADLS Gen2 s propojenými službami

Azure Synapse Analytics poskytuje integrované propojené služby při připojování k Azure Data Lake Storage Gen2. Propojené služby je možné nakonfigurovat tak, aby se ověřily pomocí klíče účtu, instančního objektu, spravované identity nebo přihlašovacích údajů.

Pokud je metoda ověřování propojené služby nastavená na klíč účtu, propojená služba se ověřuje pomocí zadaného klíče účtu úložiště, požádá o klíč SAS a automaticky ho použije na žádost o úložiště pomocí LinkedServiceBasedSASProvider.

Synapse umožňuje uživatelům nastavit propojenou službu pro konkrétní účet úložiště. Díky tomu je možné číst a zapisovat data z více účtů úložiště v jedné aplikaci nebo dotazu Spark. Jakmile nastavíme spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName pro každý účet úložiště, který se použije, Synapse zjistí, kterou propojenou službu použít pro konkrétní operaci čtení a zápisu. Pokud se ale naše úloha Sparku zabývá pouze jedním účtem úložiště, můžeme vynechat název účtu úložiště a použít 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()

Pokud je metoda ověřování propojené služby nastavená na spravovanou identitu nebo instanční objekt, propojená služba používá spravovaný token identity nebo instančního objektu s zprostředkovatelem 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()

Nastavení ověřování prostřednictvím konfigurace Sparku

Nastavení ověřování je také možné zadat prostřednictvím konfigurací Sparku místo spouštění příkazů Sparku. Všechny konfigurace Sparku by měly mít předponu spark. a všechny konfigurace hadoopu by měly mít předponu spark.hadoop..

Úložiště ADLS Gen2 bez propojených služeb

Připojte se k úložišti ADLS Gen2 přímo pomocí klíče SAS. ConfBasedSASProvider K nastavení konfigurace použijte klíč SAS a zadejte hospark.storage.synapse.sas. Tokeny SAS je možné nastavit na úrovni kontejneru, na úrovni účtu nebo na globální úrovni. Nedoporučujeme nastavit klíče SAS na globální úrovni, protože úloha nebude moct číst a zapisovat z více než jednoho účtu úložiště.

Konfigurace SAS na kontejner úložiště

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

Konfigurace SAS na účet úložiště

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

Konfigurace SAS pro všechny účty úložiště

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

Použití KNIHOVNY MSAL k získání tokenů (pomocí vlastních přihlašovacích údajů aplikace)

Pokud je ovladač úložiště ABFS nakonfigurovaný tak, aby pro ověřování používal rozhraní MSAL přímo, poskytovatel tokeny mezipaměti neuloží. To může vést k problémům se spolehlivostí. Doporučujeme použít součást ClientCredsTokenProvider Synapse Sparku.

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

Úložiště ADLS Gen2 s tokenem SAS (ze služby Azure Key Vault)

Připojte se k úložišti ADLS Gen2 pomocí tokenu SAS uloženého v tajném kódu služby 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 pro další propojené služby

Pokud se chcete připojit k jiným propojeným službám, můžete provést přímé volání tokenlibrary.

getConnectionString()

K načtení připojovací řetězec použijte getConnectionString funkci a předejte název propojené služby.

%%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 je pomocná funkce dostupná v jazyce Scala a Python, která získá všechny vlastnosti propojené služby.

%%pyspark
import json
# retrieve connectionstring from mssparkutils

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

Výstup bude vypadat takto:

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

GetSecret()

Pokud chcete načíst tajný klíč uložený ze služby Azure Key Vault, doporučujeme vytvořit propojenou službu se službou Azure Key Vault v rámci pracovního prostoru Synapse. Identita spravované služby pracovního prostoru Synapse musí mít udělená oprávnění GET Secrets ke službě Azure Key Vault. Propojená služba použije identitu spravované služby k připojení ke službě Azure Key Vault k načtení tajného kódu. Jinak připojení přímo ke službě Azure Key Vault použije přihlašovací údaje Microsoft Entra uživatele. V takovém případě bude nutné uživateli udělit oprávnění Získat tajný klíč ve službě Azure Key Vault.

V cloudech pro státní správu zadejte plně kvalifikovaný název domény služby keyvault.

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

Pokud chcete načíst tajný klíč ze služby Azure Key Vault, použijte tuto mssparkutils.credentials.getSecret() funkci.

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

Připojení propojených služeb podporovaná z modulu runtime Spark

I když Azure Synapse Analytics podporuje různá propojená připojení služeb (z kanálů a dalších produktů Azure), ne všechny z nich se podporují z modulu runtime Spark. Tady je seznam podporovaných propojených služeb:

• Azure Blob Storage
• Služby 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
• Azure SQL Data Warehouse (vyhrazené a bezserverové)
• Azure Storage

mssparkutils.credentials.getToken()

Pokud potřebujete nosný token OAuth pro přímý přístup ke službám, můžete tuto metodu getToken použít. Podporují se následující zdroje informací:

Nepodporovaný přístup k propojené službě z modulu runtime Spark

Modul runtime Sparku nepodporuje následující metody přístupu k propojeným službám:

• Předání argumentů parametrizované propojené službě
• Připojení se spravovanými identitami přiřazenými uživatelem (UAMI)
• Získání nosného tokenu do prostředku Keyvault při spuštění poznámkového bloku / SparkJobDefinition jako spravovaná identita
  • Jako alternativu můžete místo získání přístupového tokenu vytvořit propojenou službu ke službě Keyvault a získat tajný kód z poznámkového bloku nebo dávkové úlohy.
• U připojení ke službě Azure Cosmos DB se podporuje samotný přístup založený na klíči. Přístup na základě tokenů není podporován.

Při spouštění poznámkového bloku nebo úlohy Sparku můžou žádosti o získání tokenu nebo tajného kódu pomocí propojené služby selhat s chybovou zprávou, která značí BadRequest. Příčinou je často problém s konfigurací propojené služby. Pokud se zobrazí tato chybová zpráva, zkontrolujte konfiguraci propojené služby. Pokud máte nějaké dotazy, obraťte se na podporu Microsoft Azure na webu Azure Portal.

Související obsah

• Zápis do vyhrazeného fondu SQL
• Apache Spark v Azure Synapse Analytics
• Úvod do nástrojů Microsoft Sparku