3.2.4.13.3 Domain Join Specific Message Processing

  • Article

The following definitions are used in the specification of message processing that follows.

  • DomainNameString: A Unicode UTF-8 string with the same properties specified for the parameter DomainNameParam.

  • DomainControllerString: A UTF-8 string that contains the name of a domain controller in the domain that the server (2) is joining.

  • DomainObject: An object in the domain database ([MS-ADTS] section 6.4).

  • MachineAccountOUString: A UTF-8 string that contains the organizational unit (OU) in the directory for the machine account.

  • ComputerAccountString: A UTF-8 string that contains the value stored in the sAMAccountName attribute of the computer object in the domain database.

  • DNSComputerNameString: A UTF-8 string that contains the Internet host name of the computer.

  • Spn1: A UTF-8 string that contains a DNS-based SPN for the computer joining the domain.

  • Spn2: A UTF-8 string that contains a NetBIOS-based SPN for the computer joining the domain.

The following statements define the sequence of message-processing operations:

  1. If the NETSETUP_MACHINE_PWD_PASSED bit is set in Options, and the NETSETUP_JOIN_UNSECURE bit is not set in Options, the server MUST return ERROR_INVALID_PARAMETER. Otherwise, message processing continues.

  2. If the NETSETUP_MACHINE_PWD_PASSED bit is set in Options, and AccountName is not NULL, the server MUST return ERROR_INVALID_PARAMETER. Otherwise, message processing continues.

  3. If the NETSETUP_MACHINE_PWD_PASSED bit is set in Options, and either Password is NULL or the length of the PasswordString is zero, the server MUST return ERROR_PASSWORD_RESTRICTION. Otherwise, message processing continues.

  4. If the NETSETUP_MACHINE_PWD_PASSED bit is set in Options, the value of PasswordString MUST be copied to the value of ComputerPasswordString, and PasswordString MUST be set to NULL.

  5. If the NETSETUP_JOIN_READONLY bit is set in Options, and the NETSETUP_MACHINE_PWD_PASSED bit is not set in Options, the server MUST return ERROR_INVALID_PARAMETER. Otherwise, message processing continues.

  6. If the NETSETUP_JOIN_READONLY bit is set in Options, and the NETSETUP_ACCT_CREATE bit is set in Options, the server MUST return ERROR_INVALID_PARAMETER. Otherwise, message processing continues.

  7. If the NETSETUP_JOIN_READONLY bit is set in Options, the server MUST perform all subsequent message processing as if NETSETUP_DEFER_SPN_SET and NETSETUP_JOIN_UNSECURE bits were set in Options.

  8. If the server processing the message is already joined to a domain, and the NETSETUP_DOMAIN_JOIN_IF_JOINED bit is not set in Options, the server MUST return NERR_SetupAlreadyJoined. Otherwise, message processing continues.

  9. If DomainNameString contains the character "\", DomainNameString MUST be truncated such that the value of DomainNameString is equal to the substring of DomainNameString that ends prior to the first "\" character, and DomainControllerString MUST be equal to the substring beginning after the first "\" character. This is the name of the target domain controller as specified by the caller.

    The specified domain controller MUST be validated by invoking the DsrGetDcNameEx2 method ([MS-NRPC] section 3.5.4.3.1) on the DomainControllerString computer, specifying the following parameters:

    • ComputerName = DomainControllerString

    • AccountName = NULL

    • AllowableAccountControlBits = 0

    • DomainName = DomainNameString

    • SiteName = 0

    • Flags: If the NETSETUP_JOIN_READONLY bit is set in Options, Flags = (B | R); otherwise, Flags = B | J | R

    If the call succeeds and DomainControllerInfo->DomainControllerName matches DomainControllerString, execution continues at step 8.

    If the call fails, or the returned domain controller name does not match DomainControllerString, the server MUST invoke the DsrGetDcNameEx2 method ([MS-NRPC] section 3.5.4.3.1) on the DomainControllerString computer, specifying the following parameters:

    • ComputerName = DomainControllerString

    • AccountName = NULL

    • AllowableAccountControlBits = 0

    • DomainName = DomainNameString

    • SiteName = 0

    • Flags: If the NETSETUP_JOIN_READONLY bit is set in Options, Flags = (B | S); otherwise, Flags = B | J | S

    If the call fails, the server MUST stop message processing and return ERROR_NO_SUCH_DOMAIN. If the call succeeds and DomainControllerInfo->DomainControllerName matches DomainControllerString, execution continues at step 8. Otherwise, the server MUST stop message processing and return ERROR_INVALID_DOMAIN_ROLE.

  10. If DomainControllerString was not initialized in the preceding step, the server MUST locate a domain controller for the domain in DomainNameString, and DomainControllerString MUST be set to the string name of the located domain controller. The same parameter values that are shown above are used except that the ComputerName parameter is set to NULL.

  11. The SiteName ADM element SHOULD be updated with the client site name information that was returned as part of the call to DsrGetDcNameEx2.

  12. DomainNameString MUST be a validated domain name (2). The validation process is specified in section 3.2.4.16, where NameType is NetSetupDomain from the NETSETUP_NAME_TYPE enumeration (section 2.2.3.2). If this validation fails, the server MUST stop message processing and return the error specified in the validation process.

  13. If ComputerNameNetBIOS (section 3.2.1.5) is identical to DomainNameString, the server MUST return ERROR_INVALID_DOMAINNAME. Otherwise, message processing continues.

  14. If the NETSETUP_MACHINE_PWD_PASSED bit is set in Options, the server MUST attempt to establish an authenticated (2) SMB session with the domain controller named by the value of DomainControllerString. The client identity and authorization details that were used when establishing the SMB session are retrieved from RPC ([MS-RPCE] sections 2.2.1.1.10 and 3.3.3.4.3).

  15. If the NETSETUP_MACHINE_PWD_PASSED bit is set in Options, and the session fails to be established in the previous step with a non-authentication failure, the server MUST stop message processing and return the error. If the session fails to be established for some other reason, the server MUST attempt to establish an anonymous session. If an error occurs, the server MUST stop message processing and return that error. Otherwise, message processing continues.

  16. If the NETSETUP_MACHINE_PWD_PASSED bit is not set in Options, the server MUST establish an authenticated (2) SMB session with the domain controller named by the value of DomainControllerString. The credentials that are supplied during authentication are those in PasswordString, and the security context that is established MUST be that of AccountName. If an error occurs, the server MUST stop message processing and return that error. Otherwise, message processing continues.

  17. The SMB session that was established in the previous steps and the security context associated with it MUST be used for any higher-layer RPC calls made to the domain controller over the SMB NCACN_NP protocol sequence ([MS-RPCE] section 2.1.1.2 and [MS-SMB] section 3.2.4.2.4).

  18. The server MUST query the domain controller for its domain name and SID ([MS-LSAD] section 3.1.4.4.3).<73>

  19. The server MUST store the values queried in the previous step in the local DomainName and DomainSid elements (section 3.2.1.6).

  20. If the NETSETUP_MACHINE_PWD_PASSED bit is not set in Options, and either the NETSETUP_WIN9X_UPGRADE bit or the NETSETUP_JOIN_UNSECURE bit is set in Options, ComputerPasswordString is the first 14 characters of ComputerName.NetBIOS in lowercase.

  21. If the NETSETUP_MACHINE_PWD_PASSED bit is not set in Options, and neither the NETSETUP_WIN9X_UPGRADE bit nor the NETSETUP_JOIN_UNSECURE bit is set in Options, ComputerPasswordString is an ASCII string of randomly chosen characters. Each character's ASCII code MUST be between 32 and 122 inclusive. When randomly generating a password string, the server MUST generate 120 characters. Each character SHOULD be generated using the algorithm in [FIPS186-2] Appendix 3.1 and [RFC4086].<74>

  22. The server MUST store the value of ComputerPasswordString locally for consumption by security-provider services when authenticating the computer. The stored password MUST be maintained by the Netlogon Protocol [MS-NRPC] in the Password ADM element (section 3.2.1.6).

  23. If the value of the MachineAccountOU parameter is not NULL, the value of MachineAccountOUString MUST equal MachineAccountOU. If the value of MachineAccountOU is NULL, MachineAccountOUString MUST equal the value specified by the well-known object identified by the GUID with value GUID_COMPUTERS_CONTAINER_W ([MS-ADTS] section 6.1.1.4).

  24. If the [RFC1777]-format name of the organizational unit (OU) where the object exists, as specified by the value of MachineAccountOUString, cannot be found in the domain database, the server MUST return ERROR_FILE_NOT_FOUND. Otherwise, message processing continues.

  25. ComputerAccountString MUST be set to the UTF-8 string consisting of ComputerNameNetBIOS suffixed with a "$" character.

  26. DNSComputerNameString MUST equal the UTF-8 string ComputerNameFQDN.(section 3.2.1.5)

  27. Spn1 MUST be a UTF-8 string equal to the concatenation of "HOST/" and the value of DNSComputerNameString.

  28. Spn2 MUST be a UTF-8 string equal to the concatenation of "HOST/" and the value of ComputerAccountString.

  29. If the NETSETUP_ACCT_CREATE bit is set in Options, the server MUST create the domain object in the domain DomainNameParam at DomainControllerString. Manipulation of the domain computer object state is exposed through LDAP protocols ([RFC2252], [RFC2253], and [MS-SAMR]). If the domain object already exists in an organizational unit (OU) ([MS-ADSC] section 2.218) that is different from the one in MachineAccountOU, the server MUST stop message processing and return NERR_UserExists. If the domain object already exists but the MachineAccountOU is NULL or refers to the organizational unit (OU) of the domain object, the server MUST return NERR_Success. Otherwise, message processing continues.

  30. If the NETSETUP_ACCT_CREATE bit is not set in Options and the domain object does not already exist in the domain DomainNameParam at the domain controller, the server MUST stop message processing and return ERROR_NONE_MAPPED. Otherwise, message processing continues.

  31. If the NETSETUP_ACCT_CREATE bit is not set in Options, and either the NETSETUP_WIN9X_UPGRADE bit or the NETSETUP_JOIN_UNSECURE bit is set in Options, the server MUST send a request to the Netlogon Remote Protocol on the local computer to perform Netlogon authentication with the domain controllers. This is to validate that the value of ComputerPasswordString persisted locally equals the value of the password on the domain object in the LDAP attribute unicodePwd. If the authentication fails, the server MUST stop message processing and return ERROR_LOGON_FAILURE. Otherwise, message processing continues. For more information about Netlogon authentication between domain-joined computers and domain controllers, see [MS-NRPC].

  32. If the NETSETUP_JOIN_READONLY bit is not set in Options, the following LDAP attributes on DomainObject MUST be set to the values shown in the table. The security context provided to the LDAP protocol is AccountName and the credential is PasswordString. For details about attributes and attribute names, see [MS-ADTS]. For details about LDAP, see [RFC2252] and [RFC2253].

    LDAP attribute name

    Value

    userAccountControl

    ([MS-ADA3] section 2.342)

    The USER_WORKSTATION_TRUST_ACCOUNT bit is set and the USER_ACCOUNT_DISABLED bit is not set. See the userAccountControl mapping table ([MS-SAMR] section 3.1.5.14.2) for details about the mapping of these bits in the LDAP protocol.

    sAMAccountName

    ([MS-ADA3] section 2.222)

    The value of ComputerAccountString.

    unicodePwd

    ([MS-ADA3] section 2.332)

    The value of ComputerPasswordString. Protocols that expose this attribute persist the NT hash of the ComputerPasswordString ([MS-SAMR] section 3.1.5.10).

  33. The following LDAP attributes on DomainObject MUST be set to the values shown in the table unless the NETSETUP_DEFER_SPN_SET bit is set in Options.

    LDAP attribute name

    Value

    dNSHostName

    ([MS-ADA1] section 2.185)

    The value of DNSComputerNameString.

    servicePrincipalName

    ([MS-ADA3] section 2.253)

    Two values:

    Spn1

    Spn2

  34. The server MUST configure the local Netlogon Remote Protocol [MS-NRPC] so that it is aware of being joined to a domain with the name DomainNameParam.

  35. The server MUST configure the local Windows Time Service (W32Time) [WTSREF] so that it is aware of being joined to a domain.

  36. The server SHOULD store the value DNSComputerNameString locally so that the DNS service registers name records for the local computer [NIS].<75>

  37. The server SHOULD add the Domain Admins group to the local administrators group and the Domain Users group to the local users groups ([MS-SAMR] section 3.1.4.2).

  38. The server MUST apply all state changes (section 3.2.4.13.2).

  39. The server MUST stop impersonating the client by invoking the StopImpersonatingClient task (section 3.2.4.29.7).

If no errors occur, the server MUST return NERR_Success.