ADF-pipelinetoegangsfouten: Oplossingen voor 'Toegang geweigerd', '401' en '403'.

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 pipeline run mislukt met een 'AuthorizationPermissionMismatch' of 'Forbidden 403'. Dit is geen bug — de verbindingstest en de pipeline run gebruiken verschillende beveiligingscontexten, verschillende integratie runtimes 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 maskeert dit hiaat.

Inzicht in welke identiteit de pipeline gebruikt — een door het systeem toegewezen beheerde identiteit, een door de gebruiker toegewezen beheerde identiteit of een service principal — is het startpunt voor elk onderzoek naar machtigingsproblemen. Als je vanaf het begin de verkeerde identiteit diagnosticeert, zal elke poging tot herstel mislukken.

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 --role "Storage Blob Data Contributor" --scope /subscriptions//resourceGroups//providers/Microsoft.Storage/storageAccounts/

Bestaande toewijzingen controleren: az role assignment list --assignee --all

Na het toewijzen van de rol, wacht je een paar minuten totdat de wijzigingen zijn doorgevoerd voordat je opnieuw test. RBAC-wijzigingen in Azure worden uiteindelijk consistent, en een test die direct na de toewijzing wordt uitgevoerd, kan nog steeds mislukken.

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 tenant-specifieke SharePoint-endpoint, niet aan het algemene Microsoft Graph-bereik.

De oplossing zit in de app-registratie. De service principal of beheerde identiteit moet de machtiging https://.sharepoint.com/.default in het bereik hebben, niet in het Graph-bereik. Technici die ADF SharePoint-connectors configureren met behulp van de Graph-URL, krijgen tokens die Azure op identiteitsniveau accepteert, maar die SharePoint op resourceniveau afwijst. Dit resulteert in de AudienceUriValidationFailedException, die overeenkomt met de 401-fout in de ADF-foutuitvoer.

Test het token en het bereik rechtstreeks met Postman of de Azure CLI voordat je ADF-configuraties wijzigt. Een verzoek aan de SharePoint REST API met het juiste tenant-specifieke 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 linked service rechtstreeks verwijzen naar de URL van de SharePoint-site en het tenant-specifieke bereik gebruiken, niet het globale Graph-endpoint.

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 service principal of beheerde identiteit van de pipeline. Een notebook binnen die pipeline wordt uitgevoerd in een eigen, aparte uitvoeringscontext.

De oplossing is om de service principal van de pipeline toegang te geven tot de werkruimte 'Werkruimtelid' of 'Werkruimtebijdrager' op de doel-Fabric-werkruimte 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 service principal). Het notebook zelf heeft geen probleem. De identiteit die het uitvoert, beschikt niet over de vereiste Lakehouse-machtigingen.

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 service principal verloopt of verliest de context halverwege de uitvoering. Door het lidmaatschap van de werkruimte 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.

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 firewall voor opslag staat.

De AutoResolveIntegrationRuntime gebruikt dynamische IP-bereiken die rouleren. Het toevoegen van een uitzondering voor statische IP-adressen aan de firewall voor opslag is voor deze runtime niet haalbaar. De juiste oplossing is een Managed Virtual Network Integration Runtime met een privé-endpoint naar het opslagaccount.

In ADF Studio: Instellingen > Managed Virtual Network > Managed IR maken > voeg een privé-endpoint toe voor de Azure Data Lake Storage Gen2-resource. Nadat het privé-endpoint 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-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 linked service kan naar beide verwijzen. Als de linked 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 linked service gebruikt. Open de definitie van de linked service in ADF Studio en bekijk het authenticatiegedeelte. Kopieer de object-ID of client-ID en gebruik vervolgens az role assignment list --assignee --all 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 linked 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 integratie runtime 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.

Een service principal die ADF-resources beheert — pipelines maken, linked services configureren, datasets implementeren — heeft minimaal de Data Factory Contributor-rol nodig op resource groepsniveau, niet alleen op de factory zelf.

Toegang op factoryniveau maakt het mogelijk om resources binnen die factory te beheren. Toegang op resource groepsniveau is vereist om resources te maken of te gebruiken die zich op het niveau van de resourcegroep bevinden (Key Vault-referenties, opslagaccounts, integratie runtimes in sommige configuraties). Dit onderscheid is de oorzaak van fouten waarbij een service principal bestaande pipelines kan bekijken en bewerken, maar geen nieuwe linked services kan maken of naar nieuwe geheimen kan verwijzen.

Voor CI/CD-pipelines die ADF-resources implementeren, heeft de service principal die voor de implementatie wordt gebruikt de Contributor-rol nodig op resource groepsniveau, plus de Key Vault Secrets User-rol op elke Key Vault waarnaar wordt verwezen door linked 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.

Fouten in ADF-pipelines worden door MetricSign gedetecteerd via het ADF REST API-endpoint 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 run vinden, op de activiteitsdetails klikken en de foutmelding lezen. De foutcode die je 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.