Fungsi LogonUserExA (winbase.h)

Fungsi LogonUserEx mencoba masuk pengguna ke komputer lokal. Komputer lokal adalah komputer tempat LogonUserEx dipanggil. Anda tidak dapat menggunakan LogonUserEx 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 kebanyakan kasus, untuk membuat proses yang berjalan dalam konteks pengguna yang ditentukan.

Sintaksis

BOOL LogonUserExA(
  [in]            LPCSTR        lpszUsername,
  [in, optional]  LPCSTR        lpszDomain,
  [in, optional]  LPCSTR        lpszPassword,
  [in]            DWORD         dwLogonType,
  [in]            DWORD         dwLogonProvider,
  [out, optional] PHANDLE       phToken,
  [out, optional] PSID          *ppLogonSid,
  [out, optional] PVOID         *ppProfileBuffer,
  [out, optional] LPDWORD       pdwProfileLength,
  [out, optional] PQUOTA_LIMITS pQuotaLimits
);

Parameter

[in] lpszUsername

Penunjuk ke string null-terminated yang menentukan nama pengguna. Ini adalah nama akun pengguna untuk masuk. Jika Anda menggunakan format nama prinsipal pengguna (UPN) , user@DNS_domain_name, 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 null-terminated 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.

[in] dwLogonProvider

Penyedia log masuk. Parameter ini bisa menjadi salah satu nilai berikut.

[out, optional] phToken

Penunjuk ke variabel handle 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, LogonUserEx mengembalikan token peniruan yang tidak dapat Anda gunakan di CreateProcessAsUser kecuali Anda memanggil DuplicateTokenEx untuk mengonversi token peniruan ke token utama.

Ketika Anda tidak lagi memerlukan handel ini, tutup dengan memanggil fungsi CloseHandle.

[out, optional] ppLogonSid

Penunjuk ke penunjuk ke pengidentifikasi keamanan (SID) yang menerima SID pengguna yang masuk.

Setelah Anda selesai menggunakan SID, bebaskan dengan memanggil fungsi LocalFree.

[out, optional] ppProfileBuffer

Penunjuk ke penunjuk yang menerima alamat buffer yang berisi profil pengguna yang masuk.

[out, optional] pdwProfileLength

Pointer ke DWORD yang menerima panjang buffer profil.

[out, optional] pQuotaLimits

Penunjuk ke struktur QUOTA_LIMITS yang menerima informasi tentang kuota untuk pengguna yang masuk.

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan nonzero.

Jika fungsi gagal, fungsi akan mengembalikan nol. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Komentar

Jenis masuk LOGON32_LOGON_NETWORK tercepat, tetapi memiliki batasan berikut:

• Fungsi mengembalikan token peniruan , bukan token utama. Anda tidak dapat menggunakan token ini secara langsung di 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 atau printer jarak jauh, melalui pengalihan. Pengecualiannya adalah bahwa jika sumber daya jaringan tidak dikontrol, 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 Hak Akses Objek Akun.

Pengguna dianggap masuk jika setidaknya ada satu token. Jika Anda memanggil CreateProcessAsUser lalu menutup token, pengguna masih masuk hingga proses (dan semua proses turunan) berakhir.

Jika panggilan LogonUserEx berhasil, sistem memberi tahu penyedia jaringan bahwa masuk terjadi dengan memanggil fungsi NPLogonNotify entry-point penyedia.

Persyaratan

Lihat juga

Kontrol Akses Klien/Server

Fungsi Kontrol Akses Klien/Server

closeHandle

CreateProcessAsUser

DuplikatTokenEx

ImpersonateLoggedOnUser

QUOTA_LIMITS