.NET-apps verifiëren bij Azure-services tijdens lokale ontwikkeling met behulp van service-principals

Artikel
08/05/2024

Ontwikkelaars moeten fouten opsporen en testen op cloud-apps op hun lokale werkstation. Wanneer een app wordt uitgevoerd op het werkstation van een ontwikkelaar tijdens de lokale ontwikkeling, moet deze nog steeds worden geverifieerd bij alle Azure-services die door de app worden gebruikt. In dit artikel wordt beschreven hoe u service-principalobjecten voor toegewezen toepassingen instelt die moeten worden gebruikt tijdens lokale ontwikkeling.

Een diagram waarin wordt getoond hoe een lokale .NET-app de referenties van de ontwikkelaar gebruikt om verbinding te maken met Azure met behulp van lokaal geïnstalleerde ontwikkelhulpprogramma's.

Met speciale toepassingsservice-principals voor lokale ontwikkeling kunt u het principe van minimale bevoegdheden tijdens het ontwikkelen van apps volgen. Omdat machtigingen zijn afgestemd op precies wat er nodig is voor de app tijdens de ontwikkeling, wordt voorkomen dat app-code per ongeluk toegang krijgt tot een Azure-resource die is bedoeld voor gebruik door een andere app. Dit voorkomt ook dat er fouten optreden wanneer de app naar productie wordt verplaatst omdat de app te veel bevoegdheden heeft in de ontwikkelomgeving.

Een toepassingsservice-principal wordt ingesteld voor de app wanneer de app is geregistreerd in Azure. Wanneer u een app registreert voor lokale ontwikkeling, is het raadzaam het volgende te doen:

Maak een afzonderlijke app-registratie voor elke ontwikkelaar die aan de app werkt. Hiermee maakt u afzonderlijke toepassingsservice-principals voor elke ontwikkelaar die moet worden gebruikt tijdens de lokale ontwikkeling en voorkomt u dat ontwikkelaars referenties voor één toepassingsservice-principal moeten delen.
Maak een afzonderlijke app-registratie per app. Hiermee worden de machtigingen van de app alleen bereikt voor wat de app nodig heeft.

Tijdens lokale ontwikkeling worden omgevingsvariabelen ingesteld met de identiteit van de toepassingsservice-principal. De Azure Identity-bibliotheek leest deze omgevingsvariabelen en gebruikt deze informatie om de app te verifiëren bij de Azure-resources die nodig zijn.

1 - De toepassing registreren in Azure

Toepassingsservice-principalobjecten worden gemaakt met een app-registratie in Azure. U kunt dit doen met behulp van Azure Portal of Azure CLI.

Azure-portal
Azure-CLI

Meld u aan bij Azure Portal en volg deze stappen.

Instructies	Schermafbeelding
In Azure Portal: Voer app-registraties in in de zoekbalk bovenaan Azure Portal. Selecteer het item App-registraties onder de kop Services in het menu dat onder de zoekbalk wordt weergegeven.
Selecteer + Nieuwe registratie op de pagina App-registraties.
Vul op de pagina Een toepassing registreren het formulier als volgt in. Naam → Voer een naam in voor de app-registratie in Azure. Het wordt aanbevolen deze naam op te nemen, zoals de app-naam, de gebruiker waarvoor de app-registratie is bedoeld en een id zoals dev om aan te geven dat deze app-registratie moet worden gebruikt in lokale ontwikkeling. Ondersteunde accounttypen → Accounts in deze organisatiemap. Selecteer Registreren om uw app te registreren en de service-principal van de toepassing te maken.
Op de pagina App-registratie voor uw app: Toepassings-id (client) → Dit is de app-id die de app gebruikt voor toegang tot Azure tijdens de lokale ontwikkeling. Kopieer deze waarde naar een tijdelijke locatie in een teksteditor, omdat u deze in een toekomstige stap nodig hebt. Directory-id (tenant) → Deze waarde is ook nodig voor uw app wanneer deze wordt geverifieerd bij Azure. Kopieer deze waarde naar een tijdelijke locatie in een teksteditor, omdat deze in een toekomstige stap ook nodig is. Clientreferenties → U moet de clientreferenties voor de app instellen voordat uw app kan worden geverifieerd bij Azure en Azure-services kunt gebruiken. Selecteer Een certificaat of geheim toevoegen om referenties voor uw app toe te voegen.
Selecteer + Nieuw clientgeheim op de pagina Certificaten en geheimen.
Het dialoogvenster Een clientgeheim toevoegen wordt weergegeven aan de rechterkant van de pagina. In dit dialoogvenster: Beschrijving → Voer een waarde van Current in. Verloopt → Selecteer een waarde van 24 maanden. Selecteer Toevoegen om het geheim toe te voegen.
Op de pagina Certificaten en geheimen wordt de waarde van het clientgeheim weergegeven. Kopieer deze waarde naar een tijdelijke locatie in een teksteditor, omdat u deze in een toekomstige stap nodig hebt. BELANGRIJK: Dit is de enige keer dat u deze waarde ziet. Wanneer u deze pagina verlaat of vernieuwt, kunt u deze waarde niet meer zien. U kunt een extra clientgeheim toevoegen zonder dit clientgeheim ongeldig te maken, maar u ziet deze waarde niet opnieuw.

Azure CLI-opdrachten kunnen worden uitgevoerd in Azure Cloud Shell of op een werkstation waarop de Azure CLI is geïnstalleerd.

Gebruik eerst de opdracht az ad sp create-for-rbac om een nieuwe service-principal voor de app te maken. Hiermee maakt u ook tegelijkertijd de app-registratie voor de app.

az ad sp create-for-rbac \
    --name {service-principal-name}

De uitvoer van deze opdracht lijkt op de volgende JSON:

{
  "appId": "00000000-0000-0000-0000-000000000000",
  "displayName": "{service-principal-name}",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "11111111-1111-1111-1111-111111111111"
}

Kopieer deze uitvoer naar een tijdelijk bestand in een teksteditor, omdat u deze waarden in een toekomstige stap nodig hebt. Dit is de enige plaats waar u ooit het clientgeheim (wachtwoord) voor de service-principal ziet. U kunt echter later een nieuw wachtwoord toevoegen zonder de service-principal of bestaande wachtwoorden ongeldig te maken, indien nodig.

2 - Microsoft Entra-groep maken voor lokale ontwikkeling

Aangezien er doorgaans meerdere ontwikkelaars zijn die aan een app werken, is het raadzaam om een Microsoft Entra-groep te maken om de rollen (machtigingen) die de app nodig heeft in lokale ontwikkeling in te kapselen in plaats van de rollen toe te wijzen aan afzonderlijke service-principal-objecten. Deze aanpak biedt de volgende voordelen:

Elke ontwikkelaar weet zeker dat dezelfde rollen zijn toegewezen omdat rollen op groepsniveau worden toegewezen.
Als er een nieuwe rol nodig is voor de app, hoeft deze alleen aan de groep voor de app te worden toegevoegd.
Als een nieuwe ontwikkelaar lid wordt van het team, wordt er een nieuwe toepassingsservice-principal gemaakt voor de ontwikkelaar en toegevoegd aan de groep, zodat de ontwikkelaar over de juiste machtigingen beschikt om aan de app te werken.

Azure-portal
Azure-CLI

Instructies	Schermafbeelding
Navigeer naar de pagina Microsoft Entra-id in Azure Portal door Microsoft Entra-id in het zoekvak boven aan de pagina te typen. Selecteer Microsoft Entra-id in de sectie Services .
Selecteer Groepen in het linkermenu op de pagina Microsoft Entra-id.
Selecteer Nieuwe groep op de pagina Alle groepen.
Op de pagina Nieuwe groep : Groepstype → Beveiliging Groepsnaam → A-naam voor de beveiligingsgroep, meestal gemaakt op basis van de naam van de toepassing. Het is ook handig om een tekenreeks zoals local-dev op te nemen in de naam van de groep om het doel van de groep aan te geven. Groepsbeschrijving → Een beschrijving van het doel van de groep. Selecteer de koppeling Geen leden geselecteerd onder Leden om leden toe te voegen aan de groep.
In het dialoogvenster Leden toevoegen: Gebruik het zoekvak om de lijst met principal-namen in de lijst te filteren. Selecteer de toepassingsservice-principals voor lokale ontwikkeling voor deze app. Wanneer objecten zijn geselecteerd, worden ze grijs weergegeven en verplaatst u naar de lijst met geselecteerde items onder aan het dialoogvenster. Wanneer u klaar bent, selecteert u de knop Selecteren .
Selecteer Op de pagina Nieuwe groep maken de optie Maken om de groep te maken. De groep wordt gemaakt en u gaat terug naar de pagina Alle groepen . Het kan tot 30 seconden duren voordat de groep wordt weergegeven. Mogelijk moet u de pagina vernieuwen vanwege caching in Azure Portal.

