Referenties beveiligen met gekoppelde services met behulp van de mssparkutils

  • Artikel

Toegang tot gegevens uit externe bronnen verkrijgen is een veelvoorkomend patroon. Tenzij de externe gegevensbron anonieme toegang toestaat, is de kans groot dat u uw verbinding moet beveiligen met een referentie, geheim of verbindingsreeks.

Azure Synapse Analytics maakt standaard gebruik van Microsoft Entra Passthrough voor verificatie tussen resources. Als u verbinding wilt maken met een resource met andere referenties, gebruikt u de mssparkutils rechtstreeks. Het mssparkutils-pakket vereenvoudigt het proces van het ophalen van SAS-tokens, Microsoft Entra-tokens, verbindingsreeks s en geheimen die zijn opgeslagen in een gekoppelde service of vanuit een Azure Key Vault.

Microsoft Entra Passthrough maakt gebruik van machtigingen die aan u zijn toegewezen als gebruiker in Microsoft Entra ID, in plaats van machtigingen die zijn toegewezen aan Synapse of een afzonderlijke service-principal. Als u bijvoorbeeld Microsoft Entra passthrough wilt gebruiken voor toegang tot een blob in een opslagaccount, gaat u naar dat opslagaccount en wijst u de rol blobbijdrager aan uzelf toe.

Bij het ophalen van geheimen uit Azure Key Vault wordt u aangeraden een gekoppelde service te maken voor uw Azure Key Vault. Zorg ervoor dat de MSI (beheerde service-identiteit) van de Synapse-werkruimte, Secret Get-bevoegdheden heeft voor uw Azure Key Vault. Synapse verifieert zich bij Azure Key Vault met behulp van de MSI van de Synapse-werkruimte. Als u rechtstreeks verbinding maakt met Azure Key Vault zonder een gekoppelde service, verifieert u zich met uw Microsoft Entra-referenties van uw gebruiker.

Zie gekoppelde services voor meer informatie.

Gebruik

mssparkutils help voor tokens en geheimen

Deze functie geeft de Help-documentatie weer voor het beheer van geheimen en tokens in Synapse.

mssparkutils.credentials.help()

mssparkutils.credentials.help()

Console.WriteLine(TokenLibrary.help());

Resultaat ophalen:

 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

Toegang tot Azure Data Lake Storage Gen2

Primaire opslag van ADLS Gen2

Voor toegang tot bestanden vanuit de primaire Azure Data Lake Storage wordt standaard microsoft Entra-passthrough gebruikt voor verificatie en is het expliciete gebruik van de mssparkutils niet vereist. De identiteit die wordt gebruikt in de passthrough-verificatie verschilt op basis van een paar factoren. Interactieve notebooks worden standaard uitgevoerd met behulp van de identiteit van de gebruiker, maar deze kan worden gewijzigd in de beheerde service-identiteit (MSI) van de werkruimte. Batchtaken en niet-interactieve uitvoeringen van het notebook maken gebruik van de MSI van de werkruimte.

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

Opslag met gekoppelde services van ADLS Gen2

Azure Synapse Analytics biedt een geïntegreerde ervaring voor gekoppelde services bij het maken van verbinding met Azure Data Lake Storage Gen2. Gekoppelde services kunnen worden geconfigureerd voor verificatie met behulp van een accountsleutel, service-principal, beheerde identiteit of referenties.

Wanneer de verificatiemethode met de gekoppelde service is ingesteld op accountsleutel, wordt de gekoppelde service geverifieerd met behulp van de opgegeven sleutel voor het opslagaccount, wordt een SAS-sleutel aangevraagd en wordt deze automatisch toegepast op de opslagaanvraag met de LinkedServiceBasedSASProvider-provider.

Met Synapse kunnen gebruikers de gekoppelde service instellen voor een bepaald opslagaccount. Hierdoor kunnen gegevens uit meerdere opslagaccounts in één Spark-toepassing/query worden gelezen/geschreven. Zodra we spark.storage.synapse hebben ingesteld .{ source_full_storage_account_name}.linkedServiceName voor elk opslagaccount dat wordt gebruikt, bepaalt Synapse welke gekoppelde service moet worden gebruikt voor een bepaalde lees-/schrijfbewerking. Als onze Spark-taak echter alleen te maken heeft met één opslagaccount, kunnen we gewoon de naam van het opslagaccount weglaten en spark.storage.synapse.linkedServiceName gebruiken 

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

Wanneer de verificatiemethode met de gekoppelde service is ingesteld op beheerde identiteit of service-principal, maakt de gekoppelde service gebruik van het token van de beheerde identiteit of van de service-principal met de LinkedServiceBasedTokenProvider-provider.

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 Gen2-opslag zonder gekoppelde services

