Vista Win7 Credential Provider 5个例子

Windows VistaSample Credential Providers Overview ContentsTerms of Use (2)Release Notes (3)SampleCredentialProvider (3)The SampleCredentialProvider Codebase (3)Project Structure (4)Common Tasks For Extending SampleCredentialProvider (5)Tips & Tricks (6)Rebooting (7)Automating The Deployment Process (7)Developing With CredUI (8)Debugging LogonUI (9)If Your System Becomes Unstable (10)SampleCredUICredentialProvider (10)SampleAllControlsCredentialProvider (11)SampleHardwareEventCredentialProvider (13)SampleWrapExistingCredentialProvider (14)Default Tiles (17)Wrapping Existing Credential Providers (17)Credential Provider Architecture (19)Summary (19)Questions (19)Terms of UseThis code and information is provided "as is" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose.Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.Copyright (c) 2006 Microsoft Corporation. All rights reserved.Microsoft, Windows Vista, Windows XP, and Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.IntroductionIn this document, we’ll take a look at some custom Windows Vista credential provider samples. Spec ifically, we’ll cover the following topics:1. Understanding the base SampleCredentialProvider codebase.2. Common tasks for extending the base SampleCredentialProvider codebase.3. SampleCredUICredentialProvider, which supports CredUI.4. SampleAllControlsCredentialProvider, which exposes each possible UIcontrol.5. SampleHardwareEventCredentialProvider, which supports asynchronousevents.6. SampleWrapExistingCredentialProvider, which wraps the defaultusername/password credential provider in Windows Vista.Release NotesWe previously released a version of SampleCredentialProvider. This release of the samples has the following changes∙ 4 new samples showing uses of additional features of the credential provider model∙Updated the base samplecredentialprovider in the following ways o Fixed the issue where the release configuration wouldn’t buildo Built & tested in on x64freo Fixed a bug in the implementation of GetBitmapValue that caused the tiles not to show up on some machines. NOTE: Everyoneshould make sure they pick up this fix.o Added an implementation of SetSerialization SampleCredentialProviderOut of the box, SampleCredentialProvider provides a DLL project that exposes the two COM interfaces required to develop a credential provider: ICredentialProvider and ICredentialProviderCredential. ICredentialProvider exposes the functionality to enumerate available credentials, and ICredentialProviderCredential exposes the functionality required for each specific credential during the authentication process.The SampleCredentialProvider CodebaseThe SampleCredentialProvider project provides a working baseline credential provider. This sample is hardcoded to expose two accounts: Administrator and Guest. The following screenshot shows what this might look like on a domain joined machine.Project StructureThe SampleCredentialProvider project includes a small set of files, each with their own purpose:Common Tasks For Extending SampleCredentialProviderSince SampleCredentialProvider provides a great baseline for developing custom providers, it is recommended that you customize it to meet your needs, rather than starting from scratch. The following steps will walk you through the process of customizing the SampleCredentialProvider project that is common to all extensions.W e’ll use “MyCredentialProvider” as the new project name, so be sure to change it to reflect the name you want to use. We’re also not going to rename any of the folders or files to reflect the name unless it is required to build successfully, so this may be someth ing you choose to do once you’re comfortable with the codebase.Please note that these samples are intended to be run against the February CTP release of Vista (build 5308). They should be compiled against the SDK for the February CTP and run on the matching build.1. Set up Visual Studio 2005 in Tools | Options to use the executables, includes,and libs from the SDK instead of the ones shipped with VS. For more info on how to do this, see ReleaseNotes.Htm in the root of the SDK directory.2. In the SampleCredentialProvider folder, double-click theSampleCredentialProvider.sln to open it in Visual Studio 2005.3. In the Solution Explorer, right-click the SampleCredentialProvider projectnode and select Rename. Change the name to “MyCredentialProvider” and press Enter to lock in.4. In the Solution Explorer, right-click the MyCredentialProvider project nodeand select Properties. This will launch the MyCredentialProvider Property Pages dialog.5. In the left tree view, select the Configuration Properties | C/C++ node.6. Make sure the path to your Vista SDK include directory is included inAdditional Include Directories. On a default install it ends up at “C:\Program Files\Microsoft SDKs\Windows\v1.0\Include”.7. In the left tree view, select the Configuration Properties | Linker node todisplay the general properties of the linker configuration.8. Make sure the path to your Vista SDK library directory is included inAdditional Library Directories. On a default install it ends up at “C:\Program Files\Microsoft SDKs\Windows\v1.0\Lib".9. Press OK to dismiss the dialog.10. Open samplecredentialprovider.def. Change“SAMPLECREDENTIALPROVIDER.DLL” to“MYCREDENTIALPROVIDER.DLL”. Save samplecredentialprovider.def. 11. Open guid.h. Replace the GUID in DEFINE_GUID with a unique one. Youcan generate a unique GUID from Tools | Create GUID. Be sure toremember it for later. Save guid.h.12. Open Register.reg in notepad or Visual Studio (do not execute it in Explorer).Replace the GUIDs in each registry key with the one created in the last step.Also change “sampleprovider” to “MyCredentialProvider” as well as"SampleCredentialProvider.dll" to "MyCredentialProvider.dll". SaveRegister.reg.13. Open Unregister.reg in notepad or Visual Studio (do not execute it inExplorer). Replace the GUID in the registry key with the one used in theRegister.reg. Save Unregister.reg.14. Select Build | Build Solution. If there are any build errors, review the stepsabove.15. Copy the freshly built MyCredentialProvider.dll to the System32 directory ofthe test machine.16. Copy Register.reg to the test machine and run it from Explorer to register thecredential provider.17. From the Start Menu, select the option to switch users.18. The login screen should now have an extra Administrator and Guestaccount. If all you see is one large tile, click Switch User to see the list of tiles.19. You should be able to log in using the newly created Administrator accounttile. The Guest account may or may not be enabled due to the securitysettings of your system.20. If you want to remove the sample, copy Unregister.reg to the test machineand run it to unregister the credential provider.Tips & TricksThe following are some tips & tricks that can help you during the development cycle. These are useful to keep in mind when reviewing the other samples covered later in this document.RebootingWhen rebooting the test machine, it is highly recommended that you unregister the credential provider you are working on (unless you are specifically testing its behavior during the reboot itself).Credential providers that are registered during boot are locked by the operating system and cannot be overwritten. If you leave a credential provider registered during a reboot, you will not be able to overwrite it with a new version until you unregister it and reboot once again. As a result, it’s a good practice to unregister before each reboot to save effort.Once the system has booted, you can register and unregister credential providers without them being locked by Windows (unless they are actively in use). There are a few other possibilities to simplify updating binaries:∙You may choose to set up a dual boot system with a safe OS (like Windows XP) on one partition and your Windows Vista installation onanother partition. Then when you need to update your credential providerdll, you can boot into the safe OS, replace the dll (since it won’t be lockedin the safe OS) and then reboot into your Windows Vista installation to test your changes.∙ A quicker “use at your own risk” tactic is to run “kill.exe logonUI.exe” from an elevated command prompt, copy the updated binary over, then log out(which will create a new session with a new logonUI.exe)Automating The Deployment ProcessIf you are developing on a test machine to begin with, you can automate the DLL deployment process of by adding a Post-Build Event that automatically copiesthe output DLL to the System32 directory. For example, you can go to the Configuration Properties | Build Events | Post-Build Event tab of the project’s Property Pages dialog and set the following for Command Line:copy "$(OutDir)\$(ProjectName).dll" %systemroot%\system32 /YIf you do this and the Post-Build Event fails during a build, it is most likely due to the fact that the DLL is still loaded and cannot be overwritten on the drive, most likely because it was a registered provider during boot. However, be careful when performing a second build since the Post-Build Event only occurs after a successful build, and Visual C++ will skip the build process if the binaries are already up-to-date. As a result, you may want to edit one file in the project (such as by adding and deleting a space) before invoking the build again.If the Post-Build Event continues to fail due to the DLL being loaded, run the Unregister.reg file from Explorer on the target machine, which will unregister the DLL as a credential provider, and then reboot. After rebooting, run theRegister.reg file from Explorer to register the DLL as a credential provider once again.Developing With CredUIAlthough you may not want to support the CredUI scenario in your final credential provider, it is recommended that you use it during development and debugging if you are developing on the test machine. Since the CredUI scenario runs from a normal desktop session, you’ll be able to attach the Visual St udio debugger to it at runtime, drastically simplifying the process of development and testing.To do this:1. Create a new Win32 console project in Visual Studio.2. Update the main function of your new project to make a call toCredUIPromptForWindowsCredentials, such as:#include"stdafx.h"#include<windows.h>#include<WinCred.h>int _tmain(int argc, _TCHAR* argv[]){BOOL save = false;DWORD authPackage = 0;LPVOID authBuffer;ULONG authBufferSize = 0;CREDUI_INFO credUiInfo;credUiInfo.pszCaptionText = TEXT("My caption");credUiInfo.pszMessageText = TEXT("My message");credUiInfo.cbSize = sizeof(credUiInfo);credUiInfo.hbmBanner = NULL;credUiInfo.hwndParent = NULL;CredUIPromptForWindowsCredentials(&(credUiInfo), 0, &(authPackage), NULL, 0, &authBuffer, &authBufferSize, &(save), 0);}3. Update the project to link against CredUI.lib. You may need to update your“Additional Include Directories” and “Additional Library Directories” to point to the Windows Vista SDK from the proje ct’s property pages dialog.4. Add your credential provider project to the solution.5. Build the credential provider and make sure the latest version is deployed tothe System32 directory and is registered as a credential provider.6. Set breakpoints, etc, and then run the console app in debug mode. Yourbreakpoints should get hit as appropriate afterCredUIPromptForWindowsCredentials is called from the console app.Debugging LogonUIIn short: hook up kd between your test machine and your debugging machine and then pipe ntsd over kd for logonUI. There’s a fair amount of info on how to do this on the web (although not specifically for logonUI). But here’s some basic pointers.1. Install the debugger package(/whdc/devtools/debugging/default.mspx)2. Get kd set up between the two computers (for more info look on the web or MSDN)a. Hook up your debug cableb. On the debugee machine, run something like the following (change commandline arguments as necessary)i. Bcdedit –debug onii. Bcdedit –dbgsettings serial debugport:1 baudrate:115200c. Reboot debuggeed. On debugger machine, run something likei. Kd.exe –r –k com:port=com1,baud=1152003. Copy symbols that you will need locally to the box since NTSD won’t have access to thenetwork4. Create a key named logonui.exe under HKLM\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\Image File Execution Options5. In the logonui.exe key, create a string value named Debuggera. Populate that value with the path to ntsd.exe on your machine, for exampleC:\debuggers\ntsd.exe -d -gG -y <path to local symbols> (space between –y andpath required)b. –d pipes the NTSD output to KDc. –g ignores the initial startup breakpoint in the process (if you want the process tobreak instantly when first executed to set BPs, do not set the small g)d. –G ignores the termination breakpoint, so the process will exit quietlye. –y sets the local symbol path on the debugee for NTSD6. Breaking in when a .DLL loads (not required, but good to know if needed)a. Follow all of the steps above for the executable that loads the .dll, but do not setthe small g flag, then when the process starts, NTSD will break inb. Type sxeld <dll name>c. Then g the debugger and NTSD will break in on load of that dll and you can setbreakpoints, etc.If Your System Becomes UnstableDuring the process of credential provider development, there is a good possibility that you might mess up the credential providers, possibly even crashing LogonUI. Don’t Panic.Typically, you can reboot Windows in safe mode (repeatedly tap F8 during early boot for the menu to do this). From safe mode you should be able to log in using the normal password provider, at which point you can unregister the offending credential provider.The other thing you might do is to accidentally unregister one or more of the built-in credential providers by deleting its key from the registry. For reference, here are the keys fromHKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Authentication\Credential Providers:You should be able to reenter them after rebooting in safe mode. SampleCredUICredentialProviderWindows Vista introduces CredUIPromptForWindowsCredentials, which can be thought of as the next generation of CredUIPromptForCredentials (although CredUIPromptForCredentials is still maintained for backwards compatibility). Unlike CredUIPromptForCredentials, CredUIPromptForWindowsCredentials relies on the same credential providers used by the login screen. While implementing these credential providers are fundamentally the same, there isone place you’ll need to make a decision regarding how your credential provider works.The implementation of CSampleProvider::SetUsageScenario contains everything we need to add support for CredUI. This method is called with a specific usage scenario (a CREDENTIAL_PROVIDER_USAGE_SCENARIO), which asks the credential provider if it supports it. By default, SampleCredentialProvider doesnot support the CPUS_CREDUI usage scenario, which means that an applicationusing CredUIPromptForWindowsCredentials will not be able to access credentials provided through it. However, we have changed this by having requests for the CPUS_CREDUI scenario treated in the same way asCPUS_LOGON.HRESULT CSampleProvider::SetUsageScenario(CREDENTIAL_PROVIDER_USAGE_SCENARIO cpus,DWORD dwFlags){UNREFERENCED_PARAMETER(dwFlags);HRESULT hr;switch (cpus){case CPUS_LOGON:case CPUS_UNLOCK_WORKSTATION:// If we didn’t want CredUI to be supported, we would return// E_NOTIMPL if this request was for CPUS_CREDUI.case CPUS_CREDUI:hr = _EnumerateCredentials();break;case CPUS_CHANGE_PASSWORD:hr = E_NOTIMPL;break;default:hr = E_INVALIDARG;break;}return hr;}SampleAllControlsCredentialProviderThe SampleAllControlsCredentialProvider project illustrates the usage of each of the nine UI control available to credential providers. Here’s an example of what you’ll see when you run this sample from LogonUI:Note that the Cancel button is automatically inserted by LogonUI.One of the nice things about this sample is that it differs only slightly from the base sample credential provider discussed earlier. Specifically, the key areas changed are in Common.h and CSampleCredential.h.In Common.h, we’ve added mo re controls to the SAMPLE_FIELD_ID enumeration, as well as respective entries for s_rgFieldStatePairs ands_rgCredProvFieldDescriptors. As you’ll see from the screenshots above, only the “tile image” and “large text” are configured to display in both selec ted and deselected mode, whereas the “small text” is configured to only appear when the tile is deselected. All other controls appear only in the selected tile. To change this behavior, modify the second member of the s_rgFieldStatePairs (it’s a CREDENTIAL_PROVIDER_FIELD_INTERACTIVE_STATE).In addition to the new fields in Common.h, it’s necessary to add in support for each type of control to the CSampleCredential.cpp implementation. By default, the base sample only implements support for the String and Bitmap methods, such as GetStringValue, etc. Since those are the only types of controls used in the sample, it was fine to return E_NOTIMPL from the unused control methods, such as GetCheckboxValue. However, since we’re using these controls now, we’ve implem ented support for getting and setting their respective values.SampleHardwareEventCredentialProviderA common scenario for custom credentials involves external events, such as the arrival of a message generated by a fingerprint scanner. The SampleHardwareEventCredential sample illustrates processing asynchronous events such as these.When run, this sample displays a window with a single button. This window is designed to emulate an external element that has two states: connected and disconnected. When disconnected, the credential merely displays a large text asking the user to connect:By pressing the “Press to connect” but ton, the credential provides different controls, allowing the user to log in:Since you cannot change the controls used by a credential from an event, this sample actually implements two credentials: a “please connect” m essage credential and an actual “log in” credential, which is effectively the same as the CSampleCredential from the SampleCredentialProvider project. Depending on the state of the connection emulator window, the provider displays the proper one.The window is created on a separate thread, which provides it with a way to pump messages while the provider thread is managed by an external authority. When the button is pressed, the window thread calls in to the provider, asking it to re-enumerate its credentials by calling the CredentialsChanged method on the ICredentialProviderEvents pointer it received in an earlier Advise call:void CSampleProvider::OnConnectStatusChanged(){if (this->_pcpe != NULL){this->_pcpe->CredentialsChanged(this->_upAdviseContext);}}When the credentials are enumerated, methods like GetCredentialCount and GetFieldDescriptorCount are called again. In turn, the provider checks the state of the connection emulator and provides data for the appropriate credential. In either case, exactly one credential is always displayed. Note that we’re calling CredentialsChanged from a separate thread, which is okay to do. However, be extra careful when trying to call other methods from the separate thread.While this sample illustrates using a button on a window as an event, you could customize CCommandWindow::ThreadProc to look for any event you need, provided it’s supported on the secure desktop. SampleWrapExistingCredentialProviderIn some scenarios, you may find that an existing credential provider fits almost all of your needs, with the exception of an additional field or two you need to retrieve from the user. It would be a shame to have to re-implement the functionality ofthe existing credential provider, so this sample illustrates the process of wrapping an existing credential provider and extending it with two additional fields. Please note that encapsulation (or "wrapping") should be used sparingly. It is not a one size fits all replacement for the GINA chaining behavior. Unlike GINA chaining, the behavior you add only applies if the user clicks on your credential tile and does not apply if they click on another credential tile. Encapsulation is only done explicitly and should only be done when you know exactly what the behavior of the wrapped credprov is. It should be used when you want to extend the credential information that the wrapped credprov is getting. If you merely want to do something extra with the credentials gathered by another credprov, then a network provider is likely more suited to your needs than a credential provider.In our scenario, we simply attached an extra small text and combobox to the existing password provider’s credentials. We’ll let the existing credential provider decide how many credentials to enumerate, how to enumerate them, and how to authenticate. We’ll also let it deal with the behavior for the controls it defines. Credential providers are COM objects, so they can be created and managed just like any other COM object. In our scenario, we use theCLSID_PasswordCredentialProvider found in CredentialProvider.h to instantiate the provider, and then we proxy most of the calls through to it, returning theresults as though they were our own. However, if we receive calls related to our specific extensions, we handle those ourselves.Since we don’t want to limit the functionality of the wrapped credential, it’s important to avoid assumptions where possible. For example, we don’t use a checkbox in our extension, but it is possible that the underlying credential may (if not now, then possibly sometime in the future). As a result, calls to methods we don’t do anything for should still be passed along to the wrapped credential. For example:HRESULT hr = E_NOTIMPL;if (this->_pInnerCredential != NULL){// If the field is in the wrapped credential, pass it along.if (dwFieldID < this->_dwInnerDescriptorCount){hr = this->_pInnerCredential->GetCheckboxValue(dwFieldID, pbChecked, ppwzLabel);}}return hr;In some cases, we do handle calls that our wrapped credential needs as well. Fortunately, we can use the dwFieldID parameter to determine whether the referenced fields are ours or theirs. Since our sample appends controls to the wrapped credential, we can perform a simple check to see if the field is ours or theirs. For example:HRESULT hr = E_NOTIMPL;if (this->_pInnerCredential != NULL){// If the field is in the wrapped credential, pass it along.if (dwFieldID < this->_dwInnerDescriptorCount){hr = this->_pInnerCredential->GetStringValue(dwFieldID, ppwz);}// Otherwise, offset into the array to account for wrapped fields // and handle it ourselves.else{dwFieldID -= this->_dwInnerDescriptorCount;if (dwFieldID < SFI_NUM_FIELDS){hr = SHStrDupW(this->_rgFieldStrings[SFI_I_WORK_IN_STATIC],ppwz);}else{hr = E_INVALIDARG;}}}return hr;However, if you decide to insert controls between controls in the wrapped credential, you’ll need to be extra careful to track which field IDs are yours and which are theirs.For some well-known credenti al fields, such as the password provider’s password field, you can determine their location by checking the guidFieldType property of their CREDENTIAL_PROVIDER_FIELD_DESCRIPTOR. For example, password field’s CLSID is CPFG_LOGON_PASSWORD. More well-known CLSIDs are available in shlguid.h.Default TilesA Credential Provider may specify a default tile when queried regarding the number of tiles it intends to return. Although this is straightforward from the perspective of each individual Credential Provider, developers should keep in mind that LogonUI will not necessarily treat their tile as the default in all cases. The Credential Provider most recently used for interactive logon will receive preference when multiple providers return a default tile. In other words, when two or more providers return a default tile, the tile specified by the Credential Provider last used to log on will be displayed in zoomed view. This behavior does not occur in a remote session because the most recently used Credential Provider is not saved.Credential Providers may also specify default tiles for the CredUI usage scenario. The default tile in this scenario will receive focus when CredUI appears to the user. CredUI resolves multiple default tile conflicts using the same logic as LogonUI. There is no way for a Credential Provider to determine if other providers specify a default tile.The default tile provided by the Credential Provider last used to successfully logon does not need to be the same tile used during the previous logon. The Credential Provider is free to specify any of its tiles when it enumerates the default.Wrapping Existing Credential ProvidersAlthough Microsoft provides a wrapped Credential Provider sample, it is very important that all third parties proceed with extreme caution when implementing a wrapped provider. As long as instantiating multiple instances of the wrapped Credential Provider does not cause problems, wrapping is a safe technique and allows third party developers to avoid rewriting code. For instance, if the wrapped Credential Provider stores anything globally there may be issues creating two instances. The Microsoft in-box providers should be safe to wrap by third parties.。