Fungsi LogonUserA (winbase.h)

Artikel
03/09/2024

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
LOGON32_LOGON_BATCH	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.
LOGON32_LOGON_INTERACTIVE	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.
LOGON32_LOGON_NETWORK	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.
LOGON32_LOGON_NETWORK_CLEARTEXT	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.
LOGON32_LOGON_NEW_CREDENTIALS	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).
LOGON32_LOGON_SERVICE	Menunjukkan log masuk jenis layanan. Akun yang disediakan harus mengaktifkan hak istimewa layanan.
LOGON32_LOGON_UNLOCK	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
LOGON32_PROVIDER_DEFAULT	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.
LOGON32_PROVIDER_WINNT50	Gunakan penyedia log masuk negosiasi.
LOGON32_PROVIDER_WINNT40	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