Fungsi LsaLogonUser (ntsecapi.h)

Artikel
09/29/2022

Fungsi LsaLogonUser mengautentikasi data masuk prinsip keamanan dengan menggunakan informasi kredensial yang disimpan.

Jika autentikasi berhasil, fungsi ini membuat sesi masuk baru dan mengembalikan token pengguna.

Ketika tiket pemberian tiket (TGT) baru diperoleh dengan menggunakan kredensial sertifikat baru, maka semua TGT dan tiket layanan sistem dihapus menyeluruh. Setiap tiket layanan pengguna yang merupakan identitas campuran juga dibersihkan.

Sintaks

NTSTATUS LsaLogonUser(
  [in]           HANDLE              LsaHandle,
  [in]           PLSA_STRING         OriginName,
  [in]           SECURITY_LOGON_TYPE LogonType,
  [in]           ULONG               AuthenticationPackage,
  [in]           PVOID               AuthenticationInformation,
  [in]           ULONG               AuthenticationInformationLength,
  [in, optional] PTOKEN_GROUPS       LocalGroups,
  [in]           PTOKEN_SOURCE       SourceContext,
  [out]          PVOID               *ProfileBuffer,
  [out]          PULONG              ProfileBufferLength,
  [out]          PLUID               LogonId,
  [out]          PHANDLE             Token,
  [out]          PQUOTA_LIMITS       Quotas,
  [out]          PNTSTATUS           SubStatus
);

Parameter

[in] LsaHandle

Handel yang diperoleh dari panggilan sebelumnya ke LsaRegisterLogonProcess.

Pemanggil diperlukan untuk memiliki SeTcbPrivilege hanya jika satu atau beberapa hal berikut ini benar:

Paket Subauthentication digunakan.
KERB_S4U_LOGON digunakan, dan pemanggil meminta token peniruan.
Parameter LocalGroups bukan NULL.

Jika SeTcbPrivilege tidak diperlukan, panggil LsaConnectUntrusted untuk mendapatkan handel.

[in] OriginName

String yang mengidentifikasi asal upaya masuk. Untuk informasi selengkapnya, lihat Keterangan.

[in] LogonType

Nilai enumerasi SECURITY_LOGON_TYPE yang menentukan jenis log masuk yang diminta. Jika LogonType interaktif atau Batch, token utama dihasilkan untuk mewakili pengguna baru. Jika LogonType adalah Jaringan, token peniruan akan dihasilkan.

[in] AuthenticationPackage

Pengidentifikasi paket autentikasi yang akan digunakan untuk autentikasi. Anda dapat memperoleh nilai ini dengan memanggil LsaLookupAuthenticationPackage.

[in] AuthenticationInformation

Penunjuk ke buffer input yang berisi informasi autentikasi, seperti nama pengguna dan kata sandi. Format dan isi buffer ini ditentukan oleh paket autentikasi.

Parameter ini dapat menjadi salah satu struktur buffer input berikut untuk paket autentikasi MSV1_0 dan Kerberos.

