Microsoft KB Archive/170620

= How to manage computer domain membership programmatically on Windows NT =

Article ID: 170620

Article Last Modified on 11/21/2006

-

APPLIES TO


 * Microsoft Win32 Application Programming Interface, when used with:
 * Microsoft Windows NT 4.0

-



This article was previously published under Q170620



SUMMARY
You can use the Network utility in Control Panel to control the Windows NT domain membership for a Windows NT-based computer. By clicking the Change button, you can move the computer from one workgroup or domain to another workgroup or domain.

This article describes how to programmatically manage domain membership on Windows NT 4.0. Windows 2000 and Windows XP introduces the NetJoinDomain API, which must be used by Windows 2000 and Windows XP clients to join a workgroup or a domain. For more information about the NetJoinDomain API, visit the following Microsoft Developer Network (MSDN) Web site:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/netmgmt/netmgmt/netjoindomain.asp



MORE INFORMATION
This article only describes how to join a workstation to a domain. It is assumed that a computer account for the computer has already been created on the domain controller.

This article uses the Windows NT local security authority (LSA) APIs to manage domain membership and the machine password. The Windows NT LAN Manager APIs are used to obtain information about the computer and domain controllers.

When joining a Windows 2000 and Windows XP domain, the username and password of a user in the domain should be supplied for establishing an IPC$ session to the domain controller as that user.

Sample code
/*++

Copyright (c) 1997 Microsoft Corporation

Module Name:

wksacct.c

Description:

This sample illustrates how to manage Windows NT domain membership at the workstation level. This sample duplicates what takes place when changing domain membership via the network control panel applet.

The first command line argument indicates the name of the domain to      which you want the computer to belong (or trust).

The second command line argument should be equal to the password for a newly created computer account. This password is typically the machine name converted to all lowercase.

Note that this sample will not allow this operation on a Domain Controller.

TODO: Delete any existing domain trust accounts Remove any previous Domain Admin groups from local groups Add Domain Administrators to local Administrators group Add Domain Users group to the local Users group. Change NetLogon Service to start automatically

Note: Lan Manager NetXxx API are Unicode only. Note: Windows NT LSA API are Unicode only.

The following import libraries are required: netapi32.lib advapi32.lib

--*/


 * 1) define UNICODE
 * 2) define _UNICODE
 * 3) define WINNT


 * 1) include 
 * 2) include 
 * 3) include "ntsecapi.h"


 * 1) include 


 * 1) define RTN_OK 0
 * 2) define RTN_USAGE 1
 * 3) define RTN_ERROR 13

// // if you have the ddk, include ntstatus.h //
 * 1) ifndef STATUS_SUCCESS
 * 2) define STATUS_SUCCESS                 ((NTSTATUS)0x00000000L)
 * 3) define STATUS_OBJECT_NAME_NOT_FOUND   ((NTSTATUS)0xC0000034L)
 * 4) define STATUS_OBJECT_NAME_COLLISION   ((NTSTATUS)0xC0000035L)
 * 5) define STATUS_INVALID_SID             ((NTSTATUS)0xC0000078L)
 * 6) endif

BOOL GetDomainDCName(  LPWSTR Domain,   LPWSTR *pPrimaryDC   );

BOOL EstablishSession(  LPCWSTR Server,   BOOL bEstablish,   LPWSTR DomainName,   LPWSTR UserName,   LPWSTR Password   );

BOOL DoesAccountExist(  LPWSTR Domain,   LPWSTR Account   );

void InitLsaString(  PLSA_UNICODE_STRING LsaString,   LPWSTR String   );

NTSTATUS OpenPolicy(  LPWSTR ComputerName,   DWORD DesiredAccess,   PLSA_HANDLE PolicyHandle   );

