New‑SqlDscLogin - dsccommunity/SqlServerDsc GitHub Wiki

SYNOPSIS

Creates a new login on a SQL Server Database Engine instance.

SYNTAX

WindowsUser (Default)

New-SqlDscLogin -ServerObject <Server> -Name <String> [-WindowsUser] [-DefaultDatabase <String>]
 [-DefaultLanguage <String>] [-Disabled] [-Force] [-PassThru] [-WhatIf]
 [-Confirm] [<CommonParameters>]

AsymmetricKey

New-SqlDscLogin -ServerObject <Server> -Name <String> [-AsymmetricKey] -AsymmetricKeyName <String>
 [-DefaultDatabase <String>] [-DefaultLanguage <String>] [-Disabled] [-Force] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

Certificate

New-SqlDscLogin -ServerObject <Server> -Name <String> [-Certificate] -CertificateName <String>
 [-DefaultDatabase <String>] [-DefaultLanguage <String>] [-Disabled] [-Force] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

SqlLoginHashed

New-SqlDscLogin -ServerObject <Server> -Name <String> [-SqlLogin] -SecurePassword <SecureString>
 [-DefaultDatabase <String>] [-DefaultLanguage <String>] [-IsHashed] [-Disabled] [-Force] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

SqlLogin

New-SqlDscLogin -ServerObject <Server> -Name <String> [-SqlLogin] -SecurePassword <SecureString>
 [-DefaultDatabase <String>] [-DefaultLanguage <String>] [-PasswordExpirationEnabled] [-PasswordPolicyEnforced]
 [-MustChangePassword] [-Disabled] [-Force] [-PassThru] [-WhatIf]
 [-Confirm] [<CommonParameters>]

WindowsGroup

New-SqlDscLogin -ServerObject <Server> -Name <String> [-WindowsGroup] [-DefaultDatabase <String>]
 [-DefaultLanguage <String>] [-Disabled] [-Force] [-PassThru] [-WhatIf]
 [-Confirm] [<CommonParameters>]

DESCRIPTION

This command creates a new login on a SQL Server Database Engine instance. The login can be a SQL Server login, a Windows login (user or group), a certificate-based login, or an asymmetric key-based login.

EXAMPLES

EXAMPLE 1

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$securePassword = ConvertTo-SecureString -String 'MyPassword123!' -AsPlainText -Force
$serverObject | New-SqlDscLogin -Name 'MyLogin' -SqlLogin -SecurePassword $securePassword

Creates a new SQL Server login named 'MyLogin' with the specified password.

EXAMPLE 2

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$securePassword = ConvertTo-SecureString -String 'MyPassword123!' -AsPlainText -Force
$serverObject | New-SqlDscLogin -Name 'MyLogin' -SqlLogin -SecurePassword $securePassword -MustChangePassword

Creates a new SQL Server login named 'MyLogin' with a SecureString password that must be changed on first login.

EXAMPLE 3

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$serverObject | New-SqlDscLogin -Name 'DOMAIN\MyUser' -WindowsUser

Creates a new Windows user login for 'DOMAIN\MyUser'.

EXAMPLE 4

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$serverObject | New-SqlDscLogin -Name 'DOMAIN\MyGroup' -WindowsGroup

Creates a new Windows group login for 'DOMAIN\MyGroup'.

EXAMPLE 5

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$serverObject | New-SqlDscLogin -Name 'MyCertLogin' -Certificate -CertificateName 'MyCertificate'

Creates a new certificate-based login using the specified certificate.

EXAMPLE 6

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$hashedPassword = ConvertTo-SecureString -String '0x020012345678...' -AsPlainText -Force
$serverObject | New-SqlDscLogin -Name 'MyHashedLogin' -SqlLogin -SecurePassword $hashedPassword -IsHashed

Creates a new SQL Server login with a pre-hashed password. Note that password policy options (PasswordExpirationEnabled, PasswordPolicyEnforced, MustChangePassword) cannot be used with hashed passwords.

EXAMPLE 7

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$securePassword = ConvertTo-SecureString -String 'MyPassword123!' -AsPlainText -Force
$loginObject = $serverObject | New-SqlDscLogin -Name 'MyLogin' -SqlLogin -SecurePassword $securePassword -PassThru

Creates a new SQL Server login and returns the Login object.

