mssparkutils를 사용하여 연결된 서비스로 자격 증명을 보호합니다.

아티클
06/27/2024

외부 소스에서 데이터에 액세스하는 것은 일반적인 패턴입니다. 외부 데이터 원본에서 익명 액세스를 허용하지 않는 한, 자격 증명, 비밀 또는 연결 문자열로 연결을 보호해야 할 수도 있습니다.

Azure Synapse Analytics는 리소스 간 인증을 위해 기본적으로 Microsoft Entra 통과를 사용합니다. 다른 자격 증명을 사용하여 리소스에 연결해야 하는 경우 mssparkutils를 직접 사용합니다. mssparkutils 패키지는 연결된 서비스나 Azure Key Vault에 저장된 SAS 토큰, Microsoft Entra 토큰, 연결 문자열 및 비밀을 검색하는 프로세스를 간소화합니다.

Microsoft Entra 통과는 Synapse 또는 별도의 서비스 주체에 할당된 권한이 아닌 Microsoft Entra ID의 사용자로서 사용자에게 할당된 권한을 사용합니다. 예를 들어, Microsoft Entra 통과를 사용하여 스토리지 계정의 Blob에 액세스하려면 해당 스토리지 계정으로 이동하여 자신에게 Blob 기여자 역할을 할당해야 합니다.

Azure Key Vault에서 비밀을 검색하는 경우 Azure Key Vault에 연결된 서비스를 만드는 것이 좋습니다. Synapse 작업 영역 MSI(관리 서비스 ID)에 Azure Key Vault에 대한 비밀 가져오기 권한이 있는지 확인합니다. Synapse는 Synapse 작업 영역 관리형 서비스 ID를 사용하여 Azure Key Vault에 인증합니다. 연결된 서비스 없이 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 Gen2에 액세스

ADLS Gen2 기본 스토리지

기본 Azure Data Lake Storage에서 파일에 액세스하면 기본적으로 인증을 위해 Microsoft Entra 통과가 사용되며 mssparkutils를 명시적으로 사용할 필요가 없습니다. 통과 인증에 사용되는 ID는 몇 가지 요소에 따라 다릅니다. 기본적으로 대화형 Notebooks는 사용자의 ID를 사용하여 실행되지만 작업 영역 MSI(관리되는 서비스 ID)로 변경될 수 있습니다. Notebook의 일괄 작업 및 비대화형 실행은 Workspace 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 Gen2 스토리지

Azure Synapse Analytics는 Azure Data Lake Storage Gen2에 연결할 때 통합 연결된 서비스 환경을 제공합니다. 계정 키, 서비스 주체, 관리 ID또는 자격 증명을 사용하여 인증하도록 연결된 서비스를 구성할 수 있습니다.

연결된 서비스 인증 방법이 계정 키로 설정된 경우 연결된 서비스는 제공된 스토리지 계정 키를 사용하여 인증하고, 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()

연결된 서비스 인증 방법이 관리 ID 또는 서비스 주체로 설정된 경우 연결된 서비스는 LinkedServiceBasedTokenProvider 공급자와 함께 관리 ID 또는 서비스 주체 토큰을 사용합니다.

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 Gen2 스토리지(연결된 서비스 제외)

SAS 키를 사용하여 ADLS Gen2 스토리지에 직접 연결합니다. 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을 직접 사용하도록 구성되면 공급자는 토큰을 캐시하지 않습니다. 이로 인해 안정성 문제가 발생할 수 있습니다. Synapse Spark의 일부인 ClientCredsTokenProvider를 사용하는 것이 좋습니다.

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

SAS 토큰이 포함된 ADLS Gen2 스토리지(Azure Key Vault에서)

Azure Key Vault 비밀에 저장된 SAS 토큰을 사용하여 ADLS Gen2 스토리지에 연결합니다.