BOOL GetDomainSid(  LPWSTR DomainName,  // domain name to acquire Sid of   PSID *pDomainSid    // points to allocated Sid on success   );

NTSTATUS SetWorkstationTrustedDomainInfo(  LSA_HANDLE PolicyHandle,   PSID DomainSid,             // Sid of domain to manipulate   LPWSTR TrustedDomainName,   // trusted domain name to add/update   LPWSTR Password             // new trust password for trusted domain   );

NTSTATUS SetPrimaryDomain(  LSA_HANDLE PolicyHandle,   PSID DomainSid,   LPWSTR TrustedDomainName   );

void DisplayNtStatus(  LPSTR szAPI,    // ansi string containing API name   NTSTATUS Status   );

void DisplayError(  LPSTR szAPI,    // pointer to failed API name   DWORD dwLastError   );

// // Unicode entry point and argv // int __cdecl wmain(  int argc,   WCHAR *argv[]   ) {  LSA_HANDLE PolicyHandle; LPWSTR Workstation;      // target machine of policy update PSID DomainSid=NULL;     // Sid representing domain to trust WCHAR TrustedDomainName[MAX_COMPUTERNAME_LENGTH +1]; // domain or workgroup to join LPWSTR WorkGroupName;    // Workgroup to join LPWSTR Password;         // machine acct. password necessary to join domain LPWSTR PrimaryDC=NULL;   // name of that domain's PDC PSERVER_INFO_101 si101; DWORD Type; PUSER_MODALS_INFO_2 umi2; NET_API_STATUS nas; NTSTATUS Status; BOOL bJoinDom; PWKSTA_INFO_100 pwi100;

// Credentials for establishing a IPC$ session to DC  LPWSTR sessUserName = L""; LPWSTR sessPassword = L"";

if(argc < 2) { fprintf(stderr,          "Usage: %ls\t\n"           "                 \t  [UserName] [Password]\n",           argv[0]); fprintf(stderr,"MachineAccountPassword is used only if joining a domain\n"); fprintf(stderr,"Supply UserName and Password of a domain user for joining Windows 2000 domain\n"); return RTN_USAGE; }

if (argc == 2) {     bJoinDom = FALSE; // were joining a workgroup WorkGroupName = argv[1]; // Check if were a member of a domain nas = NetWkstaGetInfo(NULL,100,&(PBYTE)pwi100); if (nas != NERR_Success){ DisplayError("NetWkstaGetInfo", nas); return RTN_ERROR; }

lstrcpy(TrustedDomainName,pwi100->wki100_langroup);

}  else {     bJoinDom = TRUE; lstrcpy(TrustedDomainName,argv[1]); TrustedDomainName[MAX_COMPUTERNAME_LENGTH] = L'\0'; //truncate if necessary Password = argv[2]; if (argc >= 4) sessUserName = argv[3]; if (argc >= 5) sessPassword = argv[4]; }

Workstation = (unsigned short *) LocalAlloc(LPTR,256);

//   // ensure the local machine is NOT a DC, as this operation is   // only appropriate against a workstation. //   nas = NetServerGetInfo(NULL, 101, (LPBYTE *)&si101); if(nas != NERR_Success) { DisplayError("NetServerGetInfo", nas); return RTN_ERROR; }

Type = si101->sv101_type; NetApiBufferFree(si101);

if( (Type & SV_TYPE_DOMAIN_CTRL) ||      (Type & SV_TYPE_DOMAIN_BAKCTRL) ) { wprintf(L"Operation is not valid on a domain controller.\n"); return RTN_ERROR; }  //    // obtain the local machine's name //   nas = NetUserModalsGet(NULL, 2, (LPBYTE *)&umi2);

if(nas != NERR_Success) { DisplayError("NetUserModalsGet", nas); return RTN_ERROR; }

//   // copy the machine name to new storage //   lstrcpy(Workstation, umi2->usrmod2_domain_name);

NetApiBufferFree(umi2); // free memory allocated by NetXxx

//   // do not allow a workstation to trust itself //   if(lstrcmpiW(TrustedDomainName, Workstation) == 0) { wprintf(L"Error: Domain %ls cannot be a member of itself.\n",           TrustedDomainName);

return RTN_ERROR; }

//   // get the name of the domain DC   // if(!GetDomainDCName(TrustedDomainName,&PrimaryDC)) { wprintf(L"Could not get DC Name\n"); return RTN_ERROR; }

//   // establish NULL session to domain PDC //   if(!EstablishSession(PrimaryDC, TRUE, bJoinDom ? TrustedDomainName : L"", sessUserName, sessPassword)) { wprintf(L"Could not establish session with %ls\n",     PrimaryDC); return RTN_ERROR; }

wprintf(L"Session established to Domain Controller (%ls)\n",    PrimaryDC);

//   // see if the computer account exists on the domain //   if(!DoesAccountExist(PrimaryDC, Workstation)) return RTN_ERROR;

//   // fetch the DomainSid of the domain to trust //   if(!GetDomainSid(PrimaryDC, &DomainSid)) { DisplayError("GetDomainSid", GetLastError); return RTN_ERROR; }

wprintf(L"Opening policy on %s\n", Workstation);

//   // open the policy on this computer //   Status = OpenPolicy(            Workstation,            POLICY_CREATE_SECRET |  // for password set operation            POLICY_TRUST_ADMIN,     // for trust creation            &PolicyHandle            );

if(Status != STATUS_SUCCESS) { DisplayNtStatus("OpenPolicy", Status); return RTN_ERROR; }

if (!bJoinDom) // delete trust of dom were leaving {     Status = LsaDeleteTrustedDomain(PolicyHandle, DomainSid); if(Status != STATUS_SUCCESS) { DisplayNtStatus("OpenPolicy", Status); return RTN_ERROR; }   }

if (bJoinDom) // this stuff is not needed for workgroup joining. {     wprintf(L"Setting Trusted Domain and account password\n");

Status = SetWorkstationTrustedDomainInfo(                                   PolicyHandle,                                    DomainSid, // Must be null for workgroup,                                    TrustedDomainName,                                    Password                                    ); if(Status != STATUS_SUCCESS) { return RTN_ERROR; }  }

wprintf(L"Setting %ls\n", bJoinDom ? L"Primary Domain" : L"Workgroup");

//   // Update the primary domain to match the specified trusted domain //   Status = SetPrimaryDomain(       PolicyHandle,       bJoinDom ? DomainSid : NULL, // Must be null for workgroup       bJoinDom ? TrustedDomainName : WorkGroupName       );

if(Status != STATUS_SUCCESS) { DisplayNtStatus("SetPrimaryDomain", Status); return RTN_ERROR; }

wprintf(L"Workstation %ls is now a member of %ls %ls\n",                               Workstation,                                bJoinDom ? L"Domain" : L"Workgroup",                                 bJoinDom ? TrustedDomainName : WorkGroupName);

//   // close the NULL session to PDC //   if(bJoinDom) EstablishSession(PrimaryDC, FALSE, NULL, NULL, NULL);

//   // free the buffer allocated for the PDC computer name //   if(PrimaryDC) NetApiBufferFree(PrimaryDC);

LocalFree(Workstation);

//   // free the Sid which was allocated for the TrustedDomain Sid //   if(DomainSid) FreeSid(DomainSid);

//   // close the policy handle //   LsaClose(PolicyHandle);

wprintf(L"Restart the computer for the changes to take effect\n");

return RTN_OK; }

BOOL GetDomainDCName(  LPWSTR Domain,   LPWSTR *pPrimaryDC   ) {  NET_API_STATUS nas;

//   // get the name of the Primary Domain Controller //   nas = NetGetDCName(NULL, Domain, (LPBYTE *)pPrimaryDC);

if(nas != NERR_Success) { DisplayError("NetGetDCName", nas); return FALSE; }

return TRUE; }

BOOL EstablishSession(  LPCWSTR Server,   BOOL bEstablish,   LPWSTR DomainName,   LPWSTR UserName,   LPWSTR Password   ) {  LPCWSTR szIpc = L"\\IPC$"; WCHAR RemoteResource[UNCLEN + 5 + 1]; // UNC len + \IPC$ + NULL DWORD cchServer;

NET_API_STATUS nas;

//   // do not allow NULL or empty server name //   if(Server == NULL || *Server == L'\0') { SetLastError(ERROR_INVALID_COMPUTERNAME); return FALSE; }

cchServer = lstrlenW( Server );

if(Server[0] != L'\\' && Server[1] != L'\\') {

//       // prepend slashes and NULL terminate //       RemoteResource[0] = L'\\'; RemoteResource[1] = L'\\'; RemoteResource[2] = L'\0'; }  else { cchServer -= 2; // drop slashes from count

RemoteResource[0] = L'\0'; }

if(cchServer > CNLEN) { SetLastError(ERROR_INVALID_COMPUTERNAME); return FALSE; }

if(lstrcatW(RemoteResource, Server) == NULL) return FALSE; if(lstrcatW(RemoteResource, szIpc) == NULL) return FALSE;

//   // disconnect or connect to the resource, based on bEstablish //   if(bEstablish) { USE_INFO_2 ui2;

ZeroMemory(&ui2, sizeof(ui2));

ui2.ui2_local = NULL; ui2.ui2_remote = RemoteResource; ui2.ui2_asg_type = USE_IPC; if (lstrlenW(UserName) > 0) { ui2.ui2_domainname = DomainName; ui2.ui2_username = UserName; ui2.ui2_password = Password; }      else { ui2.ui2_domainname = L""; ui2.ui2_username = L""; ui2.ui2_password = L""; }

nas = NetUseAdd(NULL, 2, (LPBYTE)&ui2, NULL); if (nas != NERR_Success ) wprintf(L"NetUseAdd failed error %u\n",nas); }  else { nas = NetUseDel(NULL, RemoteResource, USE_LOTS_OF_FORCE); if (nas != NERR_Success ) wprintf(L"NetUseDel failed error %u\n",nas); }

if( nas == NERR_Success ) return TRUE; // indicate success

return FALSE; }

BOOL DoesAccountExist(  LPWSTR PrimaryDC,   LPWSTR Account   ) {  LPWSTR NetAccountName=NULL; PUSER_INFO_1 pUI_1=NULL; DWORD cbLength; BOOL  fReturn=FALSE; NET_API_STATUS nas;

NetAccountName = (unsigned short *) LocalAlloc(      LPTR, (lstrlenW(Account) + 2) * sizeof(WCHAR));

lstrcpyW(NetAccountName, Account);

cbLength = lstrlenW(NetAccountName);

//   // computer account names have a trailing Unicode '$' //   NetAccountName[cbLength] = L'$'; NetAccountName[cbLength + 1] = L'\0'; // terminate the string

//   // verify that the account for this machine exists in domain //   nas = NetUserGetInfo(             PrimaryDC,             NetAccountName,             1,             (LPBYTE *)&pUI_1             );

//   // free the allocated buffer for machine name //   if(NetAccountName) LocalFree(NetAccountName);

if(nas != NO_ERROR) { DisplayError("NetUserGetInfo", nas); return FALSE; }

if(pUI_1->usri1_flags & UF_WORKSTATION_TRUST_ACCOUNT) fReturn = TRUE; else wprintf(L"Account on PDC wrong type (%lu)\n",          pUI_1->usri1_flags);

//   // free buffer for user information //   if(pUI_1) NetApiBufferFree(pUI_1);

return fReturn;

}

void InitLsaString(  PLSA_UNICODE_STRING LsaString,   LPWSTR String   ) {  DWORD StringLength;

if(String == NULL) { LsaString->Buffer = NULL; LsaString->Length = 0; LsaString->MaximumLength = 0;

return; }

StringLength = lstrlenW(String); LsaString->Buffer = String; LsaString->Length = (USHORT) StringLength * sizeof(WCHAR); LsaString->MaximumLength = (USHORT) (StringLength + 1) * sizeof(WCHAR); }

BOOL GetDomainSid(  LPWSTR PrimaryDC,   // domain controller of domain to acquire Sid   PSID *pDomainSid    // points to allocated Sid on success   ) {  NET_API_STATUS nas; PUSER_MODALS_INFO_2 umi2 = NULL; DWORD dwSidSize; BOOL bSuccess = FALSE; // assume this function will fail *pDomainSid = NULL;   // invalidate pointer

__try {

//   // obtain the domain Sid from the PDC //   nas = NetUserModalsGet(PrimaryDC, 2, (LPBYTE *)&umi2); if(nas != NERR_Success) __leave;

//   // if the Sid is valid, obtain the size of the Sid //   if(!IsValidSid(umi2->usrmod2_domain_id)) __leave; dwSidSize = GetLengthSid(umi2->usrmod2_domain_id);

//   // allocate storage and copy the Sid //   *pDomainSid = LocalAlloc(LPTR, dwSidSize); if(*pDomainSid == NULL) __leave;

if(!CopySid(dwSidSize, *pDomainSid, umi2->usrmod2_domain_id)) __leave;

bSuccess = TRUE; // indicate success

} // try __finally {

if(umi2 != NULL) NetApiBufferFree(umi2);

if(!bSuccess) { //       // if the function failed, free memory and indicate result code //

if(*pDomainSid != NULL) { FreeSid(*pDomainSid); *pDomainSid = NULL; }

if(nas != NERR_Success) { SetLastError(nas); }  }

} // finally

return bSuccess; }

NTSTATUS OpenPolicy(  LPWSTR ComputerName,   DWORD DesiredAccess,   PLSA_HANDLE PolicyHandle   ) {  LSA_OBJECT_ATTRIBUTES ObjectAttributes; LSA_UNICODE_STRING ComputerString; PLSA_UNICODE_STRING Computer = NULL; LPWSTR NewComputerName;

NewComputerName = (unsigned short *) LocalAlloc(LPTR,      (MAX_COMPUTERNAME_LENGTH+3)*sizeof(WCHAR));

//   // Prepend some backslashes to the computer name so that // this will work on NT 3.51 //   lstrcpy(NewComputerName,L"\\\\"); lstrcat(NewComputerName,ComputerName);

lstrcpy(NewComputerName,ComputerName);

//   // Always initialize the object attributes to all zeroes //   ZeroMemory(&ObjectAttributes, sizeof(ObjectAttributes));

if(ComputerName != NULL) { //       // Make a LSA_UNICODE_STRING out of the LPWSTR passed in       // InitLsaString(&ComputerString, NewComputerName);

Computer = &ComputerString; }

//   // Attempt to open the policy //   return LsaOpenPolicy(               Computer,               &ObjectAttributes,               DesiredAccess,               PolicyHandle               ); }

/*++ This function sets the Primary Domain for the workstation.

To join the workstation to a Workgroup, ppdi.Name should be the name of the Workgroup and ppdi.Sid should be NULL.

--*/ NTSTATUS SetPrimaryDomain(  LSA_HANDLE PolicyHandle,   PSID DomainSid,   LPWSTR TrustedDomainName   ) {  POLICY_PRIMARY_DOMAIN_INFO ppdi;

InitLsaString(&ppdi.Name, TrustedDomainName); ppdi.Sid = DomainSid;

return LsaSetInformationPolicy(      PolicyHandle,       PolicyPrimaryDomainInformation,       &ppdi       ); }

/*++ This function manipulates the trust associated with the supplied DomainSid.

If the domain trust does not exist, it is created with the specified password. In this case, the supplied PolicyHandle must have been opened with POLICY_TRUST_ADMIN and POLICY_CREATE_SECRET access to the policy object.

--*/ NTSTATUS SetWorkstationTrustedDomainInfo(  LSA_HANDLE PolicyHandle,   PSID DomainSid,             // Sid of domain to manipulate   LPWSTR TrustedDomainName,   // trusted domain name to add/update   LPWSTR Password             // new trust password for trusted domain   ) {  LSA_UNICODE_STRING LsaPassword; LSA_UNICODE_STRING KeyName; LSA_UNICODE_STRING LsaDomainName; DWORD cchDomainName; // number of chars in TrustedDomainName NTSTATUS Status;

InitLsaString(&LsaDomainName, TrustedDomainName);

//   // ...convert TrustedDomainName to uppercase... //   cchDomainName = LsaDomainName.Length / sizeof(WCHAR); while(cchDomainName--) { LsaDomainName.Buffer[cchDomainName] = towupper(LsaDomainName.Buffer[cchDomainName]); }

InitLsaString(&KeyName, L"$MACHINE.ACC"); InitLsaString(&LsaPassword, Password);

//   // Set the machine password //   Status = LsaStorePrivateData(       PolicyHandle,       &KeyName,       &LsaPassword       );

if(Status != STATUS_SUCCESS) { DisplayNtStatus("LsaStorePrivateData", Status); return RTN_ERROR; }

return STATUS_SUCCESS;

}

void DisplayNtStatus(  LPSTR szAPI,    // ansi string containing API name   NTSTATUS Status   ) {  printf("erro=%lx\n", Status); //   // convert the NTSTATUS to Winerror and display the result //   DisplayError(szAPI, LsaNtStatusToWinError(Status)); }

void DisplayError(  LPSTR szAPI, // pointer to failed API name   DWORD dwLastError   ) {  HMODULE hModule; LPSTR MessageBuffer; DWORD dwBufferLength;

DWORD dwFormatFlags = FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_IGNORE_INSERTS | FORMAT_MESSAGE_FROM_SYSTEM ;

fprintf(stderr,"%s error! (rc=%lu)\n", szAPI, dwLastError);

//   // if dwLastError is in the network range, load the message source //   if(dwLastError >= NERR_BASE && dwLastError <= MAX_NERR) { hModule = LoadLibraryEx(          TEXT("netmsg.dll"),           NULL,           LOAD_LIBRARY_AS_DATAFILE           );

if(hModule != NULL) dwFormatFlags |= FORMAT_MESSAGE_FROM_HMODULE; } else { hModule = NULL; // default to system message source }

if(dwBufferLength=FormatMessageA( dwFormatFlags, hModule, dwLastError, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // default language (LPSTR) &MessageBuffer, 0,      NULL ))  {       printf(MessageBuffer);

LocalFree(MessageBuffer); }  else printf("FormatMessageA failed - %lu\n", GetLastError);

//   // if we loaded a message source, unload it   // if(hModule != NULL) FreeLibrary(hModule); }

Keywords: kbapi kbcode kbhowto kbkernbase kblsa kbnetwork kbsecurity KB170620

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.