ServiceNow MID Server PowerShell script for Microsoft Active Directory cross-domain user addition functionality

 

ServiceNow MID Server PowerShell script for connecting Microsoft Active Directory and implement cross-domain user addition functionality to AD group

While working on  a ServiceNow workflow using Orchestration for Microsoft Active Directory cross-domain user addition functionality, we came across a scenario where feasibility check was needed to validate whether we can add a user from a specific domain lets say "domain1" to another domain let say "domain2". Additionally, considering a user need to be added cross domain local or universal group, the PowerShell script was supposed to equipped with proper error handling. It must properly address all possible scenarios and workaround within script for the user (of local or global scope) to be added in cross domain AD group including universal group. 

Based on several attempt it became clear that it is feasible to connect to Microsoft Active Directory using PowerShell and perform various administrative tasks, including adding a user from one domain to another, provided the necessary trust relationships and permissions are in place.

Here’s a general approach on how to connect to Active Directory using PowerShell and add a user from one domain to another:

Prerequisites

1. Active Directory Module for Windows PowerShell: Ensure you have the Active Directory module installed. This module comes with the Remote Server Administration Tools (RSAT) on Windows Server or can be installed on Windows 10.
2. Trust Relationship: Ensure there is a trust relationship between the two domains (domain1 and domain2).
3. Permissions: Ensure you have the necessary administrative permissions to perform these actions on both domains.

Important Notes

1. Security: Always ensure that credentials are handled securely and scripts are executed in a secure environment.
2. Trust Relationship: The domains need to have the necessary trust relationship established for cross-domain actions.
3. Permissions: Ensure you have the appropriate permissions to add users across domains.

The cross-domain user addition functionality may fail due to several reasons, including misconfigurations, insufficient permissions, or trust relationship issues between domains. Below are some common reasons and their resolutions:

Common Issues and Resolutions

1. Trust Relationship Issues:

   • Issue: The domains do not have the required trust relationships established.
   • Resolution: Ensure that the trust relationship is properly configured. You can verify and establish trust relationships using the Active Directory Domains and Trusts console.

2. Insufficient Permissions:

   • Issue: The account used to perform the operation does not have the necessary permissions.
   • Resolution: Ensure the account has administrative rights in both source and target domains. Check group memberships and permissions.

3. Replication Latency:

   • Issue: Changes made in one domain might not be immediately replicated to another domain.
   • Resolution: Wait for Active Directory replication to complete or force replication manually using repadmin commands.

4. Network Connectivity:

   • Issue: Network issues between domain controllers of different domains can prevent cross-domain operations.
   • Resolution: Ensure there is proper network connectivity and that necessary ports are open between domain controllers.

5. DNS Configuration:

   • Issue: Incorrect DNS settings can prevent domain controllers from resolving each other.
   • Resolution: Verify DNS settings and ensure that both domains can resolve each other's domain controllers.

6. User Account Issues:

   • Issue: The user account in the source domain might have restrictions or might be disabled.
   • Resolution: Verify the status and properties of the user account in the source domain.

7. Incorrect PowerShell Commands:

   • Issue: The PowerShell script might have syntax errors or incorrect parameters.
   • Resolution: Double-check the PowerShell script for accuracy and ensure all parameters are correctly specified.

The MID Server acts as a communication layer between ServiceNow and the local environment where it can execute commands, gather data, and perform other tasks.

Setting Up and Using MID Server for PowerShell Scripts

Prerequisites

1. ServiceNow Instance: Ensure you have access to your ServiceNow instance.
2. MID Server Installation: A MID Server must be installed and configured in your environment. The MID Server should have access to the necessary resources (e.g., Active Directory).

Steps

1. Install and Configure the MID Server:

   • Follow the official ServiceNow documentation to install and configure the MID Server in your local environment.
   • Ensure the MID Server has network access to both the ServiceNow instance and the resources required (e.g., domain controllers).

2. Create a PowerShell Script:

   • Write your PowerShell script to perform the desired Active Directory operation. For example, a script to add a user from one domain to another.

3. Upload the Script to ServiceNow:

   • Navigate to MID Server Script Files in ServiceNow.
   • Create a new record and upload your PowerShell script.

