Add-SCOMRunAsAccount

Add-SCOMRunAsAccount

Adds a Run As account to a management group.

Syntax

Parameter Set: Windows
Add-SCOMRunAsAccount [-Name] <String> [-RunAsCredential] <PSCredential> [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-Windows] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: ActionAccount
Add-SCOMRunAsAccount [-Name] <String> [-RunAsCredential] <PSCredential> [-ActionAccount] [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: Basic
Add-SCOMRunAsAccount [-Name] <String> [-RunAsCredential] <PSCredential> [-Basic] [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: Binary
Add-SCOMRunAsAccount [-Name] <String> [-Path] <String> [-Binary] [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: CommunityString
Add-SCOMRunAsAccount [-Name] <String> [-String] <SecureString> [-CommunityString] [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: Digest
Add-SCOMRunAsAccount [-Name] <String> [-RunAsCredential] <PSCredential> [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-Digest] [-SCSession <Connection[]> ] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: SCXMaintenanceSSHKeyNoPrivSu
Add-SCOMRunAsAccount [-Name] <String> [-Path] <String> [-UserName] <String> -Su -SuPassword <SecureString> [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-Passphrase <SecureString> ] [-SCSession <Connection[]> ] [-SCXMaintenance] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: SCXMaintenanceSSHKeyNoPrivSudo
Add-SCOMRunAsAccount [-Name] <String> [-Path] <String> [-UserName] <String> -Sudo [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-Passphrase <SecureString> ] [-SCSession <Connection[]> ] [-SCXMaintenance] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: SCXMaintenanceSSHKeyPriv
Add-SCOMRunAsAccount [-Name] <String> [-Path] <String> [-UserName] <String> -Privileged [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-Passphrase <SecureString> ] [-SCSession <Connection[]> ] [-SCXMaintenance] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: SCXMaintenanceUserPassNoPrivSu
Add-SCOMRunAsAccount [-Name] <String> [-RunAsCredential] <PSCredential> -Su -SuPassword <SecureString> [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-SCXMaintenance] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: SCXMaintenanceUserPassNoPrivSudo
Add-SCOMRunAsAccount [-Name] <String> [-RunAsCredential] <PSCredential> -Sudo [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-SCXMaintenance] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: SCXMaintenanceUserPassPriv
Add-SCOMRunAsAccount [-Name] <String> [-RunAsCredential] <PSCredential> -Privileged [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-SCXMaintenance] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: SCXMonitoring
Add-SCOMRunAsAccount [-Name] <String> [-RunAsCredential] <PSCredential> [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-SCXMonitoring] [-Sudo] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: Simple
Add-SCOMRunAsAccount [-Name] <String> [-RunAsCredential] <PSCredential> [-ComputerName <String[]> ] [-Credential <PSCredential> ] [-Description <String> ] [-SCSession <Connection[]> ] [-Simple] [-Confirm] [-WhatIf] [ <CommonParameters>]

Parameter Set: SnmpV3
Add-SCOMRunAsAccount [-Name] <String> [-UserName] <String> [-AuthProtocolAndKey <PSCredential> ] [-ComputerName <String[]> ] [-Context <String> ] [-Credential <PSCredential> ] [-Description <String> ] [-PrivacyProtocolAndKey <PSCredential> ] [-SCSession <Connection[]> ] [-SnmpV3] [-Confirm] [-WhatIf] [ <CommonParameters>]

Detailed Description

The Add-SCOMRunAsAccount cmdlet adds a Run As account to a management group. A Run As account enables users to specify the necessary permissions for use with rules, tasks, monitors, and discoveries targeted to specific computers on an as-needed basis.

System Center 2012 – Operations Manager distributes the Run As account credentials to either all agent-managed computers, the less secure option, or only to computers that you specify, the more secure option. By default, all new accounts have the more secure distribution option. To modify the account distribution policy, use the Set-SCOMRunAsDistribution cmdlet.

Parameters

-ActionAccount

Indicates that the account is an action account. An action account specifies credentials that the MonitoringHost management process uses to perform monitoring activities.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-AuthProtocolAndKey<PSCredential>

Specifies a PSCredential object that includes the Simple Network Management Protocol (SNMP) authentication protocol and key. To obtain a PSCredential object, use the Get-Credential cmdlet.

If this parameter appears, the cmdlet must also specify the UserName and Passphrase parameters. Specify the protocol name MD5 or SHA for the Username parameter and the key for the Passphrase parameter.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Basic

Indicates that the Run As account is a Basic Authentication account, which uses basic web authentication.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Binary

Indicates that the Run As account is a Binary Authentication account, which uses authentication that the user defines.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-CommunityString

Indicates that the Run As account is a Community String account, which uses community string authentication in Simple Network Management Protocol (SNMP) version 2.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-ComputerName<String[]>

Specifies an array of names of computers. This cmdlet establishes temporary connections with management groups for these computers. You can use NetBIOS names, IP addresses, or fully qualified domain names (FQDNs). To specify the local computer, type the computer name, localhost, or a dot (.).

The System Center Data Access service must be started on the computer. If you do not specify a computer, this cmdlet uses the computer for the current management group connection.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Context<String>

Specifies the SNMP version 3 context.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Credential<PSCredential>

Specifies the user account under which the management group connection runs. Specify a PSCredential object, such as one that the Get-Credential cmdlet returns, for this parameter. For more information about credential objects, type Get-Help Get-Credential.

If you specify a computer in the ComputerName parameter, use an account that has access to that computer. The default is the current user.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Description<String>

Specifies the account description. If you do not specify this parameter, the default value is the display name.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Digest

Indicates that the Run As account is a Digest Authentication account, which uses standard digest web authentication.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Name<String>

Specifies the account name.

Aliases

none

Required?

true

Position?

1

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Passphrase<SecureString>

Specifies the Secure Shell (SSH) key passphrase for cross-platform maintenance accounts.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Path<String>

Specifies the path to the binary data file or Secure Shell (SSH) key.

Aliases

none

Required?

true

Position?

2

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-PrivacyProtocolAndKey<PSCredential>

Specifies a PSCredential object that stores the SNMP privacy protocol and key. To obtain a PSCredential object, use the Get-Credential cmdlet.

If you specify this parameter appears, you must also specify the UserName and Passphrase parameters. Specify the protocol name AES or DES for the Username parameter, and the key for the Passphrase parameter.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Privileged

Indicates that this cmdlet sets the cross-platform maintenance account as privileged access.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-RunAsCredential<PSCredential>

Specifies the credential for the Run As account.

Aliases

none

Required?

true

Position?

2

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-SCSession<Connection[]>

Specifies an array of Connection objects. To get Connection objects, use the Get-SCOMManagementGroupConnection cmdlet.

If this parameter is not specified, the cmdlet uses the active persistent connection to a management group. Use the SCSession parameter to specify a different persistent connection. You can create a temporary connection to a management group by using the ComputerName and Credential parameters. For more information, type Get-Help about_OpsMgr_Connections.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-SCXMaintenance

Indicates that the account is a cross-platform maintenance Run As account.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-SCXMonitoring

Indicates that the Run As account is a Basic Authentication account, which uses basic web authentication.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Simple

Indicates that the account is a Simple Authentication Run As account.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-SnmpV3

Indicates that the account is an SNMP version 3 Run As account.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-String<SecureString>

Specifies the account community string.

Aliases

none

Required?

true

Position?

2

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Su

Indicates that the cross-platform maintenance account uses superuser elevation to perform privileged actions.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Sudo

Indicates that the cross-platform account uses sudo elevation to perform privileged actions. The sudo program enables users to run programs that have the security permissions of another user account.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-SuPassword<SecureString>

Specifies the superuser password for a cross-platform maintenance account.

Aliases

none

Required?

true

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-UserName<String>

Specifies the user name for the account. This parameter is valid only for SNMP version 3 and cross-platform maintenance accounts. Otherwise, use the RunAsCredential parameter.

Aliases

none

Required?

true

Position?

2

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Windows

Indicates that the account is a Run As account for Windows, which uses Windows credentials for authentication. This is the default account type if the cmdlet does not specify a different type.

Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Confirm

Prompts you for confirmation before running the cmdlet.

Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see    about_CommonParameters (https://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

Outputs

The output type is the type of the objects that the cmdlet emits.

Examples

Example 1: Add a Windows Run As account

This command adds a Run As account that uses Windows authentication.

PS C:\> Add-SCOMRunAsAccount -Windows -Name "Contoso.Windows" -Description "Account used for monitoring the Contoso domain" -RunAsCredential (Get-Credential) 

Example 2: Add a Community String Run As account

This example adds a Run As account that uses Community String authentication.

The first command prompts the user to enter the community string for the account and stores the input as a secure string in the variable named $CommunityString.

The second account creates the account and specifies the string stored in $CommunityString as the community string for the account.

PS C:\> $CommunityString = Read-Host -AsSecureString
PS C:\> Add-SCOMRunAsAccount -CommunityString -Name "Contoso.CommStr" -String $CommunityString

Example 3: Add a Basic Authentication Run As account

This command adds a Run As account that uses basic web authentication.

PS C:\> Add-SCOMRunAsAccount -Basic -Name "Contoso.Basic" -RunAsCredential (Get-Credential) 

Example 4: Add a Simple Authentication Run As account

This command adds a Run As account that uses simple authentication.

PS C:\> Add-SCOMRunAsAccount -Simple -Name "Contoso.Simple" -RunAsCredential (Get-Credential)

Example 5: Add a Digest Authentication Run As account

This command adds a Run As account that uses standard digest web authentication.

PS C:\> Add-SCOMRunAsAccount -Digest -Name "Contoso.Digest" -RunAsCredential (Get-Credential)

Example 6: Add a Binary Authentication Run As account

This command adds a Run As account that uses binary authentication.

PS C:\> Add-SCOMRunAsAccount -Binary -Name "Contoso.Binary" -Path "C:\accountfile.bin"

Example 7: Add an action account

This command adds an action account.

PS C:\> Add-SCOMRunAsAccount -ActionAccount -Name "Contoso.Action" -RunAsCredential (Get-Credential) 

Example 8: Add an SNMP version 3 account without context, authentication, or privacy

This command adds an SNMP version 3 account that has no context, authentication protocol, or privacy protocol.

PS C:\> Add-SCOMRunAsAccount -Snmpv3 -Name "Contoso.Snmp1" -UserName "pattiful"

Example 9: Add an SNMP version 3 account with context, authentication, and privacy

This example adds an SNMP version 3 account that specifies context, authentication protocol, and privacy protocol.

The first command gets the SNMP version 3 privacy protocol and key for the account and assigns them to the variable named $Auth.

The second command gets the SNMP version 3 privacy protocol and key for the account and assigns them to the variable named $Privacy.

The third command creates the account, uses the credentials stored in $Auth for the authoring protocol and key, and uses the credentials stored in $Privacy for the privacy protocol and key.

PS C:\> $Auth = Get-Credential
PS C:\>$Privacy = Get-Credential
PS C:\>Add-SCOMRunAsAccount -Snmpv3 -Name "Contoso.Snmp2" -UserName "davidch" -Context "snmp context" -AuthProtocolAndKey $Auth -PrivacyProtocolAndKey $Privacy

Example 10: Add an SCX monitoring account with sudo elevation

This command adds an SCX monitoring account that uses sudo elevation.

PS C:\> Add-SCOMRunAsAccount -SCXMonitoring -Name "Contoso.SCXMon" -RunAsCredential (Get-Credential) -Sudo

Example 11: Add an SCX maintenance account with privileged access

This example adds an SCX maintenance account that has privileged access and uses a passphrase-protected SSH key.

The first command prompts the user to enter the passphrase and stores the passphrase as a secure string in the variable named $Passphrase.

The second command creates the account by using the passphrase stored in $Passphrase.

PS C:\> $Passphrase = Read-Host -AsSecureString
PS C:\> Add-SCOMRunAsAccount -SCXMaintenance -Name "Contoso.SCXMainSSH" -UserName "evannar" -Path "C:\sshkey.ppk" -Passphrase $Passphrase -Privileged

Example 12: Add an SCX maintenance account without privileged access that uses sudo elevation

This command adds an SCX maintenance account that does not have privileged access by specifying a user name and password and sudo elevation.

PS C:\> Add-SCOMRunAsAccount -SCXMaintenance -Name "Contoso.SCXMainUserName" -RunAsCredential (Get-Credential) -Sudo

Example 13: Add an SCX maintenance account that uses superuser elevation

This example adds an SCX maintenance account that does not have privileged access by specifying a user name and password and a superuser account for elevation.

The first command prompts the user to enter the password, converts the user input to a secure string, and stores the password in the $SuPassword variable.

The second command creates the account by specifying the password that is stored in $SuPassword as the superuser password.

PS C:\> $SuPassword = Read-Host -AsSecureString
PS C:\> Add-SCOMRunAsAccount -SCXMaintenance -Name "Contoso.SCXMainUserName" -RunAsCredential (Get-Credential) -Su -SuPassword $SuPassword

Get-SCOMManagementGroupConnection

Get-SCOMRunAsAccount

New-SCOMRunAsAccount

Remove-SCOMRunAsAccount

Update-SCOMRunAsAccount

Set-SCOMRunAsDistribution

Get-Credential