DSCResources/DSC_SqlLogin/en-US/about_SqlLogin.help.txt
|
.NAME
SqlLogin .DESCRIPTION The SqlLogin DSC resource manages SQL Server logins for a SQL Server instance. ## Requirements * Target machine must be running Windows Server 2012 or later. * Target machine must be running SQL Server Database Engine 2012 or later. * When the LoginType of 'SqlLogin' is used, then the login authentication mode must have been set to Mixed or Normal. If set to Integrated and error will be thrown. * The LoginMustChangePassword parameter is only valid on a SqlLogin where the LoginType parameter is set to 'SqlLogin'. * The LoginMustChangePassword parameter can not be used to change this setting on a pre-existing SqlLogin - This parameter can only be used when creating a new SqlLogin and where subsequent updates will not be applied or, alternatively, when the desired state will not change (for example, where LoginMustChangePassword is initially set to $false and will always be set to $false). * The LoginPasswordPolicyEnforced parameter cannot be set to $false if the parameter LoginPasswordExpirationEnabled is set to $true, or if the property PasswordExpirationEnabled of the login has already been set to $true by other means. It will result in the error "The CHECKEXPIRATION option cannot be used when CHECKPOLICY is OFF". If the parameter LoginPasswordPolicyEnforced is set to to $false then LoginPasswordExpirationEnabled must also be set to $false. ## Known issues All issues are not listed here, see https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+SqlLogin. .PARAMETER Name Key - String The name of the login. .PARAMETER InstanceName Key - String Name of the SQL Server instance to be configured. .PARAMETER Ensure Write - String Allowed values: Present, Absent The specified login should be 'Present' or 'Absent'. Default is 'Present'. .PARAMETER LoginType Write - String Allowed values: WindowsUser, WindowsGroup, SqlLogin, Certificate, AsymmetricKey, ExternalUser, ExternalGroup The type of login to be created. If LoginType is 'WindowsUser' or 'WindowsGroup' then provide the name in the format DOMAIN\name. Default is 'WindowsUser'. The login types 'Certificate', 'AsymmetricKey', 'ExternalUser', and 'ExternalGroup' are not yet implemented and will currently throw an exception if used. .PARAMETER ServerName Write - String The hostname of the SQL Server to be configured. Default value is the current computer name. .PARAMETER LoginCredential Write - Instance Specifies the password as a [PSCredential] object. Only applies to SQL Logins. .PARAMETER LoginMustChangePassword Write - Boolean Specifies if the login is required to have its password change on the next login. Only applies to SQL Logins. This cannot be updated on a pre-existing SQL Login and any attempt to do this will throw an exception. .PARAMETER LoginPasswordExpirationEnabled Write - Boolean Specifies if the login password is required to expire in accordance to the operating system security policy. Only applies to SQL Logins. .PARAMETER LoginPasswordPolicyEnforced Write - Boolean Specifies if the login password is required to conform to the password policy specified in the system security policy. Only applies to SQL Logins. .PARAMETER Disabled Write - Boolean Specifies if the login is disabled. Default value is $false. .PARAMETER DefaultDatabase Write - String Specifies the default database name. .EXAMPLE 1 This example shows how to ensure that the Windows user 'CONTOSO\WindowsUser', Windows group 'CONTOSO\WindowsGroup', and the SQL Login 'SqlLogin' exists. Configuration Example { param ( [Parameter(Mandatory = $true)] [System.Management.Automation.PSCredential] $SqlAdministratorCredential, [Parameter(Mandatory = $true)] [System.Management.Automation.PSCredential] $LoginCredential ) Import-DscResource -ModuleName 'SqlServerDsc' node localhost { SqlLogin 'Add_WindowsUser' { Ensure = 'Present' Name = 'CONTOSO\WindowsUser' LoginType = 'WindowsUser' ServerName = 'TestServer.company.local' InstanceName = 'DSC' PsDscRunAsCredential = $SqlAdministratorCredential } SqlLogin 'Add_DisabledWindowsUser' { Ensure = 'Present' Name = 'CONTOSO\WindowsUser2' LoginType = 'WindowsUser' ServerName = 'TestServer.company.local' InstanceName = 'DSC' PsDscRunAsCredential = $SqlAdministratorCredential Disabled = $true } SqlLogin 'Add_WindowsUser_Set_Default_Database' { Ensure = 'Present' Name = 'CONTOSO\WindowsUser3' LoginType = 'WindowsUser' ServerName = 'TestServer.company.local' InstanceName = 'DSC' DefaultDatabase = 'contoso' PsDscRunAsCredential = $SqlAdministratorCredential } SqlLogin 'Add_WindowsGroup' { Ensure = 'Present' Name = 'CONTOSO\WindowsGroup' LoginType = 'WindowsGroup' ServerName = 'TestServer.company.local' InstanceName = 'DSC' PsDscRunAsCredential = $SqlAdministratorCredential } SqlLogin 'Add_SqlLogin' { Ensure = 'Present' Name = 'SqlLogin' LoginType = 'SqlLogin' ServerName = 'TestServer.company.local' InstanceName = 'DSC' LoginCredential = $LoginCredential LoginMustChangePassword = $false LoginPasswordExpirationEnabled = $true LoginPasswordPolicyEnforced = $true PsDscRunAsCredential = $SqlAdministratorCredential } } } .EXAMPLE 2 This example shows how to remove the Windows user 'CONTOSO\WindowsUser', Windows group 'CONTOSO\WindowsGroup', and the SQL Login 'SqlLogin'. Configuration Example { Import-DscResource -ModuleName 'SqlServerDsc' node localhost { SqlLogin 'Remove_WindowsUser' { Ensure = 'Absent' Name = 'CONTOSO\WindowsUser' LoginType = 'WindowsUser' ServerName = 'TestServer.company.local' InstanceName = 'DSC' } SqlLogin 'Remove_WindowsGroup' { Ensure = 'Absent' Name = 'CONTOSO\WindowsGroup' LoginType = 'WindowsGroup' ServerName = 'TestServer.company.local' InstanceName = 'DSC' } SqlLogin 'Remove_SqlLogin' { Ensure = 'Absent' Name = 'SqlLogin' LoginType = 'SqlLogin' ServerName = 'TestServer.company.local' InstanceName = 'DSC' } } } |