Credential overview

Group Managed Service Account

To support Group Managed Service Accounts (gMSAs) the DSC resource must support it. This also applies to Managed Service Accounts (MSAs).

There are more information about using (g)MSAs with SQL Server

in the article Configure Windows Service Accounts and Permissions in section Managed Service Accounts, Group Managed Service Accounts, and Virtual Accounts

To use a (g)MSA with a DSC resource you should pass the (g)MSA account name in the credential object and use any text string as password.

It is not possible to pass $null as password, it is a limitation by how the MOF is generated when encrypting passwords.

If there is a resource that you find that will not work with a (g)MSAs then please submit a new issue. Then the community can work together to support (g)MSAs for that DSC resource too.

For designing a resource for (g)MSAs see the section Group Managed Service Account in the contribution guidelines.

^{This was discussed in issue #738.}

Built-In Account

To use a built-in account with a DSC resource you should pass the built-in account name, e.g. 'NT AUTHORITY\NetworkService' in the credential object and use any text string as password.

It is not possible to pass $null as password, it is a limitation by how the MOF is generated when encrypting passwords.

If there is a resource that you find that will not work with a built-in account then please submit a new issue. Then the community can work together to support built-in accounts for that DSC resource too.

Windows User Credentials

When using Windows user credentials (i.e., LoginType = 'WindowsUser') with SqlServerDsc resources, there are important considerations regarding the username format used in Credential, UserName, and Password parameters.

Supported Username Formats

The following username formats can be used when creating Windows credentials:

Format	Example	Works with SQLPS (SQL 2016)	Works with SqlServer module
FQDN (UPN)	user@domain.local	✅ Yes	✅ Yes
Username only	user	✅ Yes	✅ Yes
NetBIOS	DOMAIN\user	❌ No	✅ Yes

Important: The NetBIOS format (DOMAIN\user) does not work with the legacy SQLPS module (SQL Server 2016 and earlier). When using SQLPS, you must use either FQDN format (user@domain.local) or just the username without domain prefix.

Recommendations

1. Prefer FQDN format (user@domain.local) for maximum compatibility across all SQL Server versions and PowerShell modules.
2. Avoid NetBIOS format (DOMAIN\user) when targeting SQL Server 2016 or environments where SQLPS may be used.
3. Use the exact username format required by the target environment when passing credentials to commands or DSC resources.

Example: Creating a Windows User Credential

$password = ConvertTo-SecureString 'P@ssw0rd1' -AsPlainText -Force
$username = 'user@company.local'
$credential = [PSCredential]::new($username, $password)

$password = ConvertTo-SecureString 'P@ssw0rd1' -AsPlainText -Force
$username = 'user'
$credential = [PSCredential]::new($username, $password)

When using these credentials with SqlServerDsc resources, pass them via the built-in PsDscRunAsCredential, credential or password parameters. This example shows the built-in PsDscRunAsCredential parameter:

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $SqlAdministratorCredential
    )

    Import-DscResource -ModuleName 'SqlServerDsc'

    node localhost
    {
        SqlLogin 'Add_WindowsUser'
        {
            Ensure               = 'Present'
            Name                 = 'CONTOSO\WindowsUser'
            LoginType            = 'WindowsUser'
            ServerName           = 'TestServer.company.local'
            InstanceName         = 'DSC'
            PsDscRunAsCredential = $SqlAdministratorCredential
        }
    }
}

This section was informed by issue #1223.