Mengotorisasi akses ke aplikasi web menggunakan OpenID Connect dan Microsoft Azure Active Directory

  • Artikel

Peringatan

Konten ini untuk titik akhir Azure AD v1.0 yang lebih lama. Gunakan platform identitas Microsoft untuk proyek baru.

OpenID Connect adalah lapisan identitas sederhana yang dibangun di atas protokol OAuth 2.0. OAuth 2.0 mendefinisikan mekanisme untuk mendapatkan dan menggunakan token akses untuk mengakses sumber daya yang dilindungi, tetapi tidak menentukan metode standar untuk memberikan informasi identitas. OpenID Connect menerapkan autentikasi sebagai ekstensi ke proses otorisasi OAuth 2.0. Ini memberikan informasi tentang pengguna akhir dalam bentuk id_token yang memverifikasi identitas pengguna dan memberikan informasi profil dasar tentang pengguna.

OpenID Connect adalah rekomendasi kami jika Anda membangun aplikasi web yang dihost di server dan diakses melalui browser.

Mendaftarkan aplikasi Anda dengan penyewa AD Anda

Pertama, daftarkan aplikasi Anda dengan penyewa Microsoft Azure Active Directory (Azure AD). Ini akan memberi Anda ID Aplikasi untuk aplikasi Anda, serta mengaktifkannya untuk menerima token.

  1. Masuk ke portal Microsoft Azure.

  2. Pilih penyewa Microsoft Azure Active Directory Anda dengan memilih akun Anda di sudut kanan atas halaman, diikuti dengan memilih navigasi Alihkan Direktori, lalu pilih penyewa yang sesuai.

    • Lewati langkah ini jika Anda hanya memiliki satu penyewa Microsoft Azure Active Directory di bawah akun Anda, atau jika Anda sudah memilih penyewa Microsoft Azure Active Directory yang sesuai.

  3. Di portal Microsoft Azure, cari dan pilih Azure Active Directory.

  4. Di menu sebelah kiri Microsoft Azure Active Directory, pilih Pendaftaran Aplikasi, lalu pilih Pendaftaran baru.

  5. Ikuti perintah dan buat aplikasi baru. Tidak masalah apakah itu aplikasi web atau aplikasi klien publik (desktop & seluler) untuk tutorial ini, tetapi jika Anda ingin contoh khusus untuk aplikasi web atau aplikasi klien publik, lihat mulai cepat kami.

    • Nama adalah nama aplikasi dan menjelaskan aplikasi Anda ke pengguna akhir.
    • Di bawah Jenis akun yang didukung, pilih Akun di direktori organisasi dan akun Microsoft pribadi apa pun.
    • Berikan URI Pengalihan. Untuk aplikasi web, ini adalah URL dasar aplikasi Anda tempat pengguna dapat masuk. Contohnya:http://localhost:12345 Untuk klien publik (seluler & desktop), Microsoft Azure Active Directory menggunakannya untuk mengembalikan respons token. Masukkan nilai yang spesifik untuk aplikasi Anda. Contohnya:http://MyFirstAADApp

  6. Setelah Anda menyelesaikan pendaftaran, Microsoft Azure Active Directory akan menetapkan pengidentifikasi klien unik (ID Aplikasi) ke aplikasi Anda. Anda memerlukan nilai ini di bagian berikutnya, jadi, salin dari halaman aplikasi.

  7. Untuk menemukan aplikasi Anda di portal Microsoft Azure, pilih Pendaftaran aplikasi, lalu pilih Tampilkan semua aplikasi.

Alur autentikasi menggunakan OpenID Connect

Alur masuk paling dasar berisi langkah-langkah berikut - masing-masing dijelaskan secara terperinci di bawah ini.

Alur Autentikasi OpenId Connect

Dokumen metadata OpenID Connect

OpenID Connect menjelaskan dokumen metadata yang berisi sebagian besar informasi yang diperlukan aplikasi untuk masuk. Ini termasuk informasi seperti URL yang akan digunakan dan lokasi kunci penandatanganan publik layanan. Dokumen metadata OpenID Connect dapat ditemukan di:

https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration

Metadata adalah dokumen JavaScript Object Notation (JSON) sederhana. Lihat cuplikan berikut sebagai contoh. Konten cuplikan sepenuhnya dijelaskan dalam spesifikasi OpenID Connect. Perhatikan bahwa memberikan ID penyewa daripada common sebagai ganti {tenant} di atas akan mengakibatkan URI khusus penyewa di objek JSON yang dikembalikan.