EXAMPLE 8

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$serverObject | New-SqlDscLogin -Name 'MyAsymmetricKeyLogin' -AsymmetricKey -AsymmetricKeyName 'MyAsymmetricKey'

Creates a new asymmetric key-based login using the specified asymmetric key.

EXAMPLE 9

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$serverObject | New-SqlDscLogin -Name 'MyAsymmetricKeyLogin' -AsymmetricKey -AsymmetricKeyName 'MyAsymmetricKey' -PassThru

Creates a new asymmetric key-based login and returns the Login object.

EXAMPLE 10

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$securePassword = ConvertTo-SecureString -String 'NewPassword123!' -AsPlainText -Force
$serverObject | New-SqlDscLogin -Name 'ExistingLogin' -SqlLogin -SecurePassword $securePassword -Force

Creates a SQL Server login named 'ExistingLogin' without confirmation prompts. Note: If the login already exists, the command throws a terminating error.

EXAMPLE 11

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$securePassword = ConvertTo-SecureString -String 'MyPassword123!' -AsPlainText -Force
$serverObject | New-SqlDscLogin -Name 'DisabledLogin' -SqlLogin -SecurePassword $securePassword -Disabled

Creates a new SQL Server login in a disabled state.

EXAMPLE 12

$serverObject = Connect-SqlDscDatabaseEngine -InstanceName 'MyInstance'
$serverObject | New-SqlDscLogin -Name 'DOMAIN\DisabledUser' -WindowsUser -Disabled -PassThru

Creates a new disabled Windows user login and returns the Login object.

PARAMETERS

-AsymmetricKey

Specifies that an asymmetric key-based login should be created.

Type: SwitchParameter
Parameter Sets: AsymmetricKey
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-AsymmetricKeyName

Specifies the asymmetric key name when creating an asymmetric key-based login.

Type: String
Parameter Sets: AsymmetricKey
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Certificate

Specifies that a certificate-based login should be created.

Type: SwitchParameter
Parameter Sets: Certificate
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-CertificateName

Specifies the certificate name when creating a certificate-based login.

Type: String
Parameter Sets: Certificate
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-DefaultDatabase

Specifies the default database for the login. If not specified, 'master' will be used as the default database.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: Master
Accept pipeline input: False
Accept wildcard characters: False

-DefaultLanguage

Specifies the default language for the login.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Disabled

Specifies whether the login should be created in a disabled state.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Force

Specifies that the login should be created without any confirmation.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-IsHashed

Specifies whether the provided password is already hashed. Only applies when creating a SQL Server login.

Type: SwitchParameter
Parameter Sets: SqlLoginHashed
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-MustChangePassword

Specifies whether the user must change the password on next login. Only applies when creating a SQL Server login.

Type: SwitchParameter
Parameter Sets: SqlLogin
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Name

Specifies the name of the login to be created.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-PassThru

If specified, the created login object will be returned.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-PasswordExpirationEnabled

Specifies whether password expiration is enabled for SQL Server logins. Only applies when creating a SQL Server login.

Type: SwitchParameter
Parameter Sets: SqlLogin
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-PasswordPolicyEnforced

Specifies whether password policy is enforced for SQL Server logins. Only applies when creating a SQL Server login.

Type: SwitchParameter
Parameter Sets: SqlLogin
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-SecurePassword

Specifies the password as a SecureString for SQL Server logins. This parameter is required when creating a SQL Server login.

Type: SecureString
Parameter Sets: SqlLoginHashed, SqlLogin
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ServerObject

Specifies current server connection object.

Type: Server
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-SqlLogin

Specifies that a SQL Server login should be created.

Type: SwitchParameter
Parameter Sets: SqlLoginHashed, SqlLogin
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-WindowsGroup

Specifies that a Windows group login should be created.

Type: SwitchParameter
Parameter Sets: WindowsGroup
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-WindowsUser

Specifies that a Windows user login should be created.

Type: SwitchParameter
Parameter Sets: WindowsUser
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

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

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

`Microsoft.SqlServer.Management.Smo.Server`

Accepted from the pipeline. This cmdlet accepts a SMO Server

object (for example, the output of `Connect-SqlDscDatabaseEngine`) via the pipeline.

OUTPUTS

`Microsoft.SqlServer.Management.Smo.Login`

When passing parameter PassThru.

NOTES

This command has the confirm impact level set to medium since a login is created but by default it does not have any special permissions.