NotebookUtils credentials utilities for Fabric

Voit käyttää tunnistetietotyökaluja saadaksesi käyttöoikeustokeneita ja hallitaksesi salaisuuksia Azure Key Vaultissa. Moduuli notebookutils.credentials integroituu Microsoft Entra ID:hen tokenien hankintaan ja Azure Key Vaultiin salaisuuksien hallintaan, joten voit yhdistää Azure-resursseihin turvallisesti ilman, että tunnistetietoja tarvitsee paljastaa koodissa.

Tunnistetiedot ovat saatavilla Python-, PySpark-, Scala- ja R-muistikirjoissa. Tämän sivun esimerkeissä käytetään Pythonia ensisijaisena kielenä, ja Scala- ja R-vastineet on esitetty siellä, missä julkinen API niitä tukee.

Rajoitukset ja turvallisuus

Ennen kuin käytät tunnistetietotyökaluja, ole tietoinen näistä rajoituksista:

• Tokenien vanheneminen – Tokenit vanhenevat tietyn ajan kuluttua. Pitkäaikaisissa operaatioissa toteuta virkistyslogiikka pyytääksesi uutta tokenia ennen vanhenemista.
• Palvelupään laajuuden rajoitukset – Kun niitä ajetaan palveluperiaatteen alla, yleisön pbi tokeneilla on rajattu laajuus verrattuna käyttäjäidentiteettiin.
• MSAL koko laajuudelle – Jos tarvitset koko Fabric-palvelun laajuuden palvelupään alla, käytä MSAL-tunnistautumista sen sijaan, että käyttäisit getToken.
• Salainen sensurointi – Muistikirjan tulokset sensuroivat automaattisesti salaiset arvot estääkseen vahingossa paljastumisen.
• Key Vaultin käyttöoikeudet – Sinulla täytyy olla asianmukaiset oikeudet (Get lukemiseen, Set kirjoittamiseen) Azure Key Vaultissa, jotta voit käyttää tai tallentaa salaisuuksia.
• Yleisön muutokset – Token-yleisön laajuudet voivat kehittyä ajan myötä. Tarkista nykyiset scope-alueet dokumentaatiosta.

Saat yleiskatsauksen käytettävissä olevista menetelmistä suorittamalla seuraavan komennon:

notebookutils.credentials.help()

notebookutils.credentials.help()

notebookutils.credentials.help()

Seuraavassa taulukossa on lueteltu saatavilla olevat tunnistekoodimenetelmät:

Hanki tunnus

getToken palauttaa Microsoft Entra -tokenin tietylle yleisölle. Seuraava taulukko näyttää tällä hetkellä saatavilla olevat yleisön avaimet:

Saat tunnuksen suorittamalla seuraavan komennon:

notebookutils.credentials.getToken('audience Key')

notebookutils.credentials.getToken("audience Key")

notebookutils.credentials.getToken("audience Key")

Tokenin käytön esimerkkejä

Voit käyttää palautettua tokenia tunnistautuaksesi eri Azure-palveluihin.

Azure-tallennus

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

Power BI- ja Fabric REST -rajapinnat

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

Käytä tokeneita Azure SDK:n kanssa

Fabric-muistikirjat eivät tue DefaultAzureCredential tätä suoraan. Voit käyttää mukautettua tunnisteluokkaa kiertotienä NotebookUtils-tokenien välittämiseen Azure SDK -asiakkaille.

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

Huomioitavia seikkoja

• Token-tähtäimet, joiden pbi kohderyhmä voi muuttua ajan myötä.

• Kun kutsut notebookutils.credentials.getToken("pbi"), palautetulla tokenilla on rajallinen ulottuvuus, jos notebook toimii palvelupään alla. Tokenilla ei ole koko Fabric-palvelun laajuutta. Jos muistikirja toimii käyttäjätunnuksella, tokenilla on edelleen koko Fabric-palvelun laajuus, mutta tämä voi muuttua tietoturvaparannusten myötä. Varmistaaksesi, että tokenilla on koko Fabric-palvelun laajuus, käytä MSAL-tunnistautumista API:n sijaan notebookutils.credentials.getToken . Lisätietoja on artikkelissa Todentaminen Microsoft Entra ID:llä.

