Perantara autentikasi web

2025-06-10

Artikel ini menjelaskan cara menghubungkan aplikasi Universal Windows Platform (UWP) Anda ke idP online yang menggunakan protokol autentikasi seperti OpenID atau OAuth. Metode AuthenticateAsync mengirimkan permintaan ke penyedia identitas online dan mendapatkan kembali token akses yang menjelaskan sumber daya dari penyedia yang dapat diakses oleh aplikasi.

Nota

Untuk sampel kode kerja yang lengkap, kloning repositori WebAuthenticationBroker di GitHub.

Daftarkan aplikasi Anda dengan penyedia online Anda

Anda harus mendaftarkan aplikasi Anda dengan penyedia identitas online yang ingin Anda sambungkan. Anda dapat mengetahui cara mendaftarkan aplikasi dari penyedia identitas. Setelah mendaftar, penyedia online biasanya memberi Anda Id atau kunci rahasia untuk aplikasi Anda.

Membangun URI permintaan autentikasi

URI permintaan terdiri dari alamat tempat Anda mengirim permintaan autentikasi ke penyedia online Anda ditambahkan dengan informasi lain yang diperlukan, seperti ID aplikasi atau rahasia, URI pengalihan tempat pengguna dikirim setelah menyelesaikan autentikasi, dan jenis respons yang diharapkan. Anda dapat mengetahui dari penyedia anda parameter apa yang diperlukan.

URI permintaan dikirim sebagai parameter requestUri dari metode AuthenticateAsync. Ini harus berupa alamat yang aman (harus dimulai dengan https://)

Contoh berikut menunjukkan cara membuat URI permintaan.

string startURL = "https://<providerendpoint>?client_id=<clientid>&scope=<scopes>&response_type=token";
string endURL = "http://<appendpoint>";

System.Uri startURI = new System.Uri(startURL);
System.Uri endURI = new System.Uri(endURL);

Hubungkan ke penyedia online

Anda memanggil metode AuthenticateAsync untuk terhubung ke penyedia identitas online dan mendapatkan token akses. Metode ini mengambil URI yang dibangun pada langkah sebelumnya sebagai parameter requestUri, dan URI ke mana Anda ingin pengguna dialihkan sebagai parameter callbackUri.

string result;

try
{
    var webAuthenticationResult = 
        await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync( 
        Windows.Security.Authentication.Web.WebAuthenticationOptions.None, 
        startURI, 
        endURI);

    switch (webAuthenticationResult.ResponseStatus)
    {
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
            // Successful authentication. 
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
            // HTTP error. 
            result = webAuthenticationResult.ResponseErrorDetail.ToString(); 
            break;
        default:
            // Other error.
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
    } 
}
catch (Exception ex)
{
    // Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here. 
    result = ex.Message;
}

Peringatan

Selain AuthenticateAsync, namespace Windows.Security.Authentication.Web berisi metode AuthenticateAndContinue . Jangan panggil metode ini. Ini dirancang untuk aplikasi yang hanya menargetkan Windows Phone 8.1 dan tidak digunakan lagi dimulai dengan Windows 10.

Menghubungkan dengan single sign-on (SSO).

Secara default, broker autentikasi Web tidak mengizinkan cookie untuk bertahan. Karena itu, bahkan jika pengguna aplikasi menunjukkan bahwa mereka ingin tetap masuk (misalnya, dengan memilih kotak centang dalam dialog masuk penyedia), mereka harus masuk setiap kali mereka ingin mengakses sumber daya untuk penyedia tersebut. Untuk masuk dengan SSO, penyedia identitas online Anda harus mengaktifkan SSO untuk broker autentikasi Web, dan aplikasi Anda harus memanggil fungsi overload AuthenticateAsync tanpa parameter callbackUri. Ini akan memungkinkan cookie yang tersimpan disimpan oleh broker web autentikasi, sehingga panggilan autentikasi di masa mendatang oleh aplikasi yang sama tidak akan memerlukan pengguna untuk masuk berulang-ulang (pengguna dianggap "masuk" sampai token akses kedaluwarsa).

Untuk mendukung SSO, penyedia online harus mengizinkan Anda mendaftarkan URI pengalihan dalam formulir ms-app://<appSID>, di mana <appSID> adalah SID untuk aplikasi Anda. Anda dapat menemukan SID aplikasi dari halaman pengembang aplikasi untuk aplikasi Anda, atau dengan memanggil metode GetCurrentApplicationCallbackUri .

string result;

try
{
    var webAuthenticationResult = 
        await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync( 
        Windows.Security.Authentication.Web.WebAuthenticationOptions.None, 
        startURI);

    switch (webAuthenticationResult.ResponseStatus)
    {
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
            // Successful authentication. 
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
            // HTTP error. 
            result = webAuthenticationResult.ResponseErrorDetail.ToString(); 
            break;
        default:
            // Other error.
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
    } 
}
catch (Exception ex)
{
    // Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here. 
    result = ex.Message;
}

Pemecahan Masalah

Ada beberapa cara untuk memecahkan masalah API broker autentikasi web, termasuk meninjau log operasional dan meninjau permintaan dan respons web menggunakan Fiddler.

Catatan operasional

Seringkali Anda dapat menentukan apa yang tidak berfungsi dengan menggunakan log operasional. Ada saluran log peristiwa khusus Microsoft-Windows-WebAuth\Operational yang memungkinkan pengembang situs web untuk memahami bagaimana halaman web mereka sedang diproses oleh broker autentikasi Web. Untuk mengaktifkannya, luncurkan eventvwr.exe dan aktifkan Log operasional di bawah Aplikasi dan Layanan\Microsoft\Windows\WebAuth. Selain itu, broker autentikasi Web menambahkan string unik ke string agen pengguna untuk mengidentifikasi dirinya sendiri di server web. Stringnya adalah "MSAuthHost/1.0". Perhatikan bahwa nomor versi dapat berubah di masa mendatang, jadi Anda tidak boleh bergantung pada nomor versi tersebut dalam kode Anda. Contoh string pengguna agen lengkap, diikuti dengan langkah-langkah debug lengkap, adalah sebagai berikut.

User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Win64; x64; Trident/6.0; MSAuthHost/1.0)

