Служебные утилиты для работы с учетными данными NotebookUtils для Fabric

Утилиты учетных данных можно использовать для получения токенов доступа и управления секретами в Azure Key Vault. Модуль notebookutils.credentials интегрируется с Microsoft Entra ID для получения токенов и с Azure Key Vault для управления секретами, поэтому вы можете безопасно подключаться к ресурсам Azure без необходимости раскрытия учетных данных в коде.

Служебные программы учетных данных доступны в записных книжках Python, PySpark, Scala и R. Примеры на этой странице используют Python в качестве основного языка, а эквиваленты Scala и R показывают, где общедоступный API поддерживает их.

Это важно

Никогда не встраивайте секретные данные или учетные данные напрямую в код записной книжки. Всегда используйте Azure Key Vault для хранения конфиденциальных значений и их извлечения во время выполнения notebookutils.credentials.getSecret.

Ограничения и безопасность

Прежде чем использовать служебные программы учетных данных, помните об этих ограничениях:

  • Срок действия маркера — маркеры истекают через определенный период. Для длительных операций реализуйте логику обновления, чтобы запросить новый маркер до истечения срока действия.
  • Ограничения области учетной записи службы – При выполнении под учетной записью службы, токены для pbi аудитории имеют ограниченные права доступа по сравнению с удостоверением пользователя.
  • MSAL для полного охвата – Если вам необходим полный охват службы Fabric с использованием служебного принципала, используйте проверку подлинности MSAL вместо getToken.
  • Скрытие секретов — выходные данные блокнота автоматически скрывают секретные значения, чтобы предотвратить непреднамеренное раскрытие.
  • Права доступа к Key Vault — Для доступа к секретам или их хранения необходимо иметь соответствующие права (Получение для чтения, Установка для записи) в Azure Key Vault.
  • Изменения аудитории — сферы применения токенов для аудитории могут изменяться со временем. Проверьте текущие области в документации.

Чтобы получить общие сведения о доступных методах, используйте следующую команду:

notebookutils.credentials.help()

В следующей таблице перечислены доступные методы учетных данных:

Метод Signature Описание
getToken getToken(audience: String): String Возвращает токен Microsoft Entra для указанной аудитории.
getSecret getSecret(akvName: String, secret: String): String Возвращает значение секрета из указанного Хранилища ключей Azure.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Сохраняет секрет в указанном Azure Key Vault. Этот метод недоступен в общедоступном API Scala.
isValidToken isValidToken(token: String): Boolean Проверяет, является ли заданный маркер допустимым и не истек. Этот метод недоступен в общедоступном API Scala.

Получение токена

getToken возвращает токен Microsoft Entra для заданной аудитории. В представленной ниже таблице показаны ключи аудитории, доступные в настоящее время.

Ключ доступа к аудитории Ресурс Сценарий использования
storage Azure Storage Доступ к ADLS 2-го поколения и хранилищу BLOB-объектов
pbi Power BI Вызов REST API Power BI и Fabric
keyvault Azure Key Vault Получение секретов Key Vault
kusto Synapse RTA KQL DB Подключение к обозревателю данных Azure

Выполните следующую команду, чтобы получить маркер:

notebookutils.credentials.getToken('audience Key')

Примеры использования токенов

Вы можете использовать возвращенный маркер для проверки подлинности в различных службах Azure.

Azure Storage

storage_token = notebookutils.credentials.getToken('storage')

REST API Power BI и Fabric

import requests

pbi_token = notebookutils.credentials.getToken('pbi')

headers = {
    'Authorization': f'Bearer {pbi_token}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.powerbi.com/v1.0/myorg/datasets',
    headers=headers
)

if response.status_code == 200:
    datasets = response.json()
    print(f"Found {len(datasets['value'])} datasets")

Azure Data Explorer (Kusto)

kusto_token = notebookutils.credentials.getToken('kusto')

Azure Key Vault

keyvault_token = notebookutils.credentials.getToken('keyvault')

Использование токенов с Azure SDK

Ноутбуки Fabric не поддерживают DefaultAzureCredential напрямую. Можно использовать пользовательский класс учетных данных в качестве обходного решения для передачи маркеров NotebookUtils клиентам пакета SDK Azure.

from azure.core.credentials import AccessToken, TokenCredential
import jwt

class NotebookUtilsCredential(TokenCredential):
    """Custom credential that uses notebookutils tokens for Azure SDK."""

    def __init__(self, audience="storage"):
        self.audience = audience

    def get_token(self, *scopes, claims=None, tenant_id=None, **kwargs):
        token = notebookutils.credentials.getToken(self.audience)

        # Decode token to get expiration time
        token_json = jwt.decode(
            token, algorithms="RS256",
            options={"verify_signature": False}
        )

        return AccessToken(token, int(token_json.get("exp", 0)))

# Example: use with Azure Blob Storage
from azure.storage.blob import BlobServiceClient

account_url = "https://mystorageaccount.blob.core.windows.net"
credential = NotebookUtilsCredential(audience="storage")
blob_client = BlobServiceClient(account_url=account_url, credential=credential)

for container in blob_client.list_containers():
    print(f"Container: {container.name}")

Подсказка

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