{
    "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
    "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
    "token_endpoint_auth_methods_supported":
    [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
    "userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
    ...
}

Jika aplikasi Anda memiliki kunci penandatanganan kustom sebagai hasil dari penggunaan fitur pemetaan klaim, Anda harus menambahkan parameter kueri appid yang berisi ID aplikasi agar bisa mendapatkan jwks_uri yang menunjuk ke informasi kunci penandatanganan aplikasi Anda. Misalnya: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e berisi jwks_uri dari https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Mengirim permintaan masuk

Ketika aplikasi web Anda perlu mengautentikasi pengguna, aplikasi harus mengarahkan pengguna ke titik akhir /authorize. Permintaan ini mirip dengan bagian pertama Alur Kode Otorisasi OAuth 2.0, dengan perbedaan penting ini:

  • Permintaan harus menyertakan cakupan openid dalam parameter scope.
  • Parameter response_type harus mencakup id_token.
  • Permintaan harus mencakup parameter nonce.

Jadi, sampel permintaan akan terlihat seperti ini:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7
Parameter Jenis Deskripsi
tenant diperlukan Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah pengidentifikasi penyewa, misalnya, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 atau contoso.onmicrosoft.com atau common untuk token penyewa independen
client_id diperlukan ID Aplikasi yang ditetapkan ke aplikasi Anda saat Anda mendaftarkannya dengan Microsoft Azure Active Directory. Anda dapat menemukan ini di portal Microsoft Azure. Klik Microsoft Azure Active Directory, klik Pendaftaran Aplikasi, pilih aplikasi dan cari ID Aplikasi di halaman aplikasi.
response_type diperlukan Harus menyertakan id_token untuk masuk OpenID Connect. Ini mungkin juga termasuk response_types lain, seperti code atau token.
scope disarankan Spesifikasi OpenID Connect memerlukan cakupan openid, yang diterjemahkan ke izin "Memasukkan Anda" di antarmuka pengguna persetujuan. Cakupan OIDC ini dan lainnya diabaikan pada titik akhir v1.0, tetapi masih merupakan praktik terbaik untuk klien yang mematuhi standar.
nonce diperlukan Nilai yang tercantum dalam permintaan, dibuat oleh aplikasi, yang disertakan dalam id_token yang dihasilkan sebagai klaim. Aplikasi kemudian dapat memverifikasi nilai ini untuk mengurangi serangan pemutaran ulang token. Secara umum, nilainya adalah string atau GUID acak dan unik yang dapat digunakan untuk mengidentifikasi asal permintaan.
redirect_uri disarankan redirect_uri aplikasi Anda, di mana respons autentikasi dapat dikirim dan diterima oleh aplikasi Anda. Ini harus sama persis dengan salah satu redirect_uris yang Anda daftarkan di portal, kecuali hal itu memang harus dikodekan URL. Jika hilang, agen pengguna akan dikirim kembali ke salah satu URI pengalihan yang terdaftar untuk aplikasi, secara acak. Panjang maksimum adalah 255 byte
response_mode opsional Tentukan metode yang harus digunakan untuk mengirim authorization_code yang dihasilkan kembali ke aplikasi Anda. Nilai yang didukung adalah form_post untuk post formulir HTTP dan fragment untuk fragmen URL. Untuk aplikasi web, sebaiknya gunakan response_mode=form_post untuk memastikan transfer token yang paling aman ke aplikasi Anda. Default untuk alur apa pun termasuk id_token adalah fragment.
status disarankan Nilai yang disertakan dalam permintaan, yang juga dikembalikan dalam respons token. Ini bisa berupa untai (karakter) dari konten yang Anda inginkan. Nilai unik yang dihasilkan secara acak biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs. Status ini juga digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada.
permintaan opsional Menunjukkan jenis interaksi pengguna yang diperlukan. Saat ini, satu-satunya nilai yang valid adalah 'login', 'none', dan 'consent'. prompt=login memaksa pengguna untuk memasukkan info masuk mereka pada permintaan itu, meniadakan akses menyeluruh. prompt=none adalah sebaliknya - ini memastikan pengguna tidak diberikan permintaan interaktif apa pun. Jika permintaan tidak dapat diselesaikan secara diam-diam melalui akses menyeluruh, titik akhir mengembalikan kesalahan. prompt=consent memicu dialog persetujuan OAuth setelah pengguna masuk, meminta pengguna untuk memberikan izin ke aplikasi.
login_hint opsional Anda dapat menggunakan parameter ini untuk mengisi terlebih dulu bidang nama pengguna dan alamat email halaman masuk untuk pengguna, jika Anda mengetahui nama pengguna sebelumnya. Sering kali aplikasi menggunakan parameter ini saat autentikasi ulang, setelah mengekstrak nama pengguna dari aktivitas masuk sebelumnya menggunakan klaim preferred_username.

Pada titik ini, pengguna diminta untuk memasukkan info masuk mereka dan menyelesaikan autentikasi.

Respons sampel

Respons sampel, yang dikirim ke redirect_uri yang ditentukan dalam permintaan masuk setelah pengguna mengautentikasi, bisa terlihat seperti ini:

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Parameter Deskripsi
id_token id_token yang diminta oleh aplikasi. Anda dapat menggunakan id_token untuk memverifikasi identitas pengguna dan memulai sesi dengan pengguna.
status Nilai yang disertakan dalam permintaan yang juga dikembalikan dalam respons token. Nilai unik yang dihasilkan secara acak biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs. Status ini juga digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada.

Respons kesalahan

Respons kesalahan juga dapat dikirim ke redirect_uri sehingga aplikasi dapat menanganinya dengan tepat:

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan dapat digunakan untuk bereaksi terhadap kesalahan.
error_description Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi.

Kode galat untuk kesalahan titik akhir otorisasi

Tabel berikut menjelaskan kode galat yang dapat dikembalikan dalam parameter error respons kesalahan.

Kode Kesalahan Deskripsi Tindakan Klien
invalid_request Kesalahan protokol, seperti kehilangan parameter yang diperlukan. Perbaiki dan kirim ulang permintaan. Ini adalah kesalahan pengembangan, dan biasanya tertangkap selama pengujian awal.
unauthorized_client Aplikasi klien tidak diizinkan untuk meminta kode otorisasi. Ini biasanya terjadi ketika aplikasi klien tidak terdaftar di Microsoft Azure Active Directory atau tidak ditambahkan ke penyewa Microsoft Azure Active Directory pengguna. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke Microsoft Azure Active Directory.
access_denied Pemilik sumber daya menolak persetujuan Aplikasi klien dapat memberi tahu pengguna bahwa ini tidak dapat dilanjutkan kecuali pengguna menyetujui.
unsupported_response_type Server otorisasi tidak mendukung jenis respons dalam permintaan. Perbaiki dan kirim ulang permintaan. Ini adalah kesalahan pengembangan, dan biasanya tertangkap selama pengujian awal.
server_error Server mengalami kesalahan tidak terduga. Coba lagi permintaannya. Kesalahan ini dapat diakibatkan oleh kondisi sementara. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda akibat kesalahan sementara.
temporarily_unavailable Server terlalu sibuk untuk menangani permintaan tersebut untuk sementara waktu. Coba lagi permintaannya. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda akibat kondisi sementara.
invalid_resource Sumber daya target tidak valid karena tidak ada, Microsoft Azure Active Directory tidak dapat menemukannya, atau tidak dikonfigurasi dengan benar. Ini menunjukkan bahwa sumber daya, jika ada, belum dikonfigurasi di penyewa. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke Microsoft Azure Active Directory.

Memvalidasi id_token

Hanya menerima id_token tidak cukup untuk mengautentikasi pengguna; Anda harus memvalidasi tanda tangan dan memverifikasi klaim di id_token sesuai persyaratan aplikasi Anda. Titik akhir Microsoft Azure Active Directory menggunakan JSON Web Tokens (JWTs) dan kriptografi kunci umum untuk menandatangani token dan memverifikasi keabsahannya.

Anda dapat memilih untuk memvalidasi id_token di kode klien, tetapi praktik umum adalah mengirim id_token server ujung belakang dan melakukan validasi di sana.

Anda mungkin juga ingin memvalidasi klaim tambahan tergantung pada skenario Anda. Beberapa validasi umum meliputi:

  • Memastikan pengguna/organisasi sudah mendaftar untuk aplikasi.
  • Memastikan pengguna memiliki otorisasi/hak istimewa yang sesuai menggunakan klaim wids atau roles.
  • Pastikan autentikasi dengan kekuatan tertentu sudah diberikan, seperti autentikasi multifaktor.

Setelah memvalidasi id_token, Anda dapat memulai sesi dengan pengguna dan menggunakan klaim di id_token untuk mendapatkan informasi tentang pengguna di aplikasi Anda. Informasi ini dapat digunakan untuk tampilan, rekaman, personalisasi, dll. Untuk informasi selengkapnya tentang id_tokens dan klaim, baca id_tokens Microsoft Azure Active Directory.

Mengirim permintaan keluar

Ketika Anda ingin mengeluarkan pengguna dari aplikasi, itu tidak cukup untuk menghapus cookie aplikasi Anda atau mengakhiri sesi dengan pengguna. Anda juga harus mengalihkan pengguna ke end_session_endpoint untuk keluar. Jika Anda gagal melakukannya, pengguna akan dapat mengautentikasi ulang ke aplikasi Anda tanpa memasukkan info masuk mereka lagi, karena mereka akan memiliki sesi akses menyeluruh yang valid dengan titik akhir Microsoft Azure Active Directory.

Anda cukup mengalihkan pengguna ke end_session_endpoint yang tercantum dalam dokumen metadata OpenID Connect:

GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
Parameter Jenis Deskripsi
post_logout_redirect_uri disarankan URL yang seharusnya digunakan untuk mengalihkan pengguna setelah berhasil keluar. URL ini harus cocok dengan salah satu URI pengalihan yang terdaftar untuk aplikasi Anda di portal pendaftaran aplikasi. Jika post_logout_redirect_uri tidak disertakan, pengguna akan ditampilkan pesan generik.

Single sign-out

Saat Anda mengalihkan pengguna ke end_session_endpoint, Microsoft Azure Active Directory menghapus sesi pengguna dari browser. Namun, pengguna masih dapat masuk ke aplikasi lain yang menggunakan Microsoft Azure Active Directory untuk autentikasi. Untuk mengaktifkan aplikasi tersebut untuk mengeluarkan pengguna secara bersamaan, Microsoft Azure Active Directory mengirimkan permintaan HTTP GET ke LogoutUrl terdaftar dari semua aplikasi yang saat ini digunakan oleh pengguna. Aplikasi harus menanggapi permintaan ini dengan menghapus sesi apa pun yang mengidentifikasi pengguna dan mengembalikan respons 200. Jika ingin mendukung single sign-out dalam aplikasi, Anda harus menerapkan LogoutUrl dalam kode aplikasi Anda. Anda dapat mengatur LogoutUrl dari portal Microsoft Azure:

  1. Masuk ke portal Microsoft Azure.
  2. Pilih Direktori Aktif Anda dengan mengeklik akun Anda di sudut kanan atas halaman.
  3. Dari panel navigasi sebelah kiri, pilih Microsoft Azure Active Directory, lalu pilih Pendaftaran aplikasi dan pilih aplikasi Anda.
  4. Klik Pengaturan, lalu Properti dan temukan kotak teks URL Keluar.

Akuisisi Token

Banyak aplikasi web tidak anya perlu memasukkan pengguna, tetapi juga mengakses layanan web atas nama pengguna menggunakan OAuth. Skenario ini menggabungkan OpenID Connect untuk autentikasi pengguna sekaligus memperoleh authorization_code secara bersamaan yang dapat digunakan mendapatkan access_tokens menggunakan Alur Kode Otorisasi OAuth.

Mendapatkan Token Akses

Untuk mendapatkan token akses, Anda perlu mengubah permintaan masuk dari atas:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345          // Your registered Redirect Uri, url encoded
&response_mode=form_post                              // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F        // The identifier of the protected resource (web API) that your application needs access to
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

Dengan menyertakan cakupan izin dalam permintaan dan menggunakan response_type=code+id_token, titik akhir authorize memastikan pengguna telah menyetujui izin yang ditunjukkan dalam parameter kueri scope, dan mengembalikan kode otorisasi kepada aplikasi Anda untuk ditukar dengan token akses.

Respons berhasil

Respons yang berhasil, yang dikirim ke redirect_uri menggunakan response_mode=form_post, terlihat seperti:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
Parameter Deskripsi
id_token id_token yang diminta oleh aplikasi. Anda dapat menggunakan id_token untuk memverifikasi identitas pengguna dan memulai sesi dengan pengguna.
kode Kode otorisasi yang diminta aplikasi. Aplikasi dapat menggunakan kode otorisasi untuk meminta token akses untuk sumber daya target. Authorization_codes bersifat sementara dan biasanya kedaluwarsa setelah sekitar 10 menit.
status Jika parameter status disertakan dalam permintaan, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons sama persis.

Respons kesalahan

Respons kesalahan juga dapat dikirim ke redirect_uri sehingga aplikasi dapat menanganinya dengan tepat:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication
Parameter Deskripsi
error String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan dapat digunakan untuk bereaksi terhadap kesalahan.
error_description Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi.

Untuk deskripsi kemungkinan kode kesalahan dan tindakan klien yang direkomendasikan, lihat Kode kesalahan untuk kesalahan titik akhir otorisasi.

Setelah Anda mendapatkan code otorisasi dan id_token, Anda dapat memasukkan pengguna dan mendapatkan token akses atas nama mereka. Untuk memasukkan pengguna, Anda harus memvalidasi id_tokenpersis seperti yang dijelaskan di atas. Untuk mendapatkan token akses, Anda dapat mengikuti langkah-langkah yang dijelaskan di bagian "Menggunakan kode otorisasi untuk meminta token akses" dari dokumentasi alur kode OAuth kami.

Langkah berikutnya