Verifiëren bij Azure-resources vanuit .NET-apps die on-premises worden gehost

Apps die buiten Azure worden gehost (bijvoorbeeld on-premises of in een datacenter van derden), moeten een service-principal voor toepassingen gebruiken om bij Azure te verifiëren bij het openen van Azure-resources. Toepassingsservice-principalobjecten worden gemaakt met behulp van het app-registratieproces in Azure. Wanneer een toepassingsservice-principal wordt gemaakt, worden er een client-id en clientgeheim gegenereerd voor uw app. De client-id, het clientgeheim en uw tenant-id worden vervolgens opgeslagen in omgevingsvariabelen, zodat ze kunnen worden gebruikt door de Azure Identity-bibliotheek om uw app tijdens runtime bij Azure te verifiëren.

Er moet een andere app-registratie worden gemaakt voor elke omgeving waarin de app wordt gehost. Hierdoor kunnen omgevingsspecifieke resourcemachtigingen worden geconfigureerd voor elke service-principal en ervoor zorgen dat een app die in één omgeving is geïmplementeerd, niet praat met Azure-resources die deel uitmaken van een andere omgeving.

1 - De toepassing registreren in Azure

Een app kan worden geregistreerd bij Azure met behulp van Azure Portal of de Azure CLI.

Azure-portal

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 met het label 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 om deze naam op te nemen, zoals de app-naam en -omgeving (test, prod) waarvoor de app-registratie geldt. 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. Deze is ook nodig in een toekomstige stap. 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. BELANGRIJK: Stel een herinnering in uw agenda in vóór de vervaldatum van het geheim. Op deze manier kunt u een nieuw geheim toevoegen vóór en uw apps bijwerken vóór de vervaldatum van dit geheim en een serviceonderbreking in uw app voorkomen.
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

az ad sp create-for-rbac --name <app-name>

De uitvoer van de opdracht ziet er ongeveer als volgt uit. Noteer deze waarden of houd dit venster open omdat u deze waarden in de volgende stap nodig hebt en de waarde voor het wachtwoord (clientgeheim) niet opnieuw kunt weergeven.

{
  "appId": "00000000-1111-2222-3333-444444444444",
  "displayName": "msdocs-dotnet-sdk-auth-prod",
  "password": "abcdefghijklmnopqrstuvwxyz",
  "tenant": "00000000-0000-0000-0000-000000000000"
}

2 - Rollen toewijzen aan de service-principal van de toepassing

Vervolgens moet u bepalen welke rollen (machtigingen) uw app nodig heeft voor welke resources en welke rollen aan uw app worden toegewezen. Rollen kunnen aan een resource, resourcegroep of abonnementsbereik worden toegewezen. In dit voorbeeld ziet u hoe u rollen toewijst voor de service-principal binnen het bereik van de resourcegroep, omdat de meeste apps al hun Azure-resources groeperen in één resourcegroep.

Azure-portal

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 service-principal die u voor de app hebt gemaakt om de lijst te filteren. Selecteer de service-principal die aan uw toepassing is gekoppeld. Selecteer Selecteren onderaan het dialoogvenster om door te gaan.
De service-principal wordt nu 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.

Azure-CLI

Aan een service-principal wordt een rol toegewezen in Azure 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 met de appId toegang tot 00000000-0000-0000-0000-000000000000 Azure Storage-blobcontainers en -gegevens wilt toestaan voor alle opslagaccounts in de resourcegroep msdocs-dotnet-sdk-auth-example , wijst u de service-principal van de toepassing 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.

3 - Omgevingsvariabelen configureren voor toepassing

Het DefaultAzureCredential object zoekt tijdens runtime naar referenties van de service-principal in een set omgevingsvariabelen. Er zijn meerdere manieren om omgevingsvariabelen te configureren wanneer u met .NET werkt, afhankelijk van uw hulpprogramma's en omgeving.

Ongeacht welke benadering u kiest, configureert u de volgende omgevingsvariabelen wanneer u met een service-principal werkt:

• 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.

IIS

Als uw app wordt gehost in IIS, is het raadzaam om omgevingsvariabelen per app-pool in te stellen om instellingen tussen apps te isoleren.

appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='ASPNETCORE_ENVIRONMENT',value='Production']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_ID',value='00000000-0000-0000-0000-000000000000']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_TENANT_ID',value='11111111-1111-1111-1111-111111111111']" /commit:apphost
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='Contoso'].environmentVariables.[name='AZURE_CLIENT_SECRET',value='=abcdefghijklmnopqrstuvwxyz']" /commit:apphost

U kunt deze instellingen ook rechtstreeks configureren met behulp van het applicationPools element in het applicationHost.config bestand:

<applicationPools>
   <add name="CorePool" managedRuntimeVersion="v4.0" managedPipelineMode="Classic">
      <environmentVariables>
         <add name="ASPNETCORE_ENVIRONMENT" value="Development" />
         <add name="AZURE_CLIENT_ID" value="00000000-0000-0000-0000-000000000000" />
         <add name="AZURE_TENANT_ID" value="11111111-1111-1111-1111-111111111111" />
         <add name="AZURE_CLIENT_SECRET" value="=abcdefghijklmnopqrstuvwxyz" />
      </environmentVariables>
   </add>
</applicationPools>

Windows

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

U kunt PowerShell ook gebruiken 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")

4 - 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

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

NuGet Package Manager

Klik met de rechtermuisknop op uw project in het Venster Solution Explorer van Visual Studio en selecteer NuGet-pakketten beheren. Zoek naar Azure.Identity en installeer het overeenkomende pakket. Herhaal dit proces voor het Pakket 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:

1. Neem de Azure.Identity en Microsoft.Extensions.Azure naamruimten op via using instructies.
2. Registreer de Azure-serviceclient met behulp van de bijbehorende Add-voorvoegselextensiemethode.
3. 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.