4. Create a PowerShell Probe:

   • Navigate to MID Server > Probes.
   • Create a new probe with the following details:
     • Name: Your probe name
     • Type: PowerShell
     • Script: Reference your uploaded PowerShell script file

5. Create a PowerShell Command:

   • Navigate to MID Server > Commands.
   • Create a new command with the following details:
     • Name: Your command name
     • Probe: Reference the probe you created
     • Parameters: Define the parameters required by your PowerShell script (e.g., username, sourceDomain, targetDomain, etc.)

6. Trigger the MID Server Command:

   • You can trigger the command from a ServiceNow workflow, script, or UI action by using the MIDServerScriptRunner API.

Example Use Case

Let's say you need to add a user from domain1 to a group in domain2 using a MID Server.

1. PowerShell Script: Save the script as AddUserToGroup.ps1 and upload it to ServiceNow.

2. Probe: Create a probe named AddUserToGroupProbe referencing AddUserToGroup.ps1.

3. Command: Create a command named AddUserToGroupCommand with parameters for username, sourceDomain, targetDomain, targetGroupName, sourceCred, and targetCred.

4. Triggering the Command: Use the following script in a ServiceNow business rule or script action:

var gr = new GlideRecord('ecc_queue'); gr.initialize(); gr.agent = 'MIDServerName'; // Replace with your MID Server name gr.topic = 'AddUserToGroupProbe'; // Name of your probe gr.name = 'AddUserToGroupCommand'; // Name of your command gr.source = 'script'; // Source of the command gr.payload = JSON.stringify({     username: 'user123',     sourceDomain: 'domain1.com',     targetDomain: 'domain2.com',     targetGroupName: 'GroupName',     sourceCred: 'sourceCredential',     targetCred: 'targetCredential' }); gr.insert();

This setup ensures that your PowerShell script is executed via the MID Server, allowing you to interact with local resources securely and efficiently.

In the context of Active Directory (AD) and domain management, there are several important concepts related to domains that you should be aware of:

Universal vs. Local Domains

1. Local Domain:

   • Definition: A local domain refers to a domain within an organization's Active Directory infrastructure. It is managed internally and consists of users, groups, and resources specific to that organization.
   • Example: domain1.corp.local, domain2.corp.local

2. Universal Domain:

   • Definition: The term "universal domain" is not commonly used in the context of AD. However, "universal" can refer to certain types of groups that are designed to work across multiple domains in a forest.
   • Universal Groups: These are a type of AD group that can have members from any domain within the AD forest and can be granted permissions in any domain within the forest. Universal groups are useful for managing permissions across multiple domains.
   • Example: A universal group called AllEmployees that contains users from domain1 and domain2 and has permissions to resources in both domains.

Key Concepts

1. Trust Relationships:

   • Trusts are established between domains to allow for the sharing of resources and authentication.
   • Types of trusts include external trusts, forest trusts, realm trusts, and shortcut trusts.
   • Trust relationships can be one-way or two-way and can be transitive or non-transitive.

2. Global Catalog:

   • The global catalog is a distributed data repository that contains a searchable, partial representation of every object in every domain within a multi-domain AD forest.
   • It helps in speeding up searches and logon processes by providing a way to look up objects without needing to contact every domain controller.

3. Group Scope:

   • Domain Local Groups: Used to manage access to resources within the same domain.
   • Global Groups: Can include members from the same domain and can be used to grant permissions in any domain within the forest.
   • Universal Groups: Can include members from any domain within the forest and can be used to grant permissions to resources in any domain within the forest.

Practical Use of Universal and Local Concepts

When managing users and groups across multiple domains, you often need to understand these concepts to correctly configure permissions and access:

• Universal Groups: Use these when you need to grant access to resources across multiple domains. For example, if you have a shared resource in domain2 that users from both domain1 and domain2 need to access, you can create a universal group and add users from both domains to this group.

New-ADGroup -Name "UniversalGroup" -GroupScope Universal -GroupCategory Security -Path "CN=Users,DC=domain2,DC=corp,DC=local"  # Adding users from different domains to the universal group  Add-ADGroupMember -Identity "UniversalGroup" -Members "user1@domain1.corp.local","user2@domain2.corp.local"

• Domain Local Groups: Use these to manage permissions to resources that are within the same domain. For example, granting access to a file server in domain1.

