Mulai cepat: Memasukkan pengguna dan memanggil Microsoft Graph API dari aplikasi web ASP.NET

  • Artikel

Dalam mulai cepat ini, Anda mengunduh dan menjalankan sampel kode yang menunjukkan aplikasi web ASP.NET yang dapat memasukkan pengguna dengan akun Microsoft Entra.

Lihat Cara kerja sampel untuk melihat ilustrasi.

Prasyarat

Mendaftarkan dan mengunduh aplikasi

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

Anda memiliki dua opsi untuk mulai membuat aplikasi Anda: konfigurasi otomatis atau manual.

Konfigurasi otomatis

Jika Anda ingin mengonfigurasi aplikasi secara otomatis lalu mengunduh sampel kode, ikuti langkah-langkah berikut:

  1. Masuk ke pengalaman mulai cepat pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.
  2. Masukkan nama untuk aplikasi dan pilih Daftar.
  3. Ikuti petunjuk untuk mengunduh dan mengonfigurasi aplikasi baru secara otomatis.

Konfigurasi manual

Jika Anda ingin mengonfigurasi sampel aplikasi dan kode secara manual, gunakan prosedur berikut.

Langkah 1: Daftarkan aplikasi Anda

  1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.
  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan ikon Pengaturan di menu atas untuk beralih ke penyewa tempat Anda ingin mendaftarkan aplikasi dari menu Direktori + langganan.
  3. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi dan pilih Pendaftaran baru.
  4. Untuk Nama, masukkan nama aplikasi. Misalnya, masukkan AspNetCore-Quickstart. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.
  5. Atur jenis URI Pengalihan ke Web dan nilai ke https://localhost:44368/.
  6. Pilih Daftarkan.
  7. Di bagian Kelola, pilih Autentikasi.
  8. Di bagian Pemberian implisit dan alur hibrid, pilih token ID.
  9. Pilih Simpan.

Langkah 2: Unduh proyek

Unduh sampel kode ASP.NET

Tip

Untuk menghindari kesalahan yang disebabkan oleh keterbatasan panjang jalur di Windows, kami sarankan mengekstrak arsip atau mengkloning repositori ke direktori di dekat akar drive Anda.

Langkah 3: Jalankan proyek

  1. Ekstrak file .zip ke folder lokal yang dekat dengan folder akar. Misalnya, ekstrak ke C:\Azure-Samples.

    Sebaiknya ekstrak arsip ke direktori dekat akar drive untuk menghindari kesalahan yang disebabkan oleh keterbatasan panjang jalur di Windows.

  2. Buka solusi di Visual Studio(AppModelv2-WebApp-OpenIDConnect-DotNet.sln).

  3. Bergantung pada versi Visual Studio, Anda mungkin perlu mengeklik kanan proyek AppModelv2-WebApp-OpenIDConnect-DotNet, lalu pilih Pulihkan paket NuGet.

  4. Buka Package Manager Console dengan memilih Lihat>Windows Lainnya>Package Manager Console. Kemudian jalankan Update-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform -r.

  5. Edit appsettings.json dan ganti parameter ClientId, , Tenantdan redirectUri dengan:

    "ClientId" :"Enter_the_Application_Id_here" />
"TenantId": "Enter_the_Tenant_Info_Here" />
"RedirectUri" :"https://localhost:44368/" />

    Dalam kode itu:

    • Enter_the_Application_Id_here adalah ID aplikasi (klien) dari pendaftaran aplikasi yang Anda buat sebelumnya. Temukan ID aplikasi (klien) di halaman Gambaran Umum aplikasi di Pendaftaran aplikasi di pusat admin Microsoft Entra.
    • Enter_the_Tenant_Info_Here adalah salah satu opsi berikut:
      • Jika aplikasi Anda mendukung Hanya organisasi saya, ganti nilai ini dengan ID direktori (penyewa) atau nama penyewa (misalnya, contoso.onmicrosoft.com). Temukan ID direktori (penyewa) di halaman Gambaran Umum aplikasi di Pendaftaran aplikasi di pusat admin Microsoft Entra.
      • Jika aplikasi Anda mendukung Akun di direktori organisasi apa pun, ganti nilai ini dengan organizations.
      • Jika aplikasi Anda mendukung Semua pengguna akun Microsoft, biarkan nilai ini sebagai common.
    • redirectUriadalah URI Pengalihan yang Anda masukkan sebelumnya di Pendaftaran aplikasi di pusat admin Microsoft Entra.

Informasi selengkapnya

Bagian ini memberikan gambaran umum tentang kode yang diperlukan untuk memasukkan pengguna. Gambaran umum ini dapat berguna untuk memahami cara kerja kode, apa argumen utamanya, dan cara menambahkan rincian masuk ke aplikasi ASP.NET Core yang ada.

Cara kerja sampel

Diagram interaksi antara browser web, aplikasi web, dan platform identitas Microsoft di aplikasi sampel.

