Todennusohjeet Microsoft Fabric Extensibility Toolkitille

Tässä artikkelissa annetaan ohjeita siitä, miten todennuksen kanssa työskennellä Microsoft Fabricin laajennettavuustyökalupakin työkuormia rakennettaessa. Se sisältää tietoa tokenien käytöstä, suostumuksista ja eri palveluiden käytöstä frontend-sovelluksestasi.

Ennen kuin aloitat, varmista, että tunnet Authenticing-yleiskatsauksen käsitteet.

Frontend-pelkkä todennusmalli

Extensibility Toolkit käyttää vain frontend-arkkitehtuuria, joka yksinkertaistaa tunnistautumista verrattuna perinteisiin työkuormiin:

  • Suorat API-kutsut: Frontend kutsuu suoraan Fabric-rajapintoja, Azure-palveluita ja ulkoisia sovelluksia
  • Tokenin uudelleenkäyttö: Yhtä tokenia voidaan käyttää todennukseen useiden Entra-turvattujen palveluiden osalta
  • Yksinkertaistettu suostumus: Suostumuksen hallinta hoidetaan alustan toimesta automaattisella kehotuksella

Microsoft Entra application configuration

Avaa API-välilehti

Määritä laajuudet työkuormasovelluksellesi:

  • Fabric-integraation laajuudet: Esivaltuuta Microsoft Power BI application ID:llä 871c010f-5e61-4fb1-83ac-98610a7e9110
  • Mukautetut API-laajuudet: Lisää laajuudet kaikille mukautetuille API-rajapinnoille, joita työkuormasi paljastaa
  • Yksityiskohtaiset käyttöoikeudet: Käytä eri laajuuksia luku- ja kirjoitusoperaatioissa

Esimerkiksi, jos työkuormasi paljastaa datarajapinnat:

  • Lisää data.read laajuutta lukuoperaatioille
  • Lisää data.write kirjoitusoperaatioiden laajuutta
  • Validoi sopivat laajuudet API-käsittelijöissäsi

API-oikeudet -välilehti

Määritä käyttöoikeudet ulkoisille palveluille, joihin työkuormasi tarvitsee pääsyä:

  • Vaaditaan: Fabric.Extend Power BI Service -palvelussa (pakollinen Fabric-integraatiossa)
  • Azure-palvelut: Lisää scope-alueita Azure-palveluille kuten https://storage.azure.com/user_impersonation
  • Mukautetut sovellukset: Lisää scope-alueita omille Entra-suojatuille sovelluksillesi
  • Kolmannen osapuolen palvelut: Sisällytä kaikki ulkoiset palvelut, jotka tukevat Entra-tunnistautumista

Tokenien käyttötavat

Tokenien käyttö useisiin palveluihin

Extensibility Toolkitin kautta hankittua frontend-tokenia voidaan käyttää autentikointiin seuraavia vastaan:

Fabric-rajapinnat

// Token automatically includes required Fabric scopes
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Azure services