Nilai	Makna
MSV1_0_INTERACTIVE_LOGON MSV1_0	Mengautentikasi masuk pengguna interaktif. Anggota LogonDomainName, UserName, dan Password dari struktur MSV1_0_INTERACTIVE_LOGON harus menunjuk ke buffer dalam memori yang berdampingan dengan struktur itu sendiri. Nilai parameter AuthenticationInformationLength harus mempertimbangkan panjang buffer ini.
KERB_INTERACTIVE_LOGON Kerberos	Mengautentikasi masuk pengguna interaktif.
KERB_TICKET_LOGON Kerberos	Mengautentikasi pengguna pada log masuk jaringan awal atau memutuskan sambungan.
KERB_TICKET_UNLOCK_LOGON Kerberos	Mengautentikasi pengguna pada refresh tiket, variasi log masuk buka kunci stasiun kerja normal.
KERB_CERTIFICATE_LOGON Kerberos	Mengautentikasi pengguna menggunakan log masuk kartu pintar interaktif.
KERB_CERTIFICATE_S4U_LOGON Kerberos	Mengautentikasi pengguna menggunakan layanan untuk masuk pengguna (S4U).
KERB_CERTIFICATE_UNLOCK_LOGON Kerberos	Mengautentikasi pengguna untuk membuka kunci stasiun kerja yang telah dikunci selama sesi masuk kartu pintar interaktif.
KERB_SMARTCARD_LOGON Kerberos	Mengautentikasi log masuk kartu pintar pengguna menggunakan LOGON32_PROVIDER_WINNT50 atau LOGON32_PROVIDER_DEFAULT.
KERB_SMARTCARD_UNLOCK_LOGON Kerberos	Mengautentikasi pengguna untuk membuka kunci stasiun kerja yang telah dikunci selama sesi masuk kartu pintar.
KERB_S4U_LOGON Kerberos	Mengautentikasi pengguna menggunakan permintaan klien S4U. Untuk delegasi yang dibatasi, panggilan ke LsaLogonUser tidak diperlukan jika klien masuk menggunakan paket autentikasi mode LSA. Pada sistem operasi Windows, ini termasuk Kerberos, NTLM, Saluran Aman, dan Digest. Agar panggilan ini berhasil, hal berikut harus benar: Pemanggil harus merupakan akun domain (ini termasuk LOCAL_SYSTEM jika komputer adalah anggota domain). Jika menggunakan akun layanan, akun harus memiliki SeTcbPrivilege yang diatur di komputer lokal untuk mendapatkan token peniruan identitas. Jika tidak, token identitas digunakan. Penelepon harus menjadi anggota Akses Yang Kompatibel Pra-Windows 2000 atau memiliki akses baca ke keanggotaan grup klien. Keanggotaan dalam grup Akses Otorisasi Windows menjamin akses baca ke keanggotaan grup klien. Untuk informasi tentang cara mengonfigurasi grup Akses Otorisasi Windows, lihat Pangkalan Pengetahuan Microsoft. Anggota ClientUpn dan ClientRealm dari struktur KERB_S4U_LOGON harus menunjuk ke buffer dalam memori yang berdampingan dengan struktur itu sendiri. Nilai parameter AuthenticationInformationLength harus mempertimbangkan panjang buffer ini.
MSV1_0_LM20_LOGON MSV1_0	Memproses paruh kedua dari log masuk protokol NTLM 2.0. Paruh pertama dari jenis masuk ini dilakukan dengan memanggil LsaCallAuthenticationPackage dengan pesan MsV1_0Lm20ChallengeRequest . Untuk informasi selengkapnya, lihat deskripsi MsV1_0Lm20ChallengeRequest di MSV1_0_PROTOCOL_MESSAGE_TYPE. Jenis masuk ini dapat menggunakan paket subauthentication.
MSV1_0_SUBAUTH_LOGON MSV1_0	Mengautentikasi pengguna dengan subautentikasi.

Untuk informasi selengkapnya tentang buffer yang digunakan oleh paket autentikasi lainnya, lihat dokumentasi untuk paket autentikasi tersebut.

[in] AuthenticationInformationLength

Panjangnya, dalam byte, dari buffer AuthenticationInformation .

[in, optional] LocalGroups

Daftar pengidentifikasi grup tambahan untuk ditambahkan ke token pengguna yang diautentikasi. Pengidentifikasi grup ini akan ditambahkan, bersama dengan grup default WORLD dan grup jenis masuk (Interaktif, Batch, atau Jaringan), yang secara otomatis disertakan dalam setiap token pengguna.

[in] SourceContext

Struktur TOKEN_SOURCE yang mengidentifikasi modul sumber—misalnya, manajer sesi—dan konteks yang mungkin berguna untuk modul tersebut. Informasi ini disertakan dalam token pengguna dan dapat diambil dengan memanggil GetTokenInformation.

[out] ProfileBuffer

Penunjuk ke penunjuk kekosongan yang menerima alamat buffer output yang berisi informasi autentikasi, seperti shell masuk dan direktori beranda.

Parameter ini dapat menjadi salah satu struktur buffer output berikut untuk paket autentikasi MSV1_0 dan Kerberos.

Nilai	Makna
MSV1_0_INTERACTIVE_PROFILE MSV1_0	Profil masuk pengguna interaktif.
KERB_TICKET_PROFILE Kerberos	Masuk, putuskan sambungan, dan output autentikasi refresh tiket.
MSV1_0_LM20_LOGON MSV1_0	Output saat memproses paruh kedua dari log masuk protokol NTLM 2.0.
MSV1_0_LM20_LOGON_PROFILE MSV1_0	Output saat menggunakan autentikasi dengan subautentikasi.

Untuk informasi selengkapnya tentang buffer yang digunakan oleh paket autentikasi lainnya, lihat dokumentasi untuk paket autentikasi tersebut.

Ketika buffer ini tidak lagi diperlukan, aplikasi panggilan harus membebaskan buffer ini dengan memanggil fungsi LsaFreeReturnBuffer .

[out] ProfileBufferLength

Penunjuk ke ULONG yang menerima panjang, dalam byte, dari buffer profil yang dikembalikan.

[out] LogonId

Penunjuk ke buffer yang menerima LUID yang secara unik mengidentifikasi sesi masuk. LUID ini ditetapkan oleh pengendali domain yang mengautentikasi informasi masuk.

[out] Token

