Bekerja dengan identitas pengguna di autentikasi Azure App Service

Artikel ini memperlihatkan kepada Anda cara bekerja dengan identitas pengguna saat menggunakan autentikasi dan otorisasi bawaan di App Service.

Mengakses klaim pengguna dalam kode aplikasi

Untuk semua kerangka kerja bahasa, App Service membuat klaim dalam token masuk (baik dari pengguna akhir yang atau aplikasi klien terautentikasi) yang tersedia untuk kode Anda dengan memasukannya ke header permintaan. Permintaan eksternal tidak diizinkan untuk mengatur header ini, sehingga hanya ada jika diatur oleh App Service. Beberapa contoh header meliputi:

Header	Deskripsi
X-MS-CLIENT-PRINCIPAL	Representasi JSON yang dikodekan Base64 dari klaim yang tersedia. Untuk informasi selengkapnya, lihat Mendekode header utama klien.
X-MS-CLIENT-PRINCIPAL-ID	Pengidentifikasi untuk penelepon yang ditetapkan oleh IdP.
X-MS-CLIENT-PRINCIPAL-NAME	Nama yang dapat dibaca manusia untuk pemanggil yang ditetapkan oleh IdP, misalnya Alamat Email, Nama Prinsipal Pengguna.
X-MS-CLIENT-PRINCIPAL-IDP	Nama Penyedia Identitas yang digunakan oleh Autentikasi App Service.

Token penyedia juga diekspos melalui header serupa. Misalnya, Penyedia Identitas Microsoft juga menetapkan dan X-MS-TOKEN-AAD-ID-TOKEN sebagaimana merujuknyaX-MS-TOKEN-AAD-ACCESS-TOKEN.

Catatan

Kerangka kerja bahasa yang berbeda mungkin menampilkan header ini ke kode aplikasi dalam format yang berbeda, seperti huruf kecil atau kapitalisasi.

Kode yang ditulis dalam bahasa atau kerangka kerja apa pun bisa mendapat informasi yang dibutuhkan dari header ini. Mendekode header utama klien mencakup proses ini. Untuk beberapa kerangka kerja, platform ini juga menyediakan opsi tambahan yang mungkin lebih nyaman.

Mendekode header utama klien

X-MS-CLIENT-PRINCIPAL berisi set lengkap klaim yang tersedia sebagai JSON yang dikodekan Base64. Klaim ini melalui proses pemetaan klaim default, jadi beberapa mungkin memiliki nama yang berbeda dari yang Anda lihat jika memproses token secara langsung. Payload yang didekodekan disusun sebagai berikut:

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

Properti	Jenis	Deskripsi
auth_typ	string	Nama Penyedia Identitas yang digunakan oleh Autentikasi App Service.
claims	array objek	Array objek yang mewakili klaim yang tersedia. Setiap objek berisi typ properti dan val .
typ	string	Nama klaim. Ini mungkin tunduk pada pemetaan klaim default dan bisa berbeda dari klaim yang sesuai yang terkandung dalam token.
val	string	Nilai klaim.
name_typ	string	Jenis klaim nama, yang biasanya merupakan URI yang memberikan informasi skema tentang name klaim jika didefinisikan.
role_typ	string	Jenis klaim peran, yang biasanya merupakan URI yang memberikan informasi skema tentang role klaim jika didefinisikan.

Untuk memproses header ini, aplikasi Anda harus mendekode payload dan melakukan iterasi claims melalui array untuk menemukan klaim yang diinginkan. Mungkin lebih mudah untuk mengonversinya menjadi representasi yang digunakan oleh kerangka kerja bahasa aplikasi. Berikut adalah contoh proses ini di C# yang membangun jenis ClaimsPrincipal untuk digunakan aplikasi:

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);
    }
}

Alternatif khusus kerangka kerja

Untuk aplikasi ASP.NET 4.6, App Service mengisi ClaimsPrincipal.Current dengan klaim pengguna yang diautentikasi, sehingga Anda dapat mengikuti pola kode .NET standar, termasuk [Authorize] atribut. Demikian pula, untuk aplikasi PHP, App Service mengisi _SERVER['REMOTE_USER'] variabel. Untuk aplikasi Java, klaim dapat diakses dari servlet Tomcat.

Untuk Azure Functions, ClaimsPrincipal.Current tidak diisi untuk kode .NET, tetapi Anda masih dapat menemukan klaim pengguna di header permintaan, atau mendapatkan ClaimsPrincipal objek dari konteks permintaan atau bahkan melalui parameter pengikatan. Untuk informasi selengkapnya, lihat Bekerja dengan identitas klien di Azure Functions.

Untuk .NET Core, Microsoft.Identity.Web mendukung pengisian pengguna saat ini dengan autentikasi App Service. Untuk mempelajari lebih lanjut, Anda dapat membacanya di wiki Microsoft.Identity.Web, atau melihatnya ditunjukkan dalam tutorial ini untuk aplikasi web yang mengakses Microsoft Graph.

Catatan

Agar pemetaan klaim berfungsi, Anda harus mengaktifkan penyimpanan Token.

Mengakses klaim pengguna menggunakan API

Jika penyimpanan token diaktifkan untuk aplikasi Anda, Anda juga dapat memperoleh detail lain tentang pengguna yang diautentikasi dengan memanggil /.auth/me.

Langkah berikutnya

Tutorial: Mengautentikasi dan mengotorisasi pengguna secara menyeluruh