• Seuraavat scopet ovat käytettävissä, kun kutsut notebookutils.credentials.getToken audience-avaimella pbi palvelun päähenkilötunnuksen alla:

  • Lakehouse.ReadWrite.All – Lue ja kirjoita pääsy Lakehouse-esineisiin
  • MLExperiment.ReadWrite.All – Luku- ja kirjoitusoikeudet koneoppimiskokeiden kohteisiin
  • MLModel.ReadWrite.All – Luku- ja kirjoitusoikeudet koneoppimismallin kohteisiin
  • Notebook.ReadWrite.All – Luku- ja kirjoitusoikeudet muistikirjan kohteisiin
  • SparkJobDefinition.ReadWrite.All – Lue ja kirjoita pääsy Sparkin työmäärittelykohteisiin
  • Workspace.ReadWrite.All – Luku- ja kirjoitusoikeudet Workspace-kohteisiin
  • Dataset.ReadWrite.All – Tietoaineiston kohteiden luku- ja kirjoitusoikeudet

Hanki salaisuus

getSecret palauttaa Azure Key Vaultin salaisuuden annetulle Azure Key Vaultin päätepisteelle ja salaiselle nimelle. Puhelu käyttää nykyisiä käyttäjätunnuksiasi todennukseen Key Vaultia vastaan.

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

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

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

Voit hakea useita salaisuuksia rakentaaksesi yhteysmerkkijonoja tai konfiguroidaksesi palveluita:

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}"

Käytä täysin pätevää Key Vault -URL-osoitetta muodossa https://<vault-name>.vault.azure.net/. Sinulla on oltava asianmukaiset oikeudet päästäksesi avainholviin ja yksittäisiin salaisuuksiin.

Tietoturvan parhaat käytännöt

Noudata näitä suosituksia, kun työskentelet Fabric-muistikirjojen kanssa:

• Tallenna kaikki arkaluontoiset arvot Azure Key Vaultiin. Älä koskaan upota tunnuksia, yhteysmerkkijonoja tai API-avaimia suoraan muistikirjan koodiin.
• Älä kirjaa salaisia arvoja. Luota automaattiseen salaiseen sensurointiin muistikirjan tulosteissa. Vältä salaisuuksien kirjoittamista tiedostoihin tai niiden välittämistä muistikirjan parametreina.
• Käytä oikeaa yleisöavainta. Yhdistä yleisöavain kohde-Azure-resurssiin, jotta tokenilla on vain tarvitsemansa oikeudet.
• Ymmärrä identiteettikonteksti. Tiedä, toimiiko muistikirjasi käyttäjätunnuksella vai palvelupäähenkilöllä, sillä käytettävissä olevat token-laajuudet voivat vaihdella. Testaa todennus sekä interaktiivisissa että putkikonteksteissa.
• Hoida tokenien vanheneminen. Tokenit vanhenevat. Pitkäaikaisissa operaatioissa toteuta virkistyslogiikka pyytääksesi uutta tunnistetta ennen kuin nykyinen vanhenee.
• Rajoita pääsyä Key Vaultiin. Myönnä vain vähimmäisvaaditut oikeudet Key Vaultillesi. Auditoi salainen pääsy Azure Key Vaultin diagnostiikkalokien kautta.
• Käytä hallittuja identiteettejä aina kun mahdollista. Hallitut identiteetit vähentävät tarvetta hallita tunnistetietoja manuaalisesti ja tarjoavat turvallisemman tunnistautumisprosessin.

Laita salaisuus

putSecret tallentaa salaisuuden määritettyyn Azure Key Vaultiin. Jos salaisuus on jo olemassa, arvo päivitetään.

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

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

Sinulla täytyy olla asianmukaiset oikeudet (Aseta käyttöoikeus) Azure Key Vaultissa salaisuuksien kirjoittamiseen.

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

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

Validoi token

Käytä isValidToken sitä tarkistamaan, onko token voimassa eikä vanhentunut ennen kuin kutsut API:n sillä.

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

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

Liittyvä sisältö

• NotebookUtils (entinen MSSparkUtils) Fabricille