Waarom ADF-toegangsfouten gemakkelijk verkeerd gediagnosticeerd kunnen worden
Azure Data Factory-machtigingsfouten hebben een specifieke eigenschap die het debuggen ervan frustrerend maakt: de knop 'Verbinding testen' in de portal kan een succesmelding geven, terwijl de daadwerkelijke pipelineuitvoering mislukt met een 'AuthorizationPermissionMismatch' of 'Forbidden 403'. Dit is geen bug, de verbindingstest en de pipelineuitvoering gebruiken verschillende beveiligingscontexten, verschillende integratieruntimes en soms verschillende identiteiten. Wat in de ene context werkt, kan in de andere mislukken.
Dit foutpatroon doet zich voor in ADLS Gen2, SharePoint Online en Microsoft Fabric Lakehouses. De foutmelding verandert, maar de onderliggende oorzaak is bijna altijd hetzelfde: de identiteit die de pipeline daadwerkelijk gebruikt tijdens de uitvoering mist een specifieke RBAC-rol of -scope en de testinfrastructuur maskeerde dit hiaat.
Het begrijpen welke identiteit de pipeline gebruikt, een door het systeem toegewezen beheerde identiteit, een door de gebruiker toegewezen beheerde identiteit of een serviceprincipal, is het startpunt voor elk onderzoek naar machtigingsproblemen. Als u vanaf het begin de verkeerde identiteit diagnosticeert, zal elke poging tot herstel mislukken.
Autorisatie/Toestemmingsfout op ADLS Gen2
De meest voorkomende ADF-machtigingsfout op ADLS Gen2-opslag is AuthorizationPermissionMismatch. De pipeline mislukt met deze foutcode wanneer de ADF Managed Identity de rol Contributor heeft op het opslagaccount, maar geen dataplane-rol.
Dit is een vaak verkeerd begrepen onderscheid in Azure RBAC. De rol Contributor op een opslagaccount verleent toegang tot het beheervlak: de mogelijkheid om het account te configureren, sleutels te beheren en eigenschappen in te stellen. Het verleent geen toegang tot het lezen of schrijven van blobgegevens. Daarvoor is de rol Storage Blob Data Contributor (voor lezen/schrijven) of Storage Blob Data Reader (alleen lezen) vereist, toegewezen op container- of opslagaccountniveau.
De juiste rol toewijzen via Azure CLI:
az role assignment create --assignee
Bestaande toewijzingen controleren: az role assignment list --assignee
Na het toewijzen van de rol, wacht u een paar minuten totdat de wijzigingen zijn doorgevoerd voordat u opnieuw test. RBAC-wijzigingen in Azure worden uiteindelijk consistent en een test die direct na de toewijzing wordt uitgevoerd, kan nog steeds mislukken.
Foutmelding 401 op SharePoint Online: onjuiste OAuth-doelgroep
ADF pipelines die SharePoint Online of de Microsoft Graph API aanroepen, mislukken met een 401-fout, zelfs als het bearer-token geldig is. Het token is geldig – het is correct uitgegeven – maar het is uitgegeven voor de verkeerde doelgroep. SharePoint Online vereist een token dat is gekoppeld aan het tenantspecifieke SharePoint-eindpunt, niet aan het algemene Microsoft Graph-bereik.
De oplossing zit in de app-registratie. De service-principal of beheerde identiteit moet de machtiging https://
Test het token en het bereik rechtstreeks met Postman of de Azure CLI voordat u ADF-configuraties wijzigt. Een verzoek aan de SharePoint REST API met het juiste tenantspecifieke token zou een 200-statuscode moeten retourneren. Als dat het geval is, ligt het probleem bij het tokenbereik dat ADF gebruikt; zo niet, dan moeten de machtigingen voor de app-registratie worden bijgewerkt.
Voor SharePoint-connectoren moet de gekoppelde service rechtstreeks verwijzen naar de URL van de SharePoint-site en het tenantspecifieke bereik gebruiken, niet het globale Graph-eindpunt.
Toegang geweigerd tot een notebook in een Fabric-pipeline.
Fabric-pipeline-notebooks die toegang proberen te krijgen tot een Lakehouse-omgeving, mislukken met een foutmelding 'toegang geweigerd' omdat de pipeline zijn identiteit niet automatisch doorgeeft aan de notebookcontext. Een pipeline wordt uitgevoerd onder de serviceprincipal of beheerde identiteit van de pipeline. Een notebook binnen die pipeline wordt uitgevoerd in een eigen, aparte uitvoeringscontext.
De oplossing is om de serviceprincipal van de pipeline toegang te geven tot de workspace 'Workspacelid' of 'Workspacebijdrager' op de doel-Fabric-workspace die de Lakehouse-omgeving bevat. Alleen-lezen toegang is niet voldoende voor schrijfbewerkingen; de rol moet overeenkomen met de beoogde bewerking.
Dit is een veelvoorkomende bron van verwarring, omdat een notebook dat werkt wanneer het interactief wordt uitgevoerd (als de gebruiker), mislukt wanneer het vanuit een pipeline wordt uitgevoerd (als de serviceprincipal). Het notebook zelf heeft geen probleem. De identiteit die het uitvoert, beschikt niet over de vereiste Lakehouse-rechten.
Voor Fabric-taken voor het kopiëren van gegevens die af en toe mislukken tijdens het uploaden naar Lakehouse, is de oorzaak vaak dezelfde: het token van de serviceprincipal verloopt of verliest de context halverwege de uitvoering. Door het lidmaatschap van de workspace voor de pipeline-identiteit te controleren en ervoor te zorgen dat deze een permanente, niet-verlopende roltoewijzing heeft, worden de meeste incidentele authenticatiefouten in dit patroon opgelost.
Opslagfirewall blokkeert de integratieruntime.
Wanneer de openbare netwerktoegang voor ADLS Gen2 is uitgeschakeld en de ADF pipeline gebruikmaakt van de AutoResolveIntegrationRuntime (de gedeelde Azure IR), mislukt de pipeline omdat het uitgaande IP-adres van de Azure IR niet in de lijst met toegestane IP-adressen van de opslagfirewall staat.
De AutoResolveIntegrationRuntime gebruikt dynamische IP-bereiken die rouleren. Het toevoegen van een uitzondering voor statische IP-adressen aan de opslagfirewall is voor deze runtime niet haalbaar. De juiste oplossing is een Managed Virtual Network Integration Runtime met een privé-eindpunt naar het opslagaccount.
In ADF Studio: Instellingen > Managed Virtual Network > Managed IR maken > voeg een privé-eindpunt toe voor de Azure Data Lake Storage Gen2-resource. Nadat het privé-eindpunt aan de opslagzijde is goedgekeurd, gebruikt de pipeline het privé-netwerkpad en omzeilt de firewall volledig.
Het overslaan van deze stap is de meest voorkomende reden waarom een pipeline werkt in de ontwikkelomgeving (waar opslag vaak openbaar toegankelijk is) maar mislukt in de productieomgeving (waar opslag door de firewall wordt beperkt). De verbindingstest in het portaal kan een positief resultaat geven als deze vanuit een andere netwerkcontext wordt uitgevoerd, waardoor het probleem vóór de eerste productierun wordt gemaskeerd.
ADF heeft twee identiteiten, controleer welke de pipeline daadwerkelijk gebruikt.
ADF-resources hebben twee verschillende identiteitstypen die onafhankelijk van elkaar kunnen worden geconfigureerd: een door het systeem toegewezen beheerde identiteit, die automatisch wordt aangemaakt met de factory en een of meer door de gebruiker toegewezen beheerde identiteiten die expliciet worden gekoppeld. Een gekoppelde service kan naar beide verwijzen. Als de gekoppelde service een door de gebruiker toegewezen beheerde identiteit specificeert, gebruikt de pipeline die identiteit – niet de door het systeem toegewezen identiteit.
Bij het oplossen van problemen is de eerste stap om te achterhalen welke identiteit de falende gekoppelde service gebruikt. Open de definitie van de gekoppelde service in ADF Studio en bekijk het authenticatiegedeelte. Kopieer de object-ID of client-ID en gebruik vervolgens az role assignment list --assignee om te controleren welke RBAC-rollen die specifieke identiteit heeft.
Een veelgemaakte fout is het toewijzen van de juiste rol aan de door het systeem toegewezen beheerde identiteit, terwijl de gekoppelde service een door de gebruiker toegewezen identiteit gebruikt of andersom. De toewijzing is op het juiste bereik, maar aan de verkeerde identiteit, waardoor de pipeline mislukt en de roltoewijzing correct lijkt wanneer deze wordt gecontroleerd met de verkeerde identiteit.
Controleer ook of de integratieruntime die in de testverbinding wordt gebruikt, overeenkomt met de runtime die in de pipelineactiviteit is geconfigureerd. AutoResolveIntegrationRuntime en een beheerde virtuele netwerk-IR gebruiken verschillende netwerkpaden en lossen in sommige configuraties referenties op een andere manier op.
Bijdrager aan Data Factory: wat het wel en niet biedt.
Een serviceprincipal die ADF-resources beheert, pipelineen maken, gekoppelde services configureren, datasets implementeren, heeft minimaal de Data Factory Contributor-rol nodig op resourcegroepniveau, niet alleen op de factory zelf.
Toegang op factoryniveau maakt het mogelijk om resources binnen die factory te beheren. Toegang op resourcegroepniveau is vereist om resources te maken of te gebruiken die zich op het niveau van de resourcegroep bevinden (Key Vault-referenties, opslagaccounts, integratieruntimes in sommige configuraties). Dit onderscheid is de oorzaak van fouten waarbij een serviceprincipal bestaande pipelineen kan bekijken en bewerken, maar geen nieuwe gekoppelde services kan maken of naar nieuwe geheimen kan verwijzen.
Voor CI/CD-pipelineen die ADF-resources implementeren, heeft de serviceprincipal die voor de implementatie wordt gebruikt de Contributor-rol nodig op resourcegroepniveau, plus de Key Vault Secrets User-rol op elke Key Vault waarnaar wordt verwezen door gekoppelde services. Een te beperkte scope verstoort implementaties; een te brede scope creëert onnodige beveiligingsrisico's. De minimaal vereiste rolcombinatie voor ADF CI/CD-implementatie is: Bijdrager aan de resourcegroep, Key Vault Secrets User op Key Vault en Storage Blob Data Contributor op alle opslagaccounts waarnaar wordt verwezen door Linked Services.
Wanneer MetricSign de foutcode weergeeft voordat u het portaal opent
Fouten in ADF pipelines worden door MetricSign gedetecteerd via het ADF REST API-eindpunt voor uitvoeringen. Wanneer een pipeline mislukt, maakt MetricSign een incident met de naam 'pipeline_failed' aan. Dit incident bevat het exacte foutbericht uit de activiteitsdetails, inclusief 'AuthorizationPermissionMismatch' en de specifieke resource die het verzoek heeft afgewezen.
Zonder deze informatie zou de workflow er als volgt uitzien: wachten tot een stakeholder een ontbrekende rapportupdate opmerkt, inloggen bij Power BI Service, de dataset vinden, de mislukte refresh vinden, ADF openen, naar Monitor navigeren, de juiste pipeline-uitvoering vinden, op de activiteitsdetails klikken en de foutmelding lezen. De foutcode die u binnen dertig seconden had kunnen vertellen dat het een machtigingsprobleem was, verschijnt pas na vijftien minuten.
Het direct weergeven van de foutcode lost het machtigingsprobleem niet op, maar bespaart wel tijd die anders besteed zou worden aan het uitsluiten van andere oorzaken voordat de daadwerkelijke oplossing gevonden kan worden.