Aktifkan log operasional.
Jalankan aplikasi sosial Contoso.
Entri log yang dihasilkan dapat digunakan untuk memahami perilaku broker autentikasi Web secara lebih rinci. Dalam hal ini, ini dapat mencakup:
- Navigasi Mulai: Mencatat saat AuthHost dimulai dan berisi informasi tentang URL mulai dan akhir.
- Navigasi Selesai: Mencatat penyelesaian pemuatan halaman web.
- Tag Meta: Mencatat saat meta-tag ditemui termasuk detailnya.
- Navigasi Dihentikan: Navigasi dihentikan oleh pengguna.
- Kesalahan Navigasi: AuthHost mengalami kesalahan navigasi di URL termasuk HttpStatusCode.
- Akhir Navigasi: URL penghentian ditemukan.

Pemain biola

Debugger web Fiddler dapat digunakan dengan aplikasi. Untuk informasi selengkapnya, lihat Dokumentasi Fiddler

Karena AuthHost berjalan dalam kontainer aplikasinya sendiri, untuk memberinya kemampuan jaringan privat, Anda harus mengatur kunci registri: Editor Registri Windows Versi 5.00

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Opsi Eksekusi Berkas Gambar\authhost.exe\EnablePrivateNetwork = 00000001

Jika Anda tidak memiliki kunci registri ini, Anda dapat membuatnya di Prompt Perintah dengan hak istimewa administrator.
```
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
```

Tambahkan aturan untuk AuthHost karena inilah yang menghasilkan lalu lintas keluar.

CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.a.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
D:\Windows\System32>CheckNetIsolation.exe LoopbackExempt -s
List Loopback Exempted AppContainers
[1] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
    SID:  S-1-15-2-1973105767-3975693666-32999980-3747492175-1074076486-3102532000-500629349
[2] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
    SID:  S-1-15-2-166260-4150837609-3669066492-3071230600-3743290616-3683681078-2492089544
[3] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.a.p_8wekyb3d8bbwe
    SID:  S-1-15-2-3506084497-1208594716-3384433646-2514033508-1838198150-1980605558-3480344935

Tambahkan aturan firewall untuk lalu lintas masuk ke Fiddler.

Bagikan melalui