%%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에서 저장된 비밀을 검색하려면 Synapse 작업 영역 내에서 Azure Key Vault에 대한 연결된 서비스를 만드는 것이 좋습니다. Synapse 작업 영역 관리 서비스 ID는 Azure Key Vault에 대한 비밀 가져오기 권한을 부여 받아야 합니다. 연결된 서비스는 관리 서비스 ID를 사용하여 Azure Key Vault 서비스에 연결하여 비밀을 검색합니다. 그렇지 않으면 Azure Key Vault에 직접 연결하면 사용자의 Microsoft Entra 자격 증명이 사용됩니다. 이 경우 사용자에게 Azure Key Vault에서 비밀 가져오기 권한이 있어야 합니다.

정부 클라우드에서는 keyvault의 정규화된 도메인 이름을 제공합니다.

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 런타임에서 지원되는 것은 아닙니다. 지원되는 연결된 서비스 목록은 다음과 같습니다.

Azure Blob Storage
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(전용 및 서버리스)
Azure Storage

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(사용자 할당 관리 ID)와의 연결
Notebook/SparkJobDefinition이 관리 ID로 실행될 때 Keyvault 리소스에 전달자 토큰 가져오기
- 또는 액세스 토큰을 가져오는 대신 Keyvault에 연결된 서비스를 만들고 Notebook/일괄 작업에서 비밀을 가져올 수 있습니다.
Azure Cosmos DB 연결의 경우 키 기반 액세스만 지원됩니다. 토큰 기반 액세스는 지원되지 않습니다.

Notebook 또는 Spark 작업을 실행하는 동안 연결된 서비스를 사용하여 토큰/비밀을 가져오려는 요청이 'BadRequest'를 나타내는 오류 메시지와 함께 실패할 수 있습니다. 이는 연결된 서비스의 구성 문제로 인해 발생하는 경우가 많습니다. 이 오류 메시지가 표시되면 연결된 서비스의 구성을 확인하세요. 질문이 있는 경우 Azure Portal에서 Microsoft Azure 지원팀에 문의하세요.

다음을 통해 공유

mssparkutils를 사용하여 연결된 서비스로 자격 증명을 보호합니다.

사용

토큰 및 비밀에 대한 mssparkutils 도움말

Azure Data Lake Storage Gen2에 액세스

ADLS Gen2 기본 스토리지

연결된 서비스가 있는 ADLS Gen2 스토리지

Spark 구성을 통해 인증 설정 지정

ADLS Gen2 스토리지(연결된 서비스 제외)

MSAL을 사용하여 토큰 획득(사용자 지정 앱 자격 증명 사용)

SAS 토큰이 포함된 ADLS Gen2 스토리지(Azure Key Vault에서)

다른 연결된 서비스용 TokenLibrary

getConnectionString()

getPropertiesAll()

GetSecret()

Spark 런타임에서 지원되는 연결된 서비스 연결

mssparkutils.credentials.getToken()

Spark 런타임에서 지원되지 않는 연결된 서비스 액세스

피드백

추가 리소스

다음을 통해 공유

mssparkutils를 사용하여 연결된 서비스로 자격 증명을 보호합니다.

사용

토큰 및 비밀에 대한 mssparkutils 도움말

Azure Data Lake Storage Gen2에 액세스

ADLS Gen2 기본 스토리지

연결된 서비스가 있는 ADLS Gen2 스토리지

Spark 구성을 통해 인증 설정 지정

ADLS Gen2 스토리지(연결된 서비스 제외)

MSAL을 사용하여 토큰 획득(사용자 지정 앱 자격 증명 사용)

SAS 토큰이 포함된 ADLS Gen2 스토리지(Azure Key Vault에서)

다른 연결된 서비스용 TokenLibrary

getConnectionString()

getPropertiesAll()

GetSecret()

Spark 런타임에서 지원되는 연결된 서비스 연결

mssparkutils.credentials.getToken()

Spark 런타임에서 지원되지 않는 연결된 서비스 액세스

관련 콘텐츠

피드백

추가 리소스