Example: Using SSPI Authentication Encoding with BITS
You can use Security Support Provider Interface (SSPI) Authentication and Background Intelligent Transfer Service (BITS) methods to get the credentials from a user, encode the credentials, and set the encoded credentials on a BITS transfer job. Encoding is required to convert credentials structure into strings that can be passed to a BITS transfer job.
For more information about SSPI authentication and methods, see SSPI.
The following procedure prompts for credentials from the user by using the Negotiate security package. The program creates an authentication identity structure and populates the structure with the encoded strings that represent the user name, domain, and password of the user. Then the program creates a BITS download job and sets the encoded user name and password as the credentials for the job. The program frees the authentication identity structure after it is no longer needed.
This example uses the header and implementation defined in Example: Common Classes.
To use SSPI authentication encoding with BITS transfer jobs
- Initialize COM parameters by calling the CCoInitializer function. For more information about the CCoInitializer function, see Example: Common Classes.
- Get pointers for the IBackgroundCopyManager, IBackgroundCopyJob, IBackgroundCopyJob2 interfaces. This example uses the CComPtr Class to manage COM interface pointers.
- Create a CREDUI_INFO structure that contains information for customizing the appearance of the dialog box for the SspiPromptForCredentials Function. Then prompt for credentials from the user. For more information, see the SspiPromptForCredentials Function.
- Encode credential structure as strings that can be passed to a BITS transfer job by using the SspiEncodeAuthIdentityAsStrings function.
- Prepare a BG_AUTH_CREDENTIALS structure.
- Initialize COM process security by calling CoInitializeSecurity. BITS requires at least the IMPERSONATE level of impersonation. BITS fails with E_ACCESSDENIED if the correct impersonation level is not set.
- Obtain the initial locator to BITS by calling the CoCreateInstance function.
- Create a BITS transfer job by calling the IBackgroundCopyManager::CreateJob method.
- Get the identifier for the IBackgroundCopyJob2 interface, and call the IBackgroundCopyJob::QueryInterface method.
- Populate the BG_AUTH_CREDENTIALS structure with the encoded user name and password strings, and set the authentication scheme to Negotiate (BG_AUTH_SCHEME_NEGOTIATE).
- Use the IBackgroundCopyJob2 pointer to make requests to BITS. This program uses the IBackgroundCopyJob2::SetCredentials method to set the credentials for the BITS transfer job.
- Add files, modify properties, or resume the BITS transfer job.
- After the BITS transfer job is complete, remove the job from the queue by calling IBackgroundCopyJob::Complete.
- Finally, free the authentication identity structure by calling the SspiFreeAuthIdentity function.
The following code example demonstrates how to use SSPI Authentication Encoding with BITS transfer jobs.
#define SECURITY_WIN32
#define _SEC_WINNT_AUTH_TYPES
#include <windows.h>
#include <ntsecapi.h>
#include <bits.h>
#include <sspi.h>
#include <wincred.h>
#include <iostream>
#include <atlbase.h>
#include "CommonCode.h"
void PromptForCredentials(PWSTR pwTargetName)
{
HRESULT hr;
// If CoInitializeEx fails, the exception is unhandled and the program terminates
CCoInitializer coInitializer(COINIT_APARTMENTTHREADED);
CComPtr<IBackgroundCopyManager> pQueueMgr;
CComPtr<IBackgroundCopyJob> pJob;
CComPtr<IBackgroundCopyJob2> pJob2;
PSEC_WINNT_AUTH_IDENTITY_OPAQUE pAuthIdentityEx2 = NULL;
DWORD dwFlags = 0;
BOOL fSave = FALSE;
BOOL bReturn = TRUE;
CREDUI_INFO creduiInfo = { 0 };
creduiInfo.cbSize = sizeof(creduiInfo);
// Change the message text and caption to the actual text for your dialog.
creduiInfo.pszMessageText = pwTargetName;
creduiInfo.pszCaptionText = L"SSPIPFC title for the dialog box";
try {
// Prompt for credentials from user using Negotiate security package.
DWORD dwRet = SspiPromptForCredentials(
pwTargetName,
&creduiInfo,
0,
L"Negotiate",
NULL,
&pAuthIdentityEx2,
&fSave,
dwFlags
);
if (SEC_E_OK != dwRet)
{
// Prompt for credentials failed.
throw MyException(dwRet, L"SspiPromptForCredentials");
}
if (NULL != pAuthIdentityEx2)
{
GUID guidJob;
BG_AUTH_CREDENTIALS authCreds;
PCWSTR pwUserName = NULL;
PCWSTR pwDomainName = NULL;
PCWSTR pwPassword = NULL;
// Encode credential structure as strings that can
// be passed to a BITS job.
SECURITY_STATUS secStatus = SspiEncodeAuthIdentityAsStrings(
pAuthIdentityEx2,
&pwUserName,
&pwDomainName,
&pwPassword
);
if(SEC_E_OK != secStatus)
{
// Encode authentication identity as strings.
throw MyException(secStatus, L"SspiEncodeAuthIdentityAsStrings");
}
// Show the encoded user name and domain name.
wprintf(
L"User Name: %s\nDomain Name: %s",
pwUserName,
pwDomainName
);
//The impersonation level must be at least RPC_C_IMP_LEVEL_IMPERSONATE.
HRESULT hr = CoInitializeSecurity(
NULL,
-1,
NULL,
NULL,
RPC_C_AUTHN_LEVEL_CONNECT,
RPC_C_IMP_LEVEL_IMPERSONATE,
NULL,
EOAC_DYNAMIC_CLOAKING,
0
);
if (FAILED(hr))
{
throw MyException(hr, L"CoInitializeSecurity");
}
// Connect to BITS.
hr = CoCreateInstance(__uuidof(BackgroundCopyManager), NULL,
CLSCTX_LOCAL_SERVER,
__uuidof(IBackgroundCopyManager),
(void**) &pQueueMgr);
if (FAILED(hr))
{
// Failed to connect.
throw MyException(hr, L"CoCreateInstance");
}
// Create a job.
hr = pQueueMgr->CreateJob(
L"EncodeSample",
BG_JOB_TYPE_DOWNLOAD,
&guidJob,
&pJob
);
if(FAILED(hr))
{
// Failed to create a BITS job.
throw MyException(hr, L"CreateJob");
}
// Get IBackgroundCopyJob2 interface.
hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJob2), (void**)&pJob2);
if (FAILED(hr))
{
// Failed to get a reference to the IBackgroundCopyJob2 interface.
throw MyException(hr, L"QueryInterface(IBackgroundCopyJob2)");
}
// Create a BITS authentication structure from the encoded strings.
authCreds.Target = BG_AUTH_TARGET_SERVER;
authCreds.Scheme = BG_AUTH_SCHEME_NEGOTIATE;
authCreds.Credentials.Basic.UserName = (LPWSTR)pwUserName;
authCreds.Credentials.Basic.Password = (LPWSTR)pwPassword;
// Set the credentials for the job.
hr = pJob2->SetCredentials(&authCreds);
if (FAILED(hr))
{
// Failed to set credentials.
throw MyException(hr, L"SetCredentials");
}
// Modify the job's property values.
// Add files to the job.
// Activate (resume) the job in the transfer queue.
// Remove the job from the transfer queue.
hr = pJob->Complete();
if (FAILED(hr))
{
// Failed to complete the job.
throw MyException(hr, L"Complete");
}
}
}
catch(std::bad_alloc &)
{
wprintf(L"Memory allocation failed");
if (pJob != NULL)
{
pJob->Cancel();
}
}
catch(MyException &ex)
{
wprintf(L"Error %x occurred during operation", ex.Error);
if (pJob != NULL)
{
pJob->Cancel();
}
}
// Free the auth identity structure.
if (NULL != pAuthIdentityEx2)
{
SspiFreeAuthIdentity(pAuthIdentityEx2);
pAuthIdentityEx2 = NULL;
}
return;
}
void _cdecl _tmain(int argc, LPWSTR* argv)
{
PromptForCredentials(L"Target");
}
Related topics
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for