In the modern IT landscape, ensuring a computer joins the appropriate domain is more than a convenience—it’s an essential step toward consolidating control, simplifying access, and maintaining network security. This PowerShell script is designed to streamline the process of adding a computer to a domain.
Background
PowerShell has risen to prominence among IT professionals and Managed Service Providers (MSPs) as a robust and versatile scripting language. Its flexibility allows administrators to automate repetitive tasks, enforce policies, and configure systems quickly. The script presented here serves a crucial function: it enables computers to join a domain seamlessly. Domains are pivotal in the enterprise IT world, as they facilitate resource sharing, centralized authentication, and policy enforcement. A script that can reliably add computers to a domain thus adds immense value.
The Script
#Requires -Version 5.1
<#
.SYNOPSIS
Joins a computer to a domain.
.DESCRIPTION
Joins a computer to a domain.
.EXAMPLE
-DomainName "Domain.com" -UserName "DomainMyDomainUser" -Password "Somepass1"
Joins a computer to a "Domain.com" domain and restarts the computer. Don't expect a success result in Ninja as the computer will reboot before the script can return a result.
.EXAMPLE
-DomainName "Domain.com" -UserName "DomainMyDomainUser" -Password "Somepass1" -NoRestart
Joins a computer to a "Domain.com" domain and does not restart the computer.
.EXAMPLE
PS C:> Join-Domain.ps1 -DomainName "domain.com" -UserName "DomainMyDomainUser" -Password "Somepass1" -NoRestart
Joins a computer to a "Domain.com" domain and does not restart the computer.
.EXAMPLE
-DomainName "Domain.com" -UserName "DomainMyDomainUser" -Password "Somepass1" -Server "192.168.0.1"
Not recommended if the computer this script is running on does not have one of the Domain Controllers set as its DNS server.
Joins a computer to a "Domain.com" domain, talks to the domain with the IP address of "192.168.0.1", and restarts the computer.
.OUTPUTS
String[]
.NOTES
Minimum OS Architecture Supported: Windows 10, Windows Server 2016
Release Notes:
Initial Release
By using this script, you indicate your acceptance of the following legal terms as well as our Terms of Use at https://www.ninjaone.com/terms-of-use.
Ownership Rights: NinjaOne owns and will continue to own all right, title, and interest in and to the script (including the copyright). NinjaOne is giving you a limited license to use the script in accordance with these legal terms.
Use Limitation: You may only use the script for your legitimate personal or internal business purposes, and you may not share the script with another party.
Republication Prohibition: Under no circumstances are you permitted to re-publish the script in any script library or website belonging to or under the control of any other software provider.
Warranty Disclaimer: The script is provided “as is” and “as available”, without warranty of any kind. NinjaOne makes no promise or guarantee that the script will be free from defects or that it will meet your specific needs or expectations.
Assumption of Risk: Your use of the script is at your own risk. You acknowledge that there are certain inherent risks in using the script, and you understand and assume each of those risks.
Waiver and Release: You will not hold NinjaOne responsible for any adverse or unintended consequences resulting from your use of the script, and you waive any legal or equitable rights or remedies you may have against NinjaOne relating to your use of the script.
EULA: If you are a NinjaOne customer, your use of the script is subject to the End User License Agreement applicable to you (EULA).
.COMPONENT
ManageUsers
#>
[CmdletBinding()]
param (
# Domain Name to join computer to
[Parameter(Mandatory = $true)]
[String]
$DomainName,
# Use a Domain UserName to join this computer to a domain, this requires the Password parameter to be used as well
[Parameter(Mandatory = $true)]
[String]
$UserName,
# Use a Domain Password to join this computer from a domain
[Parameter(Mandatory = $true)]
$Password,
# Used only when computer can't locate a domain controler via DNS or you wish to connect to a specific DC
[Parameter()]
$Server,
# Do not restart computer after joining to a domain
[Switch]
$NoRestart
)
begin {
function Join-ComputerToDomainPS2 {
param (
[String]
$DomainName,
[PSCredential]
$Credential,
$Restart,
$Server
)
if ($Credential) {
# Use supplied Credentials
if ($Server) {
Add-Computer -DomainName $DomainName -Credential $Credential -Server $Server -Force -Confirm:$false -PassThru
}
else {
Add-Computer -DomainName $DomainName -Credential $Credential -Force -Confirm:$false -PassThru
}
}
else {
# No Credentials supplied, use current user
Add-Computer -DomainName $DomainName -Force -Confirm:$false -PassThru
}
}
Write-Output "Starting Join Domain"
# Convert username and password into a credential object
$JoinCred = [PSCredential]::new($UserName, $(ConvertTo-SecureString -String $Password -AsPlainText -Force))
}
process {
Write-Output "Joining computer($env:COMPUTERNAME) to domain $DomainName"
$script:JoinResult = $false
try {
$JoinResult = if ($NoRestart) {
# Do not restart after joining
if ($PSVersionTable.PSVersion.Major -eq 2) {
if ($Server) {
(Join-ComputerToDomainPS2 -DomainName $DomainName -Credential $Credential -Server $Server).HasSucceeded
}
else {
(Join-ComputerToDomainPS2 -DomainName $DomainName -Credential $Credential).HasSucceeded
}
}
else {
if ($Server) {
(Add-Computer -DomainName $DomainName -Credential $JoinCred -Server $Server -Force -Confirm:$false -PassThru).HasSucceeded
}
else {
(Add-Computer -DomainName $DomainName -Credential $JoinCred -Force -Confirm:$false -PassThru).HasSucceeded
}
}
}
else {
# Restart after joining
if ($PSVersionTable.PSVersion.Major -eq 2) {
if ($Server) {
(Join-ComputerToDomainPS2 -DomainName $DomainName -Credential $Credential -Server $Server).HasSucceeded
}
else {
(Join-ComputerToDomainPS2 -DomainName $DomainName -Credential $Credential).HasSucceeded
}
}
else {
if ($Server) {
(Add-Computer -DomainName $DomainName -Credential $JoinCred -Restart -Server $Server -Force -Confirm:$false -PassThru).HasSucceeded
}
else {
(Add-Computer -DomainName $DomainName -Credential $JoinCred -Restart -Force -Confirm:$false -PassThru).HasSucceeded
}
}
}
}
catch {
Write-Error "Failed to Join Domain: $DomainName"
}
if ($NoRestart -and $JoinResult) {
Write-Output "Joined computer($env:COMPUTERNAME) to Domain: $DomainName and not restarting computer"
}
elseif ($JoinResult) {
Write-Output "Joined computer($env:COMPUTERNAME) to Domain: $DomainName and restarting computer"
if ($PSVersionTable.PSVersion.Major -eq 2) {
shutdown.exe -r -t 60
}
}
else {
Write-Output "Failed to Join computer($env:COMPUTERNAME) to Domain: $DomainName"
# Clean up credentials so that they don't leak outside this script
$JoinCred = $null
exit 1
}
}
end {
# Clean up credentials so that they don't leak outside this script
$JoinCred = $null
Write-Output "Completed Join Domain"
}
Access 300+ scripts in the NinjaOne Dojo
Detailed Breakdown
The script begins with comprehensive metadata, outlining its purpose, usage examples, and expected outputs. The core logic follows a standard PowerShell function layout: begin, process, and end.
- Parameters: These are inputs the user provides, including DomainName, UserName, Password, and Server. A switch parameter called NoRestart allows users to decide if they want the computer to restart after joining the domain.
- Begin Block: This section initializes the script. It defines a function Join-ComputerToDomainPS2 and converts the provided username and password into a secure credential object, ready for use in the joining process.
- Process Block: The central logic resides here. Depending on the provided parameters, the script will join the computer to the domain with or without a restart. It uses two primary PowerShell commands: Add-Computer and a user-defined function. If any errors arise during this process, they’re caught and reported.
- End Block: This finalizes the script, cleaning up any credentials used during its execution.
Potential Use Cases
Case Study: Imagine an MSP handling IT for several small businesses. They’ve just deployed 50 new machines and need them all on the company’s domain by the start of business the next day. Using the script, the MSP quickly feeds in the required details for all machines. Within minutes, every computer is set up, without the need for manual configurations or time-consuming setups.
Comparisons
Traditional methods of joining a computer to a domain involve manual steps through the Windows interface or using legacy scripts. These methods can be time-consuming, error-prone, and don’t scale well for large deployments. Our PowerShell approach is more efficient, less error-prone, and scales to handle multiple machines.
FAQs
- Can this script handle bulk additions of computers to a domain?
Yes, with proper looping logic in place, you can process multiple computers. - What happens if the domain details provided are incorrect?
The script will throw an error indicating the domain join failure.
Implications
Incorrectly joining domains or exposing credentials can be detrimental to IT security. If a computer joins the wrong domain, it might access unauthorized resources or become exposed to security risks.
Recommendations
- Always validate domain details before execution.
- Protect and regularly rotate domain credentials.
- Test the script in a controlled environment before deploying.
Final thoughts
In an age where automation reigns supreme, tools like this script, combined with platforms like NinjaOne, can enhance efficiency, security, and manageability. NinjaOne, in particular, offers robust monitoring and management features, ensuring that once computers are added to the domain, they remain compliant, secure, and optimized for performance.