Werken met gebruikersidentiteiten in Azure-app Service-verificatie

Artikel
05/21/2024

In dit artikel wordt beschreven hoe u met gebruikersidentiteiten kunt werken bij het gebruik van de ingebouwde verificatie en autorisatie in App Service.

Toegang tot gebruikersclaims in app-code

Voor alle taalframeworks maakt App Service de claims in het binnenkomende token (of het nu gaat om een geverifieerde eindgebruiker of een clienttoepassing) die beschikbaar is voor uw code door ze 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 voorbeelden van headers zijn:

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

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

Notitie

Verschillende taalframeworks kunnen deze headers presenteren aan de app-code in verschillende indelingen, zoals kleine letters of titelcases.

Code die in elke taal of framework is geschreven, kan de informatie ophalen die nodig is uit deze headers. Het decoderen van de header van de client-principal heeft betrekking op dit proces. Voor sommige frameworks biedt het platform ook extra opties die handiger kunnen zijn.

De client-principalheader 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 het token rechtstreeks wordt verwerkt. De gedecodeerde nettolading is als volgt gestructureerd:

{
    "auth_typ": "",
    "claims": [
        {
            "typ": "",
            "val": ""
        }
    ],
    "name_typ": "",
    "role_typ": ""
}

Eigenschap	Type	Omschrijving
`auth_typ`	tekenreeks	De naam van de id-provider die wordt gebruikt door App Service-verificatie.
`claims`	matrix 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 in een token.
`val`	tekenreeks	De waarde van de claim.
`name_typ`	tekenreeks	Het naamclaimtype, dat doorgaans een URI is die schemagegevens over de `name` claim levert als er een is gedefinieerd.
`role_typ`	tekenreeks	Het rolclaimtype, dat doorgaans een URI is die schemagegevens over de `role` claim levert als er een is gedefinieerd.

Als u deze header wilt verwerken, moet uw app de nettolading decoderen en de claims matrix herhalen om de belangenclaims te vinden. Het kan handig zijn om ze te converteren naar een weergave die wordt gebruikt door het taalframework van de app. Hier volgt een voorbeeld van dit proces in C# waarmee een ClaimPrincipal-type wordt samengesteld voor de app die moet worden gebruikt:

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, we 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, etc. 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 in met de claims van de geverifieerde gebruiker, zodat u het standaard .NET-codepatroon kunt volgen, inclusief het [Authorize] kenmerk. 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 huidige gebruiker met App Service-verificatie. Voor meer informatie kunt u hierover lezen op de wiki Microsoft.Identity.Web of deze bekijken die in deze zelfstudie is gedemonstreerd voor een web-app die toegang heeft tot Microsoft Graph.

Notitie

Als de claimtoewijzing werkt, moet u het tokenarchief inschakelen.

Toegang krijgen 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.

Volgende stappen

Zelfstudie: gebruikers eind-tot-eind verifiëren en autoriseren

Delen via