Verbinding maken rechtstreeks naar ADLS Gen2-opslag met behulp van een SAS-sleutel. Gebruik de ConfBasedSASProvider SAS-sleutel en geef deze op voor de spark.storage.synapse.sas configuratie-instelling. SAS-tokens kunnen worden ingesteld op containerniveau, accountniveau of globaal. We raden u niet aan SAS-sleutels op globaal niveau in te stellen, omdat de taak niet meer dan één opslagaccount kan lezen/schrijven.

SAS-configuratie per opslagcontainer

%%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-configuratie per opslagaccount

%%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-configuratie van alle opslagaccounts

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

Opslag van ADLS Gen2 met Azure Key Vault

Maak verbinding met ADLS Gen2-opslag met behulp van een SAS-token dat is opgeslagen in een Azure Key Vault-geheim.

%%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 voor andere gekoppelde services

Om verbinding te maken met andere gekoppelde services, kunt u de tokenbibliotheek rechtstreeks aanroepen.

getConnectionString()

Om de verbindingsreeks op te halen, gebruikt u de functie getConnectionString en geeft u de naam van de gekoppelde service door.

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

De getPropertiesAll is een helperfunctie die beschikbaar is in Scala en Python om alle eigenschappen van een gekoppelde service op te halen

%%pyspark
import json
# retrieve connectionstring from mssparkutils

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

De uitvoer ziet er als volgt uit

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

GetSecret()

Als u een geheim wilt ophalen dat is opgeslagen in Azure Key Vault, kunt u het beste een gekoppelde service naar Azure Key Vault maken in de Synapse-werkruimte. De beheerde service-identiteit van de Synapse-werkruimte moet de machtiging GET Secret worden verleend voor Azure Key Vault. De gekoppelde service maakt gebruik van de beheerde service-identiteit om verbinding te maken met de Azure Key Vault-service om het geheim op te halen. Anders gebruikt u de Microsoft Entra-referenties van de gebruiker om rechtstreeks verbinding te maken met Azure Key Vault. In dit geval moet de gebruiker de GET Secret-machtigingen in Azure Key Vault worden verleend.

Geef in overheidsclouds de volledig gekwalificeerde domeinnaam van de sleutelkluis op.

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

Gebruik de functie mssparkutils.credentials.getSecret() om een geheim op te halen uit Azure Key Vault.


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

Gekoppelde serviceverbindingen die worden ondersteund vanuit de Spark-runtime

Hoewel Azure Synapse Analytics verschillende gekoppelde serviceverbindingen ondersteunt (vanuit pijplijnen en andere Azure-producten), worden ze niet allemaal ondersteund vanuit de Spark-runtime. Hier volgt de lijst met ondersteunde gekoppelde services:

  • Azure Blob-opslag
  • Azure AI-services
  • 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 (toegewezen en serverloos)
  • Azure Storage

mssparkutils.credentials.getToken()

Wanneer u een OAuth Bearer-token nodig hebt om rechtstreeks toegang te krijgen tot services, kunt u de getToken methode gebruiken. De volgende resources worden ondersteund:

Servicenaam Letterlijke tekenreeks die moet worden gebruikt in API-aanroep
Azure Storage Storage
Azure Key Vault Vault
Azure-beheer AzureManagement
Azure SQL Data Warehouse (toegewezen en serverloos) 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

Niet-ondersteunde toegang tot gekoppelde services vanuit de Spark-runtime

De volgende methoden voor toegang tot de gekoppelde services worden niet ondersteund vanuit de Spark-runtime:

  • Argumenten doorgeven aan geparameteriseerde gekoppelde service
  • Verbinding maken met door de gebruiker toegewezen beheerde identiteiten (UAMI)
  • Door het systeem toegewezen beheerde identiteiten worden niet ondersteund in Keyvault-resource
  • Voor Azure Cosmos DB-verbindingen wordt alleen toegang op basis van sleutels ondersteund. Toegang op basis van tokens wordt niet ondersteund.

Tijdens het uitvoeren van een notebook of een Spark-taak kunnen aanvragen om een token/geheim op te halen met behulp van een gekoppelde service mislukken met een foutbericht dat 'BadRequest' aangeeft. Dit wordt vaak veroorzaakt door een configuratieprobleem met de gekoppelde service. Als u dit foutbericht ziet, controleert u de configuratie van uw gekoppelde service. Als u vragen hebt, neemt u contact op met De ondersteuning van Microsoft Azure via De Azure-portal.

Gerelateerde inhoud