Fungsi LogonUserA (winbase.h)
Fungsi LogonUser mencoba masuk pengguna ke komputer lokal. Komputer lokal adalah komputer tempat LogonUser dipanggil. Anda tidak dapat menggunakan LogonUser untuk masuk ke komputer jarak jauh. Anda menentukan pengguna dengan nama pengguna dan domain dan mengautentikasi pengguna dengan kata sandi teks biasa . Jika fungsi berhasil, Anda menerima handel ke token yang mewakili pengguna yang masuk. Anda kemudian dapat menggunakan handel token ini untuk meniru pengguna yang ditentukan atau, dalam banyak kasus, untuk membuat proses yang berjalan dalam konteks pengguna yang ditentukan.
Sintaks
BOOL LogonUserA(
[in] LPCSTR lpszUsername,
[in, optional] LPCSTR lpszDomain,
[in, optional] LPCSTR lpszPassword,
[in] DWORD dwLogonType,
[in] DWORD dwLogonProvider,
[out] PHANDLE phToken
);
Parameter
[in] lpszUsername
Penunjuk ke string yang dihentikan null yang menentukan nama pengguna. Ini adalah nama akun pengguna untuk masuk. Jika Anda menggunakan format nama prinsipal pengguna (UPN), User@DNSDomainName, parameter lpszDomain harus NULL.
[in, optional] lpszDomain
Penunjuk ke string yang dihentikan null yang menentukan nama domain atau server yang database akunnya berisi akun lpszUsername . Jika parameter ini NULL, nama pengguna harus ditentukan dalam format UPN. Jika parameter ini adalah ".", fungsi memvalidasi akun hanya dengan menggunakan database akun lokal.
[in, optional] lpszPassword
Penunjuk ke string yang dihentikan null yang menentukan kata sandi teks biasa untuk akun pengguna yang ditentukan oleh lpszUsername. Setelah Anda selesai menggunakan kata sandi, hapus kata sandi dari memori dengan memanggil fungsi SecureZeroMemory . Untuk informasi selengkapnya tentang melindungi kata sandi, lihat Menangani Kata Sandi.
[in] dwLogonType
Jenis operasi masuk yang akan dilakukan. Parameter ini bisa menjadi salah satu nilai berikut, yang didefinisikan dalam Winbase.h.
| Nilai | Makna |
|---|---|
|
Jenis masuk ini ditujukan untuk server batch, di mana proses dapat dijalankan atas nama pengguna tanpa intervensi langsung mereka. Jenis ini juga untuk server performa yang lebih tinggi yang memproses banyak upaya autentikasi teks biasa pada satu waktu, seperti email atau server web. |
|
Jenis masuk ini ditujukan untuk pengguna yang akan secara interaktif menggunakan komputer, seperti pengguna yang masuk oleh server terminal , shell jarak jauh, atau proses serupa. Jenis masuk ini memiliki biaya tambahan untuk penembolokan informasi masuk untuk operasi yang terputus; oleh karena itu, ini tidak pantas untuk beberapa aplikasi klien/server, seperti server email. |
|
Jenis masuk ini ditujukan untuk server berkinerja tinggi untuk mengautentikasi kata sandi teks biasa. Fungsi LogonUser tidak menyimpan kredensial cache untuk jenis log masuk ini. |
|
Jenis masuk ini mempertahankan nama dan kata sandi dalam paket autentikasi, yang memungkinkan server untuk membuat koneksi ke server jaringan lain sambil meniru klien. Server dapat menerima kredensial teks biasa dari klien, memanggil LogonUser, memverifikasi bahwa pengguna dapat mengakses sistem di seluruh jaringan, dan masih berkomunikasi dengan server lain. |
|
Jenis log masuk ini memungkinkan pemanggil untuk mengkloning token saat ini dan menentukan kredensial baru untuk koneksi keluar. Sesi masuk baru memiliki pengidentifikasi lokal yang sama tetapi menggunakan kredensial yang berbeda untuk koneksi jaringan lainnya.
Jenis log masuk ini hanya didukung oleh penyedia log masuk LOGON32_PROVIDER_WINNT50. Catatan: Mulai Januari 2023, tidak dimungkinkan untuk menggunakan jenis masuk LOGON32_LOGON_NEW_CREDENTIALS dengan Akun Layanan Terkelola Grup (gMSA). |
|
Menunjukkan log masuk jenis layanan. Akun yang disediakan harus mengaktifkan hak istimewa layanan. |
|
GINA tidak lagi didukung.
Windows Server 2003 dan Windows XP: Jenis log masuk ini adalah untuk DLL GINA yang masuk ke pengguna yang akan secara interaktif menggunakan komputer. Jenis masuk ini dapat menghasilkan catatan audit unik yang menunjukkan kapan stasiun kerja tidak terkunci. |
[in] dwLogonProvider
Menentukan penyedia log masuk. Parameter ini bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Gunakan penyedia masuk standar untuk sistem. Penyedia keamanan default sedang bernegosiasi, kecuali Anda meneruskan NULL untuk nama domain dan nama pengguna tidak dalam format UPN. Dalam hal ini, penyedia default adalah NTLM. |
|
Gunakan penyedia log masuk negosiasi. |
|
Gunakan penyedia masuk NTLM. |
[out] phToken
Penunjuk ke variabel handel yang menerima handel ke token yang mewakili pengguna yang ditentukan.
Anda dapat menggunakan handel yang dikembalikan dalam panggilan ke fungsi ImpersonateLoggedOnUser .
Dalam kebanyakan kasus, handel yang dikembalikan adalah token utama yang dapat Anda gunakan dalam panggilan ke fungsi CreateProcessAsUser . Namun, jika Anda menentukan bendera LOGON32_LOGON_NETWORK, LogonUser mengembalikan token peniruan yang tidak dapat Anda gunakan di CreateProcessAsUser kecuali Anda memanggil DuplicateTokenEx untuk mengonversinya menjadi token utama.
Ketika Anda tidak lagi memerlukan handel ini, tutup dengan memanggil fungsi CloseHandle .
Mengembalikan nilai
Jika fungsi berhasil, fungsi mengembalikan bukan nol.
Jika fungsi gagal, fungsi akan mengembalikan nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.
Keterangan
Jenis masuk LOGON32_LOGON_NETWORK tercepat, tetapi memiliki batasan berikut:
- Fungsi mengembalikan token peniruan, bukan token utama. Anda tidak dapat menggunakan token ini langsung dalam fungsi CreateProcessAsUser . Namun, Anda dapat memanggil fungsi DuplicateTokenEx untuk mengonversi token ke token utama, lalu menggunakannya di CreateProcessAsUser.
- Jika Anda mengonversi token ke token utama dan menggunakannya di CreateProcessAsUser untuk memulai proses, proses baru tidak dapat mengakses sumber daya jaringan lain, seperti server jarak jauh atau printer, melalui pengalihan. Pengecualiannya adalah bahwa jika sumber daya jaringan tidak dikontrol akses, maka proses baru akan dapat mengaksesnya.
Hak istimewa SE_TCB_NAME tidak diperlukan untuk fungsi ini kecuali Anda masuk ke akun Paspor.
Akun yang ditentukan oleh lpszUsername, harus memiliki hak akun yang diperlukan. Misalnya, untuk masuk ke pengguna dengan bendera LOGON32_LOGON_INTERACTIVE, pengguna (atau grup tempat pengguna berada) harus memiliki hak akun SE_INTERACTIVE_LOGON_NAME. Untuk daftar hak akun yang memengaruhi berbagai operasi masuk, lihat Konstanta Hak Akun.
Pengguna dianggap masuk jika setidaknya ada satu token. Jika Anda memanggil CreateProcessAsUser lalu menutup token, sistem menganggap pengguna masih masuk hingga proses (dan semua proses turunan) telah berakhir.
Jika panggilan LogonUser berhasil, sistem memberi tahu penyedia jaringan bahwa masuk terjadi dengan memanggil fungsi titik masuk NPLogonNotify penyedia.
Contoh
Anda dapat membuat token LocalService dengan menggunakan kode berikut.
LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)
Catatan
Header winbase.h mendefinisikan LogonUser sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winbase.h (termasuk Windows.h) |
| Pustaka | Advapi32.lib |
| DLL | Advapi32.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk