Fungsi CredUIPromptForCredentialsA (wincred.h)
Fungsi CredUIPromptForCredentials membuat dan menampilkan kotak dialog yang dapat dikonfigurasi yang menerima informasi kredensial dari pengguna.
Aplikasi yang menargetkan Windows Vista atau Windows Server 2008 harus memanggil CredUIPromptForWindowsCredentials alih-alih fungsi ini, karena alasan berikut:
- CredUIPromptForWindowsCredentials konsisten dengan antarmuka pengguna Windows saat ini.
- CredUIPromptForWindowsCredentials lebih dapat diperluas, memungkinkan integrasi mekanisme autentikasi tambahan seperti biometrik dan kartu pintar.
- CredUIPromptForWindowsCredentials mematuhi spesifikasi Kriteria Umum.
Sintaks
CREDUIAPI DWORD CredUIPromptForCredentialsA(
[in, optional] PCREDUI_INFOA pUiInfo,
[in] PCSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] BOOL *save,
[in] DWORD dwFlags
);
Parameter
[in, optional] pUiInfo
Penunjuk ke struktur CREDUI_INFO yang berisi informasi untuk menyesuaikan tampilan kotak dialog.
[in] pszTargetName
Penunjuk ke string yang dihentikan null yang berisi nama target untuk kredensial, biasanya nama server. Untuk koneksi Sistem File Terdistribusi (DFS), string ini adalah formulir ServerName\ShareName. Parameter ini digunakan untuk mengidentifikasi informasi target saat menyimpan dan mengambil kredensial.
[in] pContext
Parameter ini dicadangkan untuk digunakan di masa mendatang. Ini harus NULL.
[in, optional] dwAuthError
Menentukan mengapa kotak dialog kredensial diperlukan. Penelepon dapat meneruskan parameter kesalahan Windows ini, dikembalikan oleh panggilan autentikasi lain, untuk memungkinkan kotak dialog mengakomodasi kesalahan tertentu. Misalnya, jika kode status kedaluwarsa kata sandi diteruskan, kotak dialog dapat meminta pengguna untuk mengubah kata sandi di akun.
[in, out] pszUserName
Penunjuk ke string yang dihentikan null yang berisi nama pengguna untuk kredensial. Jika string panjang bukan nol diteruskan, opsi Nama Pengguna dari kotak dialog telah diisi sebelumnya dengan string. Dalam kasus kredensial selain UserName/Password, format marshaled kredensial dapat diteruskan. String ini dibuat dengan memanggil CredMarshalCredential.
Fungsi ini menyalin nama yang disediakan pengguna ke buffer ini, menyalin maksimum karakter ulUserNameMaxChars . Format ini dapat dikonversi ke format UserName/Password dengan menggunakan CredUIParseUsername. Format marshaled dapat diteruskan langsung ke penyedia dukungan keamanan (SSP).
Jika bendera CREDUI_FLAGS_DO_NOT_PERSIST tidak ditentukan, nilai yang dikembalikan dalam parameter ini adalah formulir yang tidak boleh diperiksa, dicetak, atau disimpan selain meneruskannya ke CredUIParseUsername. Hasil berikutnya dari CredUIParseUsername hanya dapat diteruskan ke fungsi autentikasi sisi klien seperti WNetAddConnection atau fungsi SSP.
Jika tidak ada domain atau server yang ditentukan sebagai bagian dari parameter ini, nilai parameter pszTargetName digunakan sebagai domain untuk membentuk pasanganNama PenggunaDomainName\. Pada output, parameter ini menerima string yang berisi pasanganNama PenggunaDomainName\ tersebut.
[in] ulUserNameBufferSize
Jumlah maksimum karakter yang dapat disalin ke pszUserName termasuk karakter null yang mengakhiri.
[in, out] pszPassword
Penunjuk ke string yang dihentikan null yang berisi kata sandi untuk kredensial. Jika string panjang bukan nol ditentukan untuk pszPassword, opsi kata sandi kotak dialog akan diisi sebelumnya dengan string.
Fungsi ini menyalin kata sandi yang disediakan pengguna ke buffer ini, menyalin maksimum karakter ulPasswordMaxChars . Jika bendera CREDUI_FLAGS_DO_NOT_PERSIST tidak ditentukan, nilai yang dikembalikan dalam parameter ini adalah formulir yang tidak boleh diperiksa, dicetak, atau disimpan selain meneruskannya ke fungsi autentikasi sisi klien seperti WNetAddConnection atau fungsi SSP.
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] ulPasswordBufferSize
Jumlah maksimum karakter yang dapat disalin ke pszPassword termasuk karakter null yang mengakhiri.
[in, out] save
Penunjuk ke BOOL yang menentukan status awal kotak centang Simpan dan menerima status kotak centang Simpan setelah pengguna merespons kotak dialog. Jika nilai ini bukan NULL dan CredUIPromptForCredentials mengembalikan NO_ERROR, maka pfSave mengembalikan status kotak centang Simpan saat pengguna memilih OK dalam kotak dialog.
Jika bendera CREDUI_FLAGS_PERSIST ditentukan, kotak centang Simpan tidak ditampilkan, tetapi dianggap dipilih.
Jika bendera CREDUI_FLAGS_DO_NOT_PERSIST ditentukan dan CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX tidak ditentukan, kotak centang Simpan tidak ditampilkan, tetapi dianggap dikosongkan.
Aplikasi yang perlu menggunakan CredUI untuk meminta kredensial kepada pengguna, tetapi tidak memerlukan layanan manajemen kredensial yang disediakan oleh manajer kredensial, dapat menggunakan pfSave untuk menerima status kotak centang Simpan setelah pengguna menutup kotak dialog. Untuk melakukan ini, pemanggil harus menentukan CREDUI_FLAGS_DO_NOT_PERSIST dan CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX di dwFlags. Ketika CREDUI_FLAGS_DO_NOT_PERSIST dan CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX diatur, aplikasi bertanggung jawab untuk memeriksa *pfSave setelah fungsi kembali, dan jika *pfSaveADALAH TRUE, maka aplikasi harus mengambil tindakan yang sesuai untuk menyimpan kredensial pengguna dalam sumber daya aplikasi.
[in] dwFlags
Nilai DWORD yang menentukan perilaku khusus untuk fungsi ini. Nilai ini bisa menjadi kombinasi bitwise-OR dari nol atau lebih dari nilai berikut.
| Nilai | Makna |
|---|---|
|
Menentukan bahwa antarmuka pengguna akan ditampilkan meskipun kredensial dapat dikembalikan dari kredensial yang ada di pengelola kredensial. Bendera ini hanya diizinkan jika CREDUI_FLAGS_GENERIC_CREDENTIALS juga ditentukan. |
|
Isi kotak kombo dengan perintah untuk nama pengguna. |
|
Jangan simpan kredensial atau kotak centang tampilan. Anda dapat meneruskan CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX dengan bendera ini untuk menampilkan kotak centang Simpan saja, dan hasilnya dikembalikan dalam parameter output pfSave . |
|
Isi kotak kombo hanya dengan nama pengguna/kata sandi. Jangan tampilkan sertifikat atau kartu pintar dalam kotak kombo. |
|
Menentukan bahwa penelepon akan memanggil CredUIConfirmCredentials setelah memeriksa untuk menentukan apakah kredensial yang dikembalikan benar-benar valid. Mekanisme ini memastikan bahwa kredensial yang tidak valid tidak disimpan ke manajer kredensial. Tentukan bendera ini dalam semua kasus kecuali CREDUI_FLAGS_DO_NOT_PERSIST ditentukan. |
|
Pertimbangkan kredensial yang dimasukkan oleh pengguna sebagai kredensial generik. |
|
Beri tahu pengguna tentang kredensial yang tidak mencukupi dengan menampilkan tip balon "Masuk tidak berhasil". |
|
Jangan izinkan pengguna untuk mengubah nama pengguna yang disediakan. |
|
Isi kotak kombo hanya dengan kata sandi. Jangan izinkan nama pengguna dimasukkan. |
|
Jangan perlihatkan kotak centang Simpan , tetapi kredensial disimpan seolah-olah kotak diperlihatkan dan dipilih. |
|
Isi kotak kombo hanya dengan administrator lokal. Windows XP Home Edition: Bendera ini akan memfilter akun Administrator terkenal. |
|
Isi kotak kombo dengan sertifikat dan kartu pintar saja. Jangan izinkan nama pengguna dimasukkan. |
|
Isi kotak kombo dengan sertifikat atau kartu pintar saja. Jangan izinkan nama pengguna dimasukkan. |
|
Bendera ini bermakna hanya dalam menemukan kredensial yang cocok untuk mengisi kotak dialog terlebih dahulu, jika autentikasi gagal. Ketika bendera ini ditentukan, kredensial kartubebas tidak akan dicocokkan. Ini tidak berpengaruh saat menulis kredensial. CredUI tidak membuat kredensial yang berisi karakter kartubebas. Setiap yang ditemukan dibuat secara eksplisit oleh pengguna atau dibuat secara terprogram, seperti yang terjadi ketika koneksi RAS dibuat. |
|
Jika kotak centang dipilih, perlihatkan kotak centang Simpan dan kembalikanTRUE di parameter output pfSave , jika tidak, kembalikan FALSE. Kotak centang menggunakan nilai dalam pfSave secara default. |
|
Kredensial adalah kredensial "runas". Parameter TargetName menentukan nama perintah atau program yang sedang dijalankan. Ini hanya digunakan untuk meminta tujuan. |
|
Periksa apakah nama pengguna valid. |
Mengembalikan nilai
Nilai yang dikembalikan adalah DWORD dan bisa menjadi salah satu nilai berikut.
| Nilai | Deskripsi |
|---|---|
|
Pengguna memilih Batal. Parameter pszUserName dan pszPassword tidak berubah. |
|
Status ini dikembalikan untuk salah satu konfigurasi bendera yang tidak valid. |
|
PszTargetName adalah NULL, string kosong, atau lebih panjang dari CREDUI_MAX_DOMAIN_LENGTH, atau pUiInfo tidak NULL dan struktur CredUI_INFO yang ditujukan untuk tidak memenuhi salah satu persyaratan berikut:
|
|
Manajer kredensial tidak dapat digunakan. Biasanya, kesalahan ini ditangani dengan memanggil CredUIPromptForCredentials dan meneruskan bendera CREDUI_FLAGS_DO_NOT_PERSIST. |
|
Pengguna memilih OK. Parameter pszUserName, pszPassword, dan pfSave akan mengembalikan nilai yang di dokumentasikan sebelumnya. |
Keterangan
Fungsi CredUIPromptForCredentials membuat dan menampilkan kotak dialog modal aplikasi. Setelah kotak dialog ditampilkan dan sampai ditutup oleh pengguna atau aplikasi, tidak ada jendela lain dalam aplikasi yang dapat menjadi aktif.
Bendera CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE, dan CREDUI_FLAGS_EXCLUDE_CERTIFICATE saling eksklusif.
Jika CREDUI_FLAGS_DO_NOT_PERSIST ditentukan, pszTargetName harus ditentukan atau uiInfo-pszMessageText> dan uiInfo-pszCaption> harus ditentukan.
Bendera CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS dan CREDUI_FLAGS_GENERIC_CREDENTIALS saling eksklusif. Jika tidak ada yang ditentukan, kredensial adalah kredensial domain.
Sertifikat X509 harus memiliki nilai penggunaan kunci yang ditingkatkan (EKU) szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2) untuk ditampilkan.
Windows XP: Nilai EKU ini tidak diperlukan untuk menampilkan sertifikat X509.
Jika CREDUI_FLAGS_GENERIC_CREDENTIALS tidak ditentukan atau CREDUI_FLAGS_COMPLETE_USERNAME ditentukan, nama yang di ketik akan diperiksa sintaksisnya. Pemeriksaan sintaks menerapkan aturan yang sama seperti yang diterapkan oleh CredUIParseUserName. Jika nama yang di ketik tidak valid, pengguna akan dimintai nama yang valid. Jika bagian domain dari nama yang di ketik hilang, satu akan diberikan berdasarkan nama target.
Jika CREDUI_FLAGS_GENERIC_CREDENTIALS ditentukan dan CREDUI_FLAGS_VALIDATE_USERNAME juga ditentukan, nama yang ditik adalah sintaks yang diperiksa. Jika nama yang di ketik tidak valid, pengguna akan dimintai nama yang valid.
Jika CREDUI_FLAGS_GENERIC_CREDENTIALS ditentukan dan tidak CREDUI_FLAGS_COMPLETE_USERNAME atau CREDUI_FLAGS_VALIDATE_USERNAME ditentukan, nama yang ditik tidak diperiksa sintaksnya dengan cara apa pun.
Jika tidak CREDUI_FLAGS_PERSIST atau CREDUI_FLAGS_DO_NOT_PERSIST diatur, kotak centang Simpan ditampilkan, dan mengontrol apakah kredensial disimpan.
Mode Panggilan
- Pemanggil akan mencoba mengakses sumber daya target, memanggil credui (meneruskan deskripsi sumber daya target dan status kegagalan), memanggil CredUIParseUserName, mengakses sumber daya target lagi, lalu memanggil CredUIConfirmCredentials.
- Pemanggil dapat meminta kredensial tanpa mengakses sumber daya apa pun dengan melewati CREDUI_FLAGS_DO_NOT_PERSIST.
- Untuk kredensial generik, tidak ada paket autentikasi. Oleh karena itu, aplikasi perlu mengakses kredensial untuk melakukan autentikasi. Minta kredensial, tidak melewati CREDUI_FLAGS_ALWAYS_SHOW_UI sebelum autentikasi pertama. Antarmuka pengguna hanya akan muncul jika tidak ada kredensial di manajer kredensial. Pada semua pesan berikutnya dari dalam aplikasi, CREDUI_FLAGS_ALWAYS_SHOW_UI akan diteruskan karena kredensial di manajer kredensial jelas tidak valid untuk sumber daya tersebut.
Informasi Target adalah informasi tentang lokasi sumber daya yang akan diakses. Untuk daftar semua nama target potensial untuk sumber daya, panggil CredGetTargetInfo. CredGetTargetInfo mengembalikan informasi yang di-cache oleh paket autentikasi Negosiasi, NTLM, atau Kerberos ketika salah satu paket tersebut digunakan untuk mengautentikasi ke target bernama. CredGetTargetInfo mengembalikan beberapa atau semua nama berikut untuk target:
- Nama server NetBIOS komputer
- Nama server DNS komputer
- Nama domain NetBIOS dari domain tempat komputer berada
- Nama domain DNS dari domain tempat komputer berada
- Nama pohon DNS dari pohon tempat komputer berada
- Nama paket yang mengumpulkan informasi
Kredensial disimpan di manajer kredensial berdasarkan nama target. Setiap nama target disimpan secara umum tanpa bertabrakan dengan kredensial yang sudah disimpan di manajer kredensial. Karena kredensial disimpan berdasarkan nama target, pengguna tertentu hanya dapat memiliki satu kredensial per target yang disimpan di manajer kredensial.
Catatan
Header wincred.h mendefinisikan CredUIPromptForCredentials 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 | wincred.h |
| Pustaka | Credui.lib |
| DLL | Credui.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