Рекомендации

  • Области действия токенов с pbi в качестве аудитории могут меняться с течением времени.

  • При вызове notebookutils.credentials.getToken("pbi") возвращенный токен имеет ограниченную область, если записная книжка выполняется под учетной записью службы. Токен не имеет полного доступа к службе Fabric. Если записная книжка выполняется под идентификацией пользователя, маркер по-прежнему имеет полную область действия сервиса Fabric, но это может измениться по мере улучшения безопасности. Чтобы обеспечить полный доступ токена к службе Fabric, используйте аутентификацию MSAL вместо notebookutils.credentials.getToken API. Дополнительные сведения см. в разделе Аутентификация с помощью идентификатора Microsoft Entra.

  • Следующие области действия доступны при вызове notebookutils.credentials.getToken под идентификатором учетной записи службы с ключом аудитории pbi:

    • Lakehouse.ReadWrite.All — доступ к элементам Lakehouse на чтение и запись
    • MLExperiment.ReadWrite.All — доступ на чтение и запись к элементам эксперимента машинного обучения
    • MLModel.ReadWrite.All — доступ на чтение и запись к элементам модели машинного обучения
    • Notebook.ReadWrite.All — доступ на чтение и запись к элементам записной книжки
    • SparkJobDefinition.ReadWrite.All — доступ на чтение и запись к элементам определения задания Spark
    • Workspace.ReadWrite.All — доступ на чтение и запись к элементам рабочей области
    • Dataset.ReadWrite.All — доступ на чтение и запись к элементам набора данных

Подсказка

Если вам нужен доступ к дополнительным сервисам в Fabric или более широким разрешениям в контексте служебного принципала, используйте MSAL для Python для аутентификации непосредственно с полной областью службы Fabric вместо того, чтобы полагаться getToken("pbi")на него.

Получение секрета

getSecret возвращает секрет Azure Key Vault для заданной конечной точки Azure Key Vault и имени секрета. Вызов использует учетные данные текущего пользователя для проверки подлинности в Key Vault.

notebookutils.credentials.getSecret('https://<name>.vault.azure.net/', 'secret name')

Вы можете получить несколько секретов для создания строк подключения или настройки служб:

vault_url = "https://myvault.vault.azure.net/"

db_host = notebookutils.credentials.getSecret(vault_url, "db-host")
db_user = notebookutils.credentials.getSecret(vault_url, "db-user")
db_password = notebookutils.credentials.getSecret(vault_url, "db-password")

connection_string = f"Server={db_host};User={db_user};Password={db_password}"

Замечание

Выходные данные записной книжки автоматически скрывают конфиденциальные данные для обеспечения безопасности. При печати или отображении полученного секрета выходные данные отображают редактированный заполнитель вместо фактического значения.

Используйте полный URL-адрес Key Vault в формате https://<vault-name>.vault.azure.net/. У вас должны быть соответствующие разрешения для доступа к Key Vault и отдельным секретам.

Лучшие практики обеспечения безопасности

Следуйте этим рекомендациям при работе с учетными данными в записных книжках Fabric:

  • Сохраните все конфиденциальные значения в Azure Key Vault. Никогда не внедряйте учетные данные, строки подключения или ключи API непосредственно в код записной книжки.
  • Не записывайте секретные значения. Полагайтесь на автоматическое скрытие секретной информации в выводах блокнота. Избегайте написания секретов в файлы или передачи их в качестве параметров записной книжки.
  • Используйте правильный ключ аудитории. Сопоставьте идентификатор аудитории с целевым ресурсом Azure, чтобы токен имел только необходимые разрешения.
  • Понять контекст идентификации. Узнайте, запускается ли ваша записная книжка с удостоверением пользователя или сервисным принципалом, так как доступные области действия токенов могут отличаться. Проверяйте аутентификацию как в интерактивном режиме, так и в режиме конвейера.
  • Управление истечением срока действия токена. Срок действия токенов истекает. Для длительных операций реализуйте логику обновления, чтобы запросить новый маркер до истечения срока действия текущего.
  • Ограничение доступа к Key Vault. Предоставьте только минимальные необходимые разрешения в Key Vault. Аудит доступа к секретам с помощью диагностических журналов Azure Key Vault.
  • Используйте управляемые удостоверения, когда это возможно. Управляемые удостоверения снижают потребность в управлении учетными данными вручную и обеспечивают более безопасный поток проверки подлинности.

Введите секрет

putSecret хранит секрет в указанном Azure Key Vault. Если секрет уже существует, значение обновляется.

notebookutils.credentials.putSecret('https://<name>.vault.azure.net/', 'secret name', 'secret value')

Для записи секретов необходимо иметь соответствующие разрешения (задать разрешение) в Azure Key Vault.

vault_url = "https://myvault.vault.azure.net/"

notebookutils.credentials.putSecret(vault_url, "api-key", "my-secret-api-key-value")

Проверить токен

Используйте isValidToken для проверки того, является ли маркер допустимым и не истек до вызова API с ним.

token = notebookutils.credentials.getToken('storage')
is_valid = notebookutils.credentials.isValidToken(token)

if is_valid:
    print("Token is valid")
else:
    print("Token is expired or invalid, requesting a new one")
    token = notebookutils.credentials.getToken('storage')

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

  • Last updated on