# Example PowerShell to create a domain local group and add members  New-ADGroup -Name "DomainLocalGroup" -GroupScope DomainLocal -GroupCategory Security -Path "CN=Users,DC=domain1,DC=corp,DC=local"  # Adding members to the domain local group  Add-ADGroupMember -Identity "DomainLocalGroup" -Members "user1","user2"

Integrating with ServiceNow and MID Server

When using a MID Server to execute PowerShell scripts for AD tasks:

• The MID Server runs in the context of the local domain where it is installed but can interact with other domains if properly configured.
• Universal groups and trust relationships allow for cross-domain operations, assuming the necessary permissions and configurations are in place.

Creating a robust PowerShell script for adding a user to a cross-domain local or universal group with proper error handling involves several steps. The script needs to account for network issues, trust relationships, permissions, and other potential issues. Here's a detailed and comprehensive script with proper error handling to cover various scenarios:

Prerequisites

• Ensure the Active Directory module for PowerShell is installed.
• The script is executed with sufficient privileges to add users to groups across domains.
• Trust relationships between the domains are properly configured.

Script Outline

1. Parameters: Accept input parameters for user, source domain, target domain, group name, and credentials.
2. Validation: Validate the input parameters.
3. Connectivity Check: Verify network connectivity to both domains.
4. Retrieve User: Retrieve the user from the source domain.
5. Add User to Group: Add the user to the specified group in the target domain.
6. Error Handling: Handle errors gracefully and provide meaningful output.

Robust PowerShell Script with Detailed Error Handling and Logging

To provide a comprehensive solution, the script should handle these scenarios and log relevant information for troubleshooting:

