Fungsi LsaLogonUser (ntsecapi.h)

  • Artikel

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

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

Ketika tiket baru yang memberikan tiket (TGT) diperoleh dengan menggunakan kredensial sertifikat baru, maka semua TGT sistem dan tiket layanan 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 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 masuk atau memutuskan sambungan jaringan awal.
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 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 mengatur SeTcbPrivilege di komputer lokal untuk mendapatkan token peniruan identitas. Jika tidak, token identitas digunakan.
  • Pemanggil harus menjadi anggota Akses 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 pemanggil 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 pengontrol 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 mengalami 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 menjadi 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

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 ntsecapi.h
Pustaka Secur32.lib
DLL Secur32.dll

Lihat juga

Mengizinkan Akses Anonim

LsaCallAuthenticationPackage

LsaFreeReturnBuffer

LsaLookupAuthenticationPackage