De opdracht az ad group create wordt gebruikt om groepen te maken in Microsoft Entra ID. De parameters --display-name en --mail-nickname zijn vereist. De naam die aan de groep wordt gegeven, moet zijn gebaseerd op de naam van de app. Het is ook handig om een woordgroep zoals 'local-dev' op te nemen in de naam van de groep om het doel van de groep aan te geven.

az ad group create \
    --display-name MyDisplay \
    --mail-nickname MyDisplay \
    --description {group-description}

Als u leden aan de groep wilt toevoegen, hebt u de object-id van de service-principal van de toepassing nodig. Dit verschilt van de toepassings-id. Gebruik de opdracht az ad sp list om de beschikbare service-principals weer te geven. De --filter parameteropdracht accepteert OData-stijlfilters en kan worden gebruikt om de lijst te filteren zoals wordt weergegeven. De --query parameter beperkt kolommen tot alleen die van belang.

az ad sp list \
    --filter "startswith(displayName, 'msdocs')" \
    --query "[].{objectId:objectId, displayName:displayName}" \
    --output table

De opdracht az ad group member add kan vervolgens worden gebruikt om leden toe te voegen aan de groep:

az ad group member add \
    --group {group-name} \
    --member-id {object-id}

3 - Rollen toewijzen aan de toepassing

Bepaal vervolgens welke rollen (machtigingen) uw app nodig heeft voor welke resources en wijs deze rollen toe aan uw app. In dit voorbeeld worden de rollen toegewezen aan de Microsoft Entra-groep die in stap 2 is gemaakt. Aan groepen kan een rol worden toegewezen voor een resource, resourcegroep of abonnementsbereik. In dit voorbeeld ziet u hoe u rollen toewijst binnen het bereik van de resourcegroep, omdat de meeste apps al hun Azure-resources groeperen in één resourcegroep.

Azure-portal
Azure-CLI

Instructies	Schermafbeelding
Zoek de resourcegroep voor uw app door te zoeken naar de naam van de resourcegroep met behulp van het zoekvak boven aan Azure Portal. Navigeer naar uw resourcegroep door de naam van de resourcegroep te selecteren onder de kop Resourcegroepen in het dialoogvenster.
Selecteer op de pagina voor de resourcegroep toegangsbeheer (IAM) in het menu aan de linkerkant.
Op de pagina Toegangsbeheer (IAM): Selecteer het tabblad Roltoewijzingen. Selecteer + Toevoegen in het bovenste menu en voeg vervolgens roltoewijzing toe in de resulterende vervolgkeuzelijst.
De pagina Roltoewijzing toevoegen bevat alle rollen die kunnen worden toegewezen voor de resourcegroep. Gebruik het zoekvak om de lijst te filteren op een beter beheerbare grootte. In dit voorbeeld ziet u hoe u filtert op Storage Blob-rollen. Selecteer de rol die u wilt toewijzen. Selecteer Volgende om naar het volgende scherm te gaan.
Op de volgende pagina Roltoewijzing toevoegen kunt u opgeven aan welke gebruiker de rol moet toewijzen. Selecteer Gebruiker, groep of service-principal onder Toegang toewijzen aan. Selecteer + Leden selecteren onder Leden. Aan de rechterkant van Azure Portal wordt een dialoogvenster geopend.
In het dialoogvenster Leden selecteren : Het tekstvak Selecteren kan worden gebruikt om de lijst met gebruikers en groepen in uw abonnement te filteren. Typ indien nodig de eerste paar tekens van de Microsoft Entra-groep voor lokale ontwikkeling die u voor de app hebt gemaakt. Selecteer de microsoft Entra-groep voor lokale ontwikkeling die is gekoppeld aan uw toepassing. Selecteer Selecteren onderaan het dialoogvenster om door te gaan.
De Microsoft Entra-groep wordt weergegeven als geselecteerd in het scherm Roltoewijzing toevoegen. Selecteer Beoordelen + toewijzen om naar de laatste pagina te gaan en vervolgens opnieuw beoordelen en toewijzen om het proces te voltooien.

Aan een toepassingsservice-principal wordt een rol in Azure toegewezen met behulp van de opdracht az role assignment create :

az role assignment create --assignee "{appId}" \
    --role "{roleName}" \
    --resource-group "{resourceGroupName}"

Als u de rolnamen wilt ophalen waaraan een service-principal kan worden toegewezen, gebruikt u de opdracht az role definition list :

az role definition list \
    --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
    --output table

Als u bijvoorbeeld de service-principal van 00000000-0000-0000-0000-000000000000 de toepassing wilt toestaan met leesappId-, schrijf- en verwijdertoegang tot Azure Storage-blobcontainers en -gegevens toe te staan aan alle opslagaccounts in de resourcegroep msdocs-dotnet-sdk-auth-auth-example, wijst u de toepassingsservice-principal toe aan de rol Inzender voor opslagblobgegevens met behulp van de volgende opdracht:

az role assignment create --assignee "00000000-0000-0000-0000-000000000000" \
    --role "Storage Blob Data Contributor" \
    --resource-group "msdocs-dotnet-sdk-auth-example"

Zie Azure-rollen toewijzen met behulp van de Azure CLI voor meer informatie over het toewijzen van machtigingen op resource- of abonnementsniveau met behulp van de Azure CLI.

4 - Omgevingsvariabelen voor toepassingen instellen

Tijdens runtime DefaultAzureCredential wordt gezocht naar de informatie van de service-principal in een verzameling omgevingsvariabelen. Er zijn meerdere manieren om omgevingsvariabelen te configureren wanneer u met .NET werkt, afhankelijk van uw hulpprogramma's en omgeving.

Configureer, ongeacht de methode die u kiest, de volgende omgevingsvariabelen bij het werken met een service-principal:

AZURE_CLIENT_ID → de waarde van de app-id.
AZURE_TENANT_ID → de waarde van de tenant-id.
AZURE_CLIENT_SECRET → het wachtwoord/de referentie die voor de app is gegenereerd.

Wanneer u lokaal werkt met Visual Studio, kunnen omgevingsvariabelen worden ingesteld in het launchsettings.json bestand in de Properties map van uw project. Wanneer de app wordt gestart, worden deze waarden automatisch opgehaald. Houd er rekening mee dat deze configuraties niet met uw app reizen wanneer deze wordt geïmplementeerd, dus u moet omgevingsvariabelen instellen in uw doelhostingomgeving.

"profiles": {
    "SampleProject": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7177;http://localhost:5177",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID":"11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID": "11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
      }
    }
  }

Wanneer u lokaal werkt met Visual Studio Code, kunnen omgevingsvariabelen worden ingesteld in het launch.json bestand van uw project. Wanneer de app wordt gestart, worden deze waarden automatisch opgehaald. Houd er rekening mee dat deze configuraties niet met uw app reizen wanneer deze wordt geïmplementeerd, dus u moet omgevingsvariabelen instellen in uw doelhostingomgeving.

"configurations": [
{
    "env": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "AZURE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "AZURE_TENANT_ID":"11111111-1111-1111-1111-111111111111",
        "AZURE_CLIENT_SECRET": "=abcdefghijklmnopqrstuvwxyz"
    }
}

U kunt omgevingsvariabelen voor Windows instellen vanaf de opdrachtregel. Wanneer u deze methode gebruikt, zijn de waarden echter toegankelijk voor alle apps die op dat besturingssysteem worden uitgevoerd en kunnen conflicten veroorzaken als u niet voorzichtig bent. Omgevingsvariabelen kunnen worden ingesteld op gebruikers- of systeemniveau.