param (     [string]$username,     [string]$sourceDomain,     [string]$targetDomain,     [string]$groupName,     [pscredential]$sourceCred,     [pscredential]$targetCred,     [string]$logFile = "C:\Scripts\ADUserAdd.log"  # Default log file path )  function Write-Log {     param (         [string]$message,         [string]$logFile     )          $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"     $logMessage = "$timestamp - $message"     Add-Content -Path $logFile -Value $logMessage }  function Validate-Parameters {     param (         [string]$username,         [string]$sourceDomain,         [string]$targetDomain,         [string]$groupName,         [string]$logFile     )      Write-Log -message "Validating parameters." -logFile $logFile      if (-not $username) {         $msg = "Username is required."         Write-Log -message $msg -logFile $logFile         throw $msg     }     if (-not $sourceDomain) {         $msg = "Source domain is required."         Write-Log -message $msg -logFile $logFile         throw $msg     }     if (-not $targetDomain) {         $msg = "Target domain is required."         Write-Log -message $msg -logFile $logFile         throw $msg     }     if (-not $groupName) {         $msg = "Group name is required."         Write-Log -message $msg -logFile $logFile         throw $msg     } }  function Check-Connectivity {     param (         [string]$domain,         [string]$logFile     )      Write-Log -message "Checking connectivity to domain controller for $domain." -logFile $logFile      try {         $ping = Test-Connection -ComputerName $domain -Count 1 -ErrorAction Stop         Write-Log -message "Successfully connected to domain controller for $domain." -logFile $logFile         return $true     }     catch {         $msg = "Unable to connect to domain controller for $domain."         Write-Log -message $msg -logFile $logFile         Write-Log -message $_ -logFile $logFile         return $false     } }  function Get-User {     param (         [string]$username,         [string]$domain,         [pscredential]$cred,         [string]$logFile     )      Write-Log -message "Retrieving user $username from domain $domain." -logFile $logFile      try {         $user = Get-ADUser -Identity $username -Server $domain -Credential $cred -ErrorAction Stop         Write-Log -message "Successfully retrieved user $username from domain $domain." -logFile $logFile         return $user     }     catch {         $msg = "Error retrieving user $username from domain $domain: $_"         Write-Log -message $msg -logFile $logFile         throw $msg     } }  function Add-UserToGroup {     param (         [ADUser]$user,         [string]$groupName,         [string]$domain,         [pscredential]$cred,         [string]$logFile     )      Write-Log -message "Adding user $($user.SamAccountName) to group $groupName in domain $domain." -logFile $logFile      try {         Add-ADGroupMember -Identity $groupName -Members $user.DistinguishedName -Server $domain -Credential $cred -ErrorAction Stop         $msg = "User $($user.SamAccountName) added to group $groupName successfully."         Write-Log -message $msg -logFile $logFile         Write-Output $msg     }     catch {         $msg = "Error adding user $($user.SamAccountName) to group $groupName: $_"         Write-Log -message $msg -logFile $logFile         throw $msg     } }  # Main Script Execution try {     Import-Module ActiveDirectory -ErrorAction Stop     Write-Log -message "Active Directory module imported successfully." -logFile $logFile      Validate-Parameters -username $username -sourceDomain $sourceDomain -targetDomain $targetDomain -groupName $groupName -logFile $logFile        if (-not (Check-Connectivity -domain $sourceDomain -logFile $logFile)) { throw "Source domain connectivity check failed." }     if (-not (Check-Connectivity -domain $targetDomain -logFile $logFile)) { throw "Target domain connectivity check failed." }      $user = Get-User -username $username -domain $sourceDomain -cred $sourceCred -logFile $logFile      try {         Add-UserToGroup -user $user -groupName $groupName -domain $targetDomain -cred $targetCred -logFile $logFile     }     catch {         if ($groupName -notmatch "^(Domain Admins|Enterprise Admins|Schema Admins)$") {             $msg = "Cannot add user to group $groupName in domain $targetDomain. Cross-domain group membership may be restricted."             Write-Log -message $msg -logFile $logFile             throw $msg         }         throw $_     } } catch {     $errorMsg = "An error occurred: $_"     Write-Log -message $errorMsg -logFile $logFile     Write-Error $errorMsg }

Detailed Steps

1. Log Function (Write-Log):

   • Writes messages to a log file with a timestamp for auditing and troubleshooting purposes.

2. Parameter Validation:

   • Ensures all necessary parameters are provided.
   • Logs validation steps.

3. Connectivity Check:

   • Verifies network connectivity to domain controllers.
   • Logs the results of connectivity checks.

4. Retrieve User:

   • Retrieves the user from the source domain.
   • Logs the success or failure of user retrieval.

5. Add User to Group:

   • Attempts to add the user to the specified group in the target domain.
   • Logs the attempt and its outcome.
   • Handles errors specific to cross-domain membership restrictions.
   • Provides a specific check for well-known restricted groups and logs a clear message.

6. Main Script Execution:

   • Imports the Active Directory module.
   • Validates parameters, checks connectivity, retrieves the user, and attempts to add the user to the group.
   • Catches and logs any errors encountered during execution.

Example PowerShell Command

.\AddUserToGroup.ps1 -username "user1" -sourceDomain "domain1.corp.local" -targetDomain "domain2.corp.local" -groupName "GroupName" -sourceCred (Get-Credential) -targetCred (Get-Credential) -logFile "C:\Scripts\ADUserAdd.log"

This robust comprehensive script ensures detailed logging of the script’s execution, making it easier to audit and troubleshoot. It also includes specific error handling for cross-domain group membership scenarios.

If the script does not work for scenarios where a user needs to be added to a cross-domain AD group (other than a universal group), it could be due to limitations or restrictions in Active Directory regarding group membership across domains. Here are some common reasons and their potential solutions:

Common Issues and Solutions

1. Trust Relationship Issues:

   • Issue: The domains do not have the necessary trust relationships established.
   • Solution: Ensure that the appropriate trust relationships (e.g., external or forest trusts) are in place and properly configured between the domains.

2. Group Scope Limitations:

   • Issue: Only universal groups can contain members from different domains. Domain local and global groups have restrictions:
     • Domain Local Groups: Can only contain members from any domain but can only be used within the domain where they are defined.
     • Global Groups: Can only contain members from the same domain where the group is defined.
   • Solution: Use universal groups for cross-domain group membership. If domain-specific groups are required, ensure the user is a member of a global group in their domain, and then add that global group to the domain local group in the target domain.

3. Permissions and Access Control:

   • Issue: The account running the script does not have the necessary permissions to add users to groups in the target domain.
   • Solution: Ensure that the credentials used have sufficient privileges in both the source and target domains.

4. Network and DNS Configuration:

   • Issue: Network or DNS issues prevent communication between domain controllers.
   • Solution: Ensure proper network connectivity and DNS resolution between the domains.