// Same token works for Azure services
const response = await fetch('https://management.azure.com/subscriptions', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Mukautetut sovellukset

// Token works for your own Entra-secured applications
const response = await fetch('https://myapp.contoso.com/api/data', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Laajuuden hallinta

Extensibility Toolkit abstraktoi laajuuden hallinnan yleisille skenaarioille:

  • Fabric-asiakaskirjastot: Sisällytä automaattisesti vaaditut Fabric-laajuudet
  • Azure client libraries: Handle Azure service scopes transparently
  • Mukautetut tähtäimet: Määritä tarvittaessa lisätähtäimiä

Työskentely suostumuksilla

Alkuperäinen tokenien hankinta

Aloita hankkimalla token tunnistautumiskontekstin luomiseksi:

const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

Tämä puhelu voi johtaa:

  • Suostumuskehote: Jos käyttäjä ei ole suostunut hakemukseesi
  • Hiljainen hankinta: Jos suostumus on aiemmin myönnetty

Lisäpalveluiden käsittely

Kun työkuormasi tarvitsee lisäpalveluita, määritä vaaditut laajuudet:

try {
  // Request token with specific scopes for Azure Storage
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  // Use token to access Azure Storage
  const response = await fetch('https://mystorageaccount.blob.core.windows.net/', {
    headers: { 'Authorization': `Bearer ${token.token}` }
  });
} catch (error) {
  // Handle authentication or authorization errors
  console.error('Access failed:', error.message);
}

Esimerkkiskenaariot

Skenaario 1: Pääsy Fabric- ja Azure-palveluihin

Työkuormasi täytyy:

  • Listaa Fabric-työtilat
  • Lue Azure Storagesta
  • Write to Azure Key Vault

Toteutus:

  1. Määritä API-oikeudet vaadittaville palveluille
  2. Hanki alkuperäinen token
  3. Käytä tokenia kaikkiin palvelukutsuihin
  4. Käsittele suostumuspyyntöjä tarpeen mukaan

Skenaario 2: Mukautettu sovellusintegraatio

Työkuormasi integroituu omaan taustapalveluosi:

  1. Konfiguroi taustajärjestelmäsi: Varmista, että se hyväksyy Entra-tokenit
  2. Lisää API-oikeudet: Sisällytä backendisi laajuudet työkuormasovellukseen
  3. Käytä standarditunnistautumista: Sama token-malli toimii myös omiin palveluihisi

Skenaario 3: Kolmannen osapuolen palveluintegraatio

Integraatio ulkoisiin Entra-yhteensopiviin palveluihin:

  1. Palvelun rekisteröinti: Rekisteröi työkuormasi kolmannen osapuolen palveluun
  2. Scope-konfiguraatio: Lisää palvelun scope-alueet API-oikeuksiisi
  3. Tokenin käyttö: Käytä samaa todennusmallia ulkoisille palveluille

Virheenkäsittely ja vianmääritys

Yleiset todennusvirheet

  • Suostumus vaaditaan: Käyttäjä ei ole myöntänyt lupaa tiettyyn laajuuteen
  • Ehdollinen pääsy: Lisätodennusvaatimukset (esim. MFA)
  • Tokenin vanheneminen: Token on vanhentunut ja tarvitsee päivitystä
  • Virheellinen scope: Pyydetty scope ei ole konfiguroitu tai saatavilla

Virheiden käsittelymallit

async function handleAuthenticatedRequest(url: string, requiredScopes: string[] = []) {
  try {
    const token = await workloadClient.auth.acquireFrontendAccessToken({ 
      scopes: requiredScopes 
    });
    return await makeRequest(url, token);
  } catch (error) {
    if (error.code === 'consent_required') {
      // User needs to grant consent for the requested scopes
      console.error('Consent required for scopes:', requiredScopes);
    }
    throw error;
  }
}

Redirect URI-käsittely

Laajennettavuustyökalupakki sisältää sisäänrakennetun uudelleenohjaus-URI-käsittelyn autentikointisuostumusponnahdusikkunoita varten. Tämä toteutetaan päätiedostossa index.ts ja hoitaa suostumusuudelleenohjaukset automaattisesti.

Työkalupakki käsittelee:

  • Automaattinen ikkunan sulkeminen: Suostumusponnahdusikkunat sulkeutuvat automaattisesti käyttäjän vuorovaikutuksen jälkeen
  • Virheiden käsittely: Tietyt virhekoodit havaitaan ja käsitellään asianmukaisesti
  • Virhenäyttö: Epäonnistuneet suostumusyritykset näyttävät käyttäjäystävällisiä virheilmoituksia

Nykyinen toteutus työkalupakissa:

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle errors
  if (url?.hash?.includes("error")) {
    if (url.hash.includes("AADSTS650052")) {
      // Handle missing service principal error
      printFormattedAADErrorMessage(url?.hash);
    } else if (url.hash.includes("AADSTS65004")) {
      // Handle user declined consent error
      printFormattedAADErrorMessage(url?.hash);
    } else {
      window.close();
    }
  } else {
    // Close window on successful consent
    window.close();
  }
}

Note

Uudelleenohjaus-URI-käsittely sisällytetään automaattisesti laajennettavuustyökalujen mallipohjaan. Sinun ei tarvitse toteuttaa tätä itse, ellei halua räätälöidä virheenkäsittelyä.

Parhaat käytännöt

Tokenien hallinta

  • Välimuistitokenit: Käytä tokeneita uudelleen, kunnes ne vanhenevat
  • Handle update -toiminto: Toteuta automaattinen tokenin päivityslogiikka
  • Turvallinen tallennus: Tallenna tokenit turvallisesti selaimen muistiin
  • Vähimmäisoikeudet: Pyydä vain niitä scopeja, joita oikeasti tarvitset
  • Progressiivinen suostumus: Pyydä lisäoikeuksia ominaisuuksien käytön myötä
  • Selvä viestintä: Selitä käyttäjille, miksi käyttöoikeudet ovat tarpeen

Virheenkäsittely

  • Sulava heikkeneminen: Tarjoa varatoimintoja aina kun mahdollista
  • Käyttäjäpalaute: Viesti selkeästi todennusvaatimuksista
  • Uusintalogiikka: Toteuta sopivat uudelleenyrittämismekanismit tilapäisille epäonnistumisille

Liittyvä sisältö

  • Last updated on