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

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

Вы можете использовать утилиты учетных данных в блокнотах Python и Fabric Spark. В ноутбуках Fabric Spark можно использовать PySpark, Scala или R. Доступность методов зависит от времени выполнения и API блокнота. Например, putSecret работает только в тетрадях на Python, которые используют среду выполнения Python. Ноутбуки Spark этого не поддерживают, даже когда запускают код на Python с PySpark. Ноутбуки Spark, использующие Scala или R, тоже этого не поддерживают.

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

Это важно

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

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

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

  • Срок действия маркера — маркеры истекают через определенный период. Для длительных операций реализуйте логику обновления, чтобы запросить новый маркер до истечения срока действия.
  • Ограничения области учетной записи службы – При выполнении под учетной записью службы, токены для pbi аудитории имеют ограниченные права доступа по сравнению с удостоверением пользователя.
  • MSAL для полного охвата – Если вам необходим полный охват службы Fabric с использованием служебного принципала, используйте проверку подлинности MSAL вместо getToken.
  • Секретная редакция — вывод блокнота пытается скрыть исходное секретное значение при прямой печати или отображении кода. Эта мера защиты, реализованная по принципу best effort, снижает риск случайного разглашения информации, в том числе при демонстрации экрана. Это не граница безопасности. После извлечения авторизованный код записной книжки получает секрет в открытом виде и может обрабатывать, преобразовывать или раскрывать сам секрет либо содержимое, производное от него.
  • Права доступа к 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. Этот метод работает только в ноутбуках, использующих среду выполнения Python. Ноутбуки Spark этого не поддерживают, даже когда запускают код на Python с PySpark. Ноутбуки Spark с Scala или R тоже этого не поддерживают.
isValidToken isValidToken(token: String): Boolean Проверяет, является ли заданный маркер допустимым и не истек. Этот метод недоступен в общедоступном API Scala.

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

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

Ключ доступа к аудитории Ресурс Сценарий использования
storage служба хранилища Azure Доступ к 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_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. Он работает только в ноутбуках, использующих среду выполнения Python.

Это важно

Блокноты Spark не поддерживают putSecret, даже когда они запускают код на Python с PySpark. Ноутбуки Spark с Scala или R тоже этого не поддерживают. Используйте Python-блокнот, который использует Python runtime.

# Run only in a notebook that uses the Python runtime.
notebookutils.credentials.putSecret(
    'https://<name>.vault.azure.net/',
    'secret name',
    'secret value'
)

Для записи секретов нужны соответствующие права (Set permission) на Azure Key Vault. Запустите следующий пример только в блокноте, использующем среду выполнения Python. Не запускайте это в записной книжке Fabric Spark.

# Python runtime only. Fabric Spark notebooks don't support putSecret.
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')

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

  • Последнее обновление: