Delen via

Werken met gebruikersidentiteiten in Azure-app Service-verificatie

In dit artikel leest u hoe u met gebruikersidentiteiten kunt werken wanneer u ingebouwde verificatie en autorisatie gebruikt in Azure App Service.

Toegang tot gebruikersclaims in app-code

Voor alle taalframeworks maakt App Service de claims in het binnenkomende token (van een geverifieerde eindgebruiker of van een clienttoepassing) beschikbaar voor uw code door deze in de aanvraagheaders te injecteren. Externe aanvragen mogen deze headers niet instellen, dus ze zijn alleen aanwezig als ze zijn ingesteld door App Service.

Enkele voorbeeldheaders worden beschreven in de volgende tabel:

Koptekst Beschrijving
X-MS-CLIENT-PRINCIPAL Een met Base64 gecodeerde JSON-weergave van beschikbare claims. Zie De client-principalheader decoderen voor meer informatie.
X-MS-CLIENT-PRINCIPAL-ID Een id voor de beller, die door de id-provider wordt ingesteld.
X-MS-CLIENT-PRINCIPAL-NAME Een door mensen leesbare naam voor de beller, ingesteld door de id-provider, zoals een e-mailadres of een user principal name.
X-MS-CLIENT-PRINCIPAL-IDP De naam van de id-provider die door App Service-verificatie wordt gebruikt.

Providertokens worden ook weergegeven via vergelijkbare headers. Microsoft Entra stelt bijvoorbeeld ook X-MS-TOKEN-AAD-ACCESS-TOKEN en X-MS-TOKEN-AAD-ID-TOKEN in zoals gepast.

Notitie

Verschillende programmeertaalframeworks kunnen deze headers op verschillende manieren aan de app-code presenteren, zoals in kleine letters of met een titelcase.

Code die in elke taal of framework is geschreven, kan de informatie ophalen die nodig is uit deze headers. Decodeer de client-principalheader behandelt dit proces. Voor sommige frameworks biedt het platform ook extra opties die handiger kunnen zijn.

De client-principal header decoderen

X-MS-CLIENT-PRINCIPAL bevat de volledige set beschikbare claims als met Base64 gecodeerde JSON. Deze claims doorlopen een standaardproces voor claimtoewijzing, dus sommigen hebben mogelijk andere namen dan u zou zien als u het token rechtstreeks hebt verwerkt.

De gedecodeerde payload is als volgt gestructureerd:

{
    "auth_typ": "",
    "claims": [
        {
            "typ": "",
            "val": ""
        }
    ],
    "name_typ": "",
    "role_typ": ""
}
Eigenschap Type Beschrijving
auth_typ tekenreeks De naam van de id-provider die door App Service-verificatie wordt gebruikt.
claims reeks van objecten Een matrix met objecten die de beschikbare claims vertegenwoordigen. Elk object bevat typ en val eigenschappen.
typ tekenreeks De naam van de claim. Het kan onderhevig zijn aan standaardclaimtoewijzing en kan afwijken van de bijbehorende claim die is opgenomen in een token.
val tekenreeks De waarde van de claim.
name_typ tekenreeks Het naamclaimtype, dat doorgaans een URI is die schema-informatie over de name claim biedt als er een is gedefinieerd.
role_typ tekenreeks Het rolclaimtype, dat doorgaans een URI is die schema-informatie over de role claim biedt als er een is gedefinieerd.

Als u deze header wilt verwerken, moet uw app de nettolading decoderen en de claims matrix doorlopen om relevante claims te vinden. Het kan handig zijn om claims te converteren naar een weergave die door het taalframework van de app wordt gebruikt. Hier volgt een voorbeeld van dit proces in C# waarmee een ClaimsPrincipal type wordt samengesteld dat de app kan gebruiken:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Claims;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.AspNetCore.Http;

public static class ClaimsPrincipalParser
{
    private class ClientPrincipalClaim
    {
        [JsonPropertyName("typ")]
        public string Type { get; set; }
        [JsonPropertyName("val")]
        public string Value { get; set; }
    }

    private class ClientPrincipal
    {
        [JsonPropertyName("auth_typ")]
        public string IdentityProvider { get; set; }
        [JsonPropertyName("name_typ")]
        public string NameClaimType { get; set; }
        [JsonPropertyName("role_typ")]
        public string RoleClaimType { get; set; }
        [JsonPropertyName("claims")]
        public IEnumerable<ClientPrincipalClaim> Claims { get; set; }
    }

    public static ClaimsPrincipal Parse(HttpRequest req)
    {
        var principal = new ClientPrincipal();

        if (req.Headers.TryGetValue("x-ms-client-principal", out var header))
        {
            var data = header[0];
            var decoded = Convert.FromBase64String(data);
            var json = Encoding.UTF8.GetString(decoded);
            principal = JsonSerializer.Deserialize<ClientPrincipal>(json, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
        }

        /** 
         *  At this point, the code can iterate through `principal.Claims` to
         *  check claims as part of validation. Alternatively, you can convert
         *  it into a standard object with which to perform those checks later
         *  in the request pipeline. That object can also be leveraged for 
         *  associating user data, and so on. The rest of this function performs such
         *  a conversion to create a `ClaimsPrincipal` as might be used in 
         *  other .NET code.
         */

        var identity = new ClaimsIdentity(principal.IdentityProvider, principal.NameClaimType, principal.RoleClaimType);
        identity.AddClaims(principal.Claims.Select(c => new Claim(c.Type, c.Value)));
        
        return new ClaimsPrincipal(identity);
    }
}

Frameworkspecifieke alternatieven

Voor ASP.NET 4.6-apps vult App Service ClaimsPrincipal.Current met de claims van de geverifieerde gebruiker. U kunt het standaard .NET-codepatroon volgen, inclusief het kenmerk [Authorize]. Voor PHP-apps vult App Service de _SERVER['REMOTE_USER'] variabele ook in. Voor Java-apps zijn de claims toegankelijk vanuit de Tomcat-servlet.

Voor Azure FunctionsClaimsPrincipal.Current is deze niet ingevuld voor .NET-code, maar u kunt de gebruikersclaims nog steeds vinden in de aanvraagheaders of het ClaimsPrincipal object ophalen uit de aanvraagcontext of zelfs via een bindingsparameter. Zie Werken met clientidentiteiten in Azure Functions voor meer informatie.

Voor .NET Core ondersteunt Microsoft.Identity.Web het invullen van de actuele gebruiker door middel van App Service-verificatie. Raadpleeg de wiki Microsoft.Identity.Web voor meer informatie of bekijk deze in deze zelfstudie voor een web-app die toegang heeft tot Microsoft Graph.

Notitie

Als claimtoewijzing werkt, moet u het tokenarchief inschakelen.

Toegang tot gebruikersclaims met behulp van de API

Als het tokenarchief is ingeschakeld voor uw app, kunt u ook andere gegevens over de geverifieerde gebruiker verkrijgen door aan te roepen /.auth/me.

Verwante inhoud