# Set user environment variables
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000"
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111"
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz"

# Set system environment variables - requires running as admin
setx ASPNETCORE_ENVIRONMENT "Development"
setx AZURE_CLIENT_ID "00000000-0000-0000-0000-000000000000" /m
setx AZURE_TENANT_ID "11111111-1111-1111-1111-111111111111" /m
setx AZURE_CLIENT_SECRET "=abcdefghijklmnopqrstuvwxyz" /m

PowerShell kan ook worden gebruikt om omgevingsvariabelen in te stellen op gebruikers- of computerniveau:

# Set user environment variables
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "User")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "User")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "User")

# Set system environment variables - requires running as admin
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_ID", "00000000-0000-0000-0000-000000000000", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_TENANT_ID", "11111111-1111-1111-1111-111111111111", "Machine")
[Environment]::SetEnvironmentVariable("AZURE_CLIENT_SECRET", "=abcdefghijklmnopqrstuvwxyz", "Machine")

5 - DefaultAzureCredential implementeren in uw toepassing

DefaultAzureCredential is een geordende volgorde van mechanismen voor verificatie bij Microsoft Entra. Elk verificatiemechanisme is een klasse die is afgeleid van de TokenCredential-klasse en wordt een referentie genoemd. Tijdens runtime DefaultAzureCredential wordt geprobeerd om te verifiëren met behulp van de eerste referentie. Als deze referentie geen toegangstoken kan verkrijgen, wordt de volgende referentie in de reeks geprobeerd, enzovoort, totdat een toegangstoken is verkregen. Op deze manier kan uw app verschillende referenties in verschillende omgevingen gebruiken zonder omgevingsspecifieke code te schrijven.

De volgorde en locaties waarin DefaultAzureCredential wordt gezocht naar referenties, vindt u op DefaultAzureCredential.

Als u dit wilt gebruiken DefaultAzureCredential, voegt u de Azure.Identity en eventueel de Microsoft.Extensions.Azure-pakketten toe aan uw toepassing:

Opdrachtregel
NuGet Package Manager

Navigeer in een terminal van uw keuze naar de projectmap van de toepassing en voer de volgende opdrachten uit:

dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.Azure

Azure-services worden geopend met behulp van gespecialiseerde clientklassen uit de verschillende Azure SDK-clientbibliotheken. Deze klassen en uw eigen aangepaste services moeten worden geregistreerd, zodat ze kunnen worden geopend via afhankelijkheidsinjectie in uw app. Voer Program.csin de volgende stappen de volgende stappen uit om een clientklasse te registreren en DefaultAzureCredential:

Neem de Azure.Identity en Microsoft.Extensions.Azure naamruimten op via using instructies.
Registreer de Azure-serviceclient met behulp van de bijbehorende Add-voorvoegselextensiemethode.
Geef een exemplaar van DefaultAzureCredential de UseCredential methode door.

Voorbeeld:

using Microsoft.Extensions.Azure;
using Azure.Identity;

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddBlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"));
    clientBuilder.UseCredential(new DefaultAzureCredential());
});

Een alternatief UseCredential is om rechtstreeks te instantiëren DefaultAzureCredential :

using Azure.Identity;

builder.Services.AddSingleton<BlobServiceClient>(_ =>
    new BlobServiceClient(
        new Uri("https://<account-name>.blob.core.windows.net"),
        new DefaultAzureCredential()));

Wanneer de voorgaande code wordt uitgevoerd op uw lokale ontwikkelwerkstation, wordt er gezocht in de omgevingsvariabelen voor een toepassingsservice-principal of in lokaal geïnstalleerde ontwikkelhulpprogramma's, zoals Visual Studio, voor een set ontwikkelaarsreferenties. Beide benaderingen kunnen worden gebruikt om de app te verifiëren bij Azure-resources tijdens lokale ontwikkeling.

Wanneer deze code wordt geïmplementeerd in Azure, kan dezelfde code uw app ook verifiëren bij andere Azure-resources. DefaultAzureCredential kan omgevingsinstellingen en beheerde identiteitsconfiguraties ophalen om automatisch te verifiëren bij andere services.

Delen via