Paket NuGet middleware OWIN

Anda dapat mengatur saluran autentikasi dengan autentikasi berbasis cookie menggunakan OpenID Connect di ASP.NET dengan paket middleware OWIN. Anda dapat menginstal paket ini dengan menjalankan perintah berikut di Package Manager Console dalam Visual Studio:

Install-Package Microsoft.Identity.Web.Owin
Install-Package Microsoft.Identity.Web.GraphServiceClient
Install-Package Microsoft.Owin.Security.Cookies

Kelas permulaan OWIN

Middleware OWIN menggunakan kelas permulaan yang berjalan ketika proses hosting dimulai. Dalam mulai cepat ini, file startup.cs berada di folder akar. Kode berikut menunjukkan parameter yang digunakan mulai cepat ini:

    public void Configuration(IAppBuilder app)
    {
        app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

        app.UseCookieAuthentication(new CookieAuthenticationOptions());
        OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

        app.AddMicrosoftIdentityWebApp(factory);
        factory.Services
            .Configure<ConfidentialClientApplicationOptions>(options => { options.RedirectUri = "https://localhost:44368/"; })
            .AddMicrosoftGraph()
            .AddInMemoryTokenCaches();
        factory.Build();
    }
Di mana Deskripsi
ClientId ID aplikasi untuk aplikasi yang terdaftar di portal Microsoft Azure.
Authority Titik akhir layanan token keamanan (STS) untuk diautentikasi pengguna. Biasanya https://login.microsoftonline.com/{tenant}/v2.0 untuk awan publik. Dalam URL tersebut, {tenant} adalah nama penyewa, ID penyewa, atau common untuk referensi ke titik akhir umum. (Titik akhir umum digunakan untuk aplikasi multipenyewa.)
RedirectUri URL tempat pengguna dikirim setelah autentikasi terhadap platform identitas Microsoft.
PostLogoutRedirectUri URL tempat pengguna dikirim setelah keluar.
Scope Daftar lingkup yang diminta, dipisahkan oleh spasi.
ResponseType Permintaan agar respons dari autentikasi berisi kode otorisasi dan token ID.
TokenValidationParameters Daftar parameter untuk validasi token. Dalam hal ini, ValidateIssuer diatur ke false untuk menunjukkan bahwa parameter dapat menerima rincian masuk dari jenis akun pribadi, kantor, atau sekolah apa pun.
Notifications Daftar delegasi yang dapat dijalankan di OpenIdConnect pesan.

Tantangan autentikasi

Anda dapat memaksa pengguna untuk masuk dengan meminta tantangan autentikasi di pengontrol Anda:

public void SignIn()
{
    if (!Request.IsAuthenticated)
    {
        HttpContext.GetOwinContext().Authentication.Challenge(
            new AuthenticationProperties{ RedirectUri = "/" },
            OpenIdConnectAuthenticationDefaults.AuthenticationType);
    }
}

Tip

Meminta tantangan autentikasi menggunakan metode ini bersifat opsional. Anda biasanya menggunakannya saat ingin tampilan dapat diakses dari pengguna yang terautentikasi dan tidak diautentikasi. Atau, Anda dapat melindungi pengontrol menggunakan metode yang dijelaskan di bagian berikutnya.

Atribut untuk melindungi pengontrol atau tindakan pengontrol

Anda dapat melindungi pengontrol atau metode pengontrol menggunakan atribut [Authorize]. Atribut ini membatasi akses ke pengontrol atau tindakan dengan hanya mengizinkan pengguna terautentikasi untuk mengakses tindakan di pengontrol. Tantangan otentikasi kemudian akan terjadi secara otomatis ketika pengguna yang tidak diautentikasi mencoba mengakses salah satu tindakan atau pengontrol yang dihiasi oleh atribut [Authorize].

Memanggil Microsoft Graph dari pengontrol

Anda dapat memanggil Microsoft Graph dari pengontrol dengan mendapatkan instans GraphServiceClient menggunakan GetGraphServiceClient metode ekstensi pada pengontrol, seperti dalam kode berikut:

    try
    { 
        var me = await this.GetGraphServiceClient().Me.GetAsync();
        ViewBag.Username = me.DisplayName;
    }
    catch (ServiceException graphEx) when (graphEx.InnerException is MicrosoftIdentityWebChallengeUserException)
    {
        HttpContext.GetOwinContext().Authentication.Challenge(OpenIdConnectAuthenticationDefaults.AuthenticationType);
        return View();
    }

Bantuan dan dukungan

Jika Anda memerlukan bantuan, ingin melaporkan masalah, atau ingin mempelajari opsi dukungan, lihat Bantuan dan dukungan bagi pengembang.

Langkah berikutnya

Untuk panduan langkah demi langkah lengkap tentang membangun aplikasi dan fitur baru, termasuk penjelasan lengkap dari mulai cepat ini, cobalah tutorial ASP.NET.

Menambahkan rincian masuk ke aplikasi web ASP.NET