Test-DbaAgSpn

Synopsis

Validates Service Principal Name registration for Availability Group listeners in Active Directory

Description

Checks whether the required SPNs are properly registered in Active Directory for each Availability Group listener’s service account. This function queries AD to verify that both the MSSQLSvc/listener.domain.com and MSSQLSvc/listener.domain.com:port SPNs exist, which are essential for Kerberos authentication to work correctly with AG listeners.

Use this to troubleshoot client connectivity issues, validate SPN configuration before deployments, or audit security compliance. Missing SPNs will cause authentication failures when clients attempt to connect using integrated Windows authentication through the listener.

https://learn.microsoft.com/en-us/sql/database-engine/availability-groups/windows/listeners-client-connectivity-application-failover?view=sql-server-ver16#SPNs was used as a guide

Syntax

Test-DbaAgSpn
    [[-SqlInstance] <DbaInstanceParameter[]>]
    [[-SqlCredential] <PSCredential>]
    [[-Credential] <PSCredential>]
    [[-AvailabilityGroup] <String[]>]
    [[-Listener] <String[]>]
    [[-InputObject] <AvailabilityGroup[]>]
    [-EnableException]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Get-DbaAvailabilityGroup -SqlInstance sql01 -AvailabilityGroup SharePoint | Test-DbaAgSpn

Tests the SPNs for the SharePoint availability group listeners on sql01

Example: 2

PS C:\> Test-DbaAgSpn -SqlInstance sql01 -AvailabilityGroup SharePoint -Listener spag01

Tests the spag01 SPN for the SharePoint availability group listener on sql01

Example: 3

PS C:\> Test-DbaAgSpn -SqlInstance sql01 | Set-DbaSpn

Tests the SPNs for all availability group listeners on sql01 and sets them if they are not set

Optional Parameters

-SqlInstance

The target SQL Server instance or instances. Server version must be SQL Server version 2012 or higher.

-SqlCredential

Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
For MFA support, please use Connect-DbaInstance.

-Credential

Alternative credential for connecting to Active Directory.

-AvailabilityGroup

Specifies which availability groups to validate SPNs for by name. Use this when you need to check specific AGs instead of all AGs on the instance.
If not specified, all availability groups will be tested. Accepts multiple AG names for bulk validation.

-Listener

Specifies which AG listeners to validate SPNs for by listener name. Use this when troubleshooting specific listener connectivity issues.
If not specified, all listeners within the specified availability groups will be tested. Accepts multiple listener names.

-InputObject

Accepts availability group objects from Get-DbaAvailabilityGroup for pipeline processing. Use this to chain commands when working with specific AG objects.
This allows for filtering AGs before SPN validation without needing to specify instance and AG names separately.

-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with “sea of red” exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this “nice by default” feature off and enables you to catch exceptions with your own try/catch.

Outputs

PSCustomObject

Returns one object per SPN validation result. For each listener, two objects are returned - one for the SPN without port (e.g., MSSQLSvc/listener.domain.com) and one with port (e.g., MSSQLSvc/listener.domain.com:1433). The function queries Active Directory to verify SPN registration and reports the validation status.

Properties:

• ComputerName: The fully qualified network name of the computer hosting the SQL Server instance
• SqlInstance: The SQL Server instance name
• InstanceName: The instance name (defaults to MSSQLSERVER for default instance)
• SqlProduct: The SQL Server product version string including edition and platform information
• InstanceServiceAccount: The service account running SQL Server (may be modified if virtual or managed service account is detected)
• RequiredSPN: The Service Principal Name that should be registered in Active Directory
• IsSet: Boolean indicating whether the required SPN is currently registered in Active Directory (true if found, false if missing)
• Cluster: Boolean indicating whether SQL Server is running in a clustered configuration
• TcpEnabled: Boolean indicating whether TCP protocol is enabled (always true for AG listeners)
• Port: The TCP port number the listener uses
• DynamicPort: Boolean indicating whether dynamic port allocation is enabled (always false for AG listeners)
• Warning: Reserved for warning messages; contains “None” unless a warning condition is detected
• Error: Contains “SPN missing” if the SPN is not found in Active Directory, or “None” if the SPN is properly registered Note: The Credential and DomainName properties are excluded from the default display but remain accessible using Select-Object *.