Penunjuk ke handel yang menerima token pengguna baru yang dibuat untuk sesi ini. Setelah Anda selesai menggunakan token, lepaskan dengan memanggil fungsi CloseHandle .

[out] Quotas

Ketika token utama dikembalikan, parameter ini menerima struktur QUOTA_LIMITS yang berisi batas kuota proses yang ditetapkan ke proses awal pengguna yang baru masuk.

[out] SubStatus

Jika log masuk gagal karena pembatasan akun, parameter ini menerima informasi tentang mengapa log masuk gagal. Nilai ini diatur hanya jika informasi akun pengguna valid dan masuk ditolak.

Parameter ini dapat menjadi salah satu nilai SubStatus berikut untuk paket autentikasi MSV1_0.

Nilai	Makna
STATUS_INVALID_LOGON_HOURS	Akun pengguna memiliki batasan waktu dan tidak dapat digunakan untuk masuk saat ini.
STATUS_INVALID_WORKSTATION	Akun pengguna memiliki batasan stasiun kerja dan tidak dapat digunakan untuk masuk dari stasiun kerja saat ini.
STATUS_PASSWORD_EXPIRED	Kata sandi akun pengguna telah kedaluwarsa.
STATUS_ACCOUNT_DISABLED	Akun pengguna saat ini dinonaktifkan dan tidak dapat digunakan untuk masuk.

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan STATUS_SUCCESS.

Jika fungsi gagal, fungsi mengembalikan kode NTSTATUS , yang bisa menjadi salah satu nilai berikut.

Nilai	Deskripsi
STATUS_QUOTA_EXCEEDED	Kuota memori penelepon tidak cukup untuk mengalokasikan buffer output yang dikembalikan oleh paket autentikasi.
STATUS_ACCOUNT_RESTRICTION	Akun pengguna dan kata sandi sah, tetapi akun pengguna memiliki batasan yang mencegah masuk saat ini. Untuk informasi selengkapnya, lihat nilai yang disimpan dalam parameter SubStatus .
STATUS_BAD_VALIDATION_CLASS	Informasi autentikasi yang diberikan tidak dikenali oleh paket autentikasi.
STATUS_LOGON_FAILURE	Upaya masuk gagal. Alasan kegagalan tidak ditentukan, tetapi alasan umum termasuk nama pengguna yang salah eja dan kata sandi yang salah eja.
STATUS_NO_LOGON_SERVERS	Tidak ada pengendali domain yang tersedia untuk melayani permintaan autentikasi.
STATUS_NO_SUCH_PACKAGE	Paket autentikasi yang ditentukan tidak dikenali oleh LSA.
STATUS_PKINIT_FAILURE	Klien Kerberos menerima sertifikat KDC yang tidak valid. Untuk masuk perangkat, validasi KDC yang ketat diperlukan, sehingga KDC harus memiliki sertifikat yang menggunakan templat "Autentikasi Kerberos" atau yang setara. Selain itu, sertifikat KDC dapat kedaluwarsa, dicabut, atau klien berada di bawah serangan aktif mengirim permintaan ke server yang salah.
STATUS_PKINIT_CLIENT_FAILURE	Klien Kerberos menggunakan sertifikat sistem yang tidak valid. Untuk masuk perangkat, harus ada nama DNS. Selain itu, sertifikat sistem dapat kedaluwarsa atau sertifikat yang salah dapat dipilih.

Untuk informasi selengkapnya, lihat Nilai Pengembalian Fungsi Kebijakan LSA.

Fungsi LsaNtStatusToWinError mengonversi kode NTSTATUS ke kode kesalahan Windows.

Keterangan

Parameter OriginName harus menentukan informasi yang bermakna. Misalnya, mungkin berisi "TTY1" untuk menunjukkan terminal satu atau "NTLM - simpul jarak jauh JAZZ" untuk menunjukkan masuk jaringan yang menggunakan NTLM melalui simpul jarak jauh yang disebut "JAZZ".

Anda harus memanggil LsaLogonUser secara terpisah untuk memperbarui kredensial perangkat PKINIT untuk LOCAL_SYSTEM dan NETWORK_SERVICE. Ketika tidak ada kredensial perangkat PKINIT, panggilan yang berhasil tidak melakukan operasi. Ketika ada kredensial perangkat PKINIT, panggilan yang berhasil membersihkan kredensial perangkat PKINIT sehingga hanya kredensial kata sandi yang tersisa.

Persyaratan


Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	ntsecapi.h
Pustaka	Secur32.lib
DLL	Secur32.dll

Lihat juga

Memperbolehkan Akses Anonim

LsaCallAuthenticationPackage

LsaFreeReturnBuffer

LsaLookupAuthenticationPackage