AdfsFarm - X-Guardian/AdfsDsc GitHub Wiki

AdfsFarm

Parameters

Parameter Attribute DataType Description Allowed Values
FederationService Name Key String Specifies the DNS name of the federation service. This value must match the subject name of the specified certificate.
Credential Required PSCredential Specifies a PSCredential object that must have domain administrator privileges.
CertificateThumbprint Write String Specifies the thumbprint of the certificate to use for HTTPS bindings and service communication for ADFS. This value should match the thumbprint of a valid certificate in the Local Computer certificate store.
FederationService DisplayName Write String Specifies the display name of the Federation Service.
GroupServiceAccount Identifier Write String Specifies the Group Managed Service Account under which the Active Directory Federation Services (AD FS) service runs.
Overwrite Configuration Write Boolean This parameter must be used to remove an existing Active Directory Federation Services (AD FS) configuration database and overwrite it with a new database.
ServiceAccount Credential Write PSCredential Specifies the Active Directory account under which the AD FS service runs in the form: <user name>.
SQLConnectionString Write String Specifies the SQL Server database that will store the AD FS configuration settings. If not specified, the AD FS installer uses the Windows Internal Database to store configuration settings.
AdminConfiguration Write MSFT_KeyValuePair[] Specifies the Admin Configuration
Ensure Read String The state of the ADFS Farm.
CertificateDnsName Write String Specifies the DNS name of the certificate to use for HTTPS bindings and service communication for ADFS. This value should match the DNS name of a valid certificate in the Local Computer certificate store.
SigningCertificate DnsName Write String Specifies the DNS name of the signing certificate for ADFS. This value should match the DNS name of a valid certificate in the Local Computer certificate store.
DecryptionCertificate DnsName Write String Specifies the DNS name of the decryption certificate for ADFS. This value should match the DNS name of a valid certificate in the Local Computer certificate store.

Description

The AdfsFarm DSC resource manages the installation of an Active Directory Federation Services server farm, and the primary node of the farm. To further manage the configuration of ADFS, the ADFSProperties DSC resource should be used.

Note: removal of the ADFS server farm using this resource is not supported. Remove the Adfs-Federation role from the server instead.

Examples

Example 1

This configuration will create the first node in an Active Directory Federation Services (AD FS) server farm using the Windows Internal Database (WID) on the local server computer.

The certificate with the specified thumbprint will be used as the SSL certificate and the service communications certificate. Automatically generated, self-signed certificates will be used for the token signing and token decryption certificates.

The standard user account specified in the ServiceAccountCredential parameter will be used for the service account.

Configuration AdfsFarm_ServiceAccount_WID_Config
{
    Param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $ServiceAccountCredential,

        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $DomainAdminCredential
    )

    Import-DscResource -ModuleName PSDesiredStateConfiguration
    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        WindowsFeature InstallAdfs
        {
            Name = 'ADFS-Federation'
        }

        AdfsFarm Contoso
        {
            FederationServiceName        = 'fs.corp.contoso.com'
            FederationServiceDisplayName = 'Contoso ADFS Service'
            CertificateThumbprint        = '8169c52b4ec6e77eb2ae17f028fe5da4e35c0bed'
            ServiceAccountCredential     = $ServiceAccountCredential
            Credential                   = $DomainAdminCredential
        }
    }
}

Example 2

This configuration will create the first node in an Active Directory Federation Services (AD FS) server farm using the Windows Internal Database (WID) on the local server computer.

The certificate with the specified thumbprint will be used as the SSL certificate and the service communications certificate. Automatically generated, self-signed certificates will be used for the token signing and token decryption certificates.

The group Managed Service Account specified in the GroupServiceAccountIdentifier parameter will be used for the service account.

Configuration AdfsFarm_gMSA_WID_Config
{
    Param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $DomainAdminCredential
    )

    Import-DscResource -ModuleName PSDesiredStateConfiguration
    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        WindowsFeature InstallAdfs
        {
            Name = 'ADFS-Federation'
        }

        AdfsFarm Contoso
        {
            FederationServiceName         = 'fs.corp.contoso.com'
            FederationServiceDisplayName  = 'Contoso ADFS Service'
            CertificateThumbprint         = '8169c52b4ec6e77eb2ae17f028fe5da4e35c0bed'
            GroupServiceAccountIdentifier = 'contoso\adfsgmsa$'
            Credential                    = $DomainAdminCredential
        }
    }
}

Example 3

This configuration will create the first node in an Active Directory Federation Services (AD FS) server farm using a Microsoft SQL Server database on a remote computer named sql01.contoso.com using Windows Authentication.

The certificate with the specified thumbprint will be used as the SSL certificate and the service communications certificate. Automatically generated, self-signed certificates will be used for the token signing and token decryption certificates.

The group Managed Service Account specified in the GroupServiceAccountIdentifier parameter will be used for the service account.

Configuration AdfsFarm_gMSA_SQL_Integrated_Config
{
    Param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $DomainAdminCredential
    )

    Import-DscResource -ModuleName PSDesiredStateConfiguration
    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        WindowsFeature InstallAdfs
        {
            Name = 'ADFS-Federation'
        }

        AdfsFarm Contoso
        {
            FederationServiceName         = 'fs.corp.contoso.com'
            FederationServiceDisplayName  = 'Contoso ADFS Service'
            CertificateThumbprint         = '8169c52b4ec6e77eb2ae17f028fe5da4e35c0bed'
            GroupServiceAccountIdentifier = 'contoso\adfsgmsa$'
            SQLConnectionString           = 'Data Source=sql01.contoso.com;Integrated Security=True'
            Credential                    = $DomainAdminCredential
        }
    }
}

Example 4

This configuration will create the first node in an Active Directory Federation Services (AD FS) server farm using a Microsoft SQL Server database on a remote computer named sql01.contoso.com using SQL Authentication.

The certificate with the specified thumbprint will be used as the SSL certificate and the service communications certificate. Automatically generated, self-signed certificates will be used for the token signing and token decryption certificates.

The group Managed Service Account specified in the GroupServiceAccountIdentifier parameter will be used for the service account.

Configuration AdfsFarm_gMSA_SQL_Config
{
    Param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $DomainAdminCredential,
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $SqlCredential
    )

    Import-DscResource -ModuleName PSDesiredStateConfiguration
    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        WindowsFeature InstallAdfs
        {
            Name = 'ADFS-Federation'
        }

        $SqlUserName = $SqlCredential.UserName
        $SqlPassword = $SqlCredential.GetNetworkCredential().Password

        AdfsFarm Contoso
        {
            FederationServiceName         = 'fs.corp.contoso.com'
            FederationServiceDisplayName  = 'Contoso ADFS Service'
            CertificateThumbprint         = '8169c52b4ec6e77eb2ae17f028fe5da4e35c0bed'
            GroupServiceAccountIdentifier = 'contoso\adfsgmsa$'
            SQLConnectionString           = "Data Source=sql01.contoso.com;User ID=$SqlUserName;Password=$SqlPassword"
            Credential                    = $DomainAdminCredential
        }
    }
}

Example 5

This configuration will create the first node in an Active Directory Federation Services (AD FS) server farm using a Microsoft SQL Server database on a remote computer named sql01.contoso.com using Windows Authentication.

The certificate with the specified thumbprint will be used as the SSL certificate and the service communications certificate. Automatically generated, self-signed certificates will be used for the token signing and token decryption certificates.

The group Managed Service Account specified in the GroupServiceAccountIdentifier parameter will be used for the service account.

The AdminConfiguration parameter will be used to pass the CN of a pre-configured ADFS Active Directory configuration object, removing the requirement of needing Domain Admin credentials for the ADFS Farm install. See https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/deployment/install-ad-fs-delegated-admin for further details.

Configuration AdfsFarm_gMSA_SQL_Integrated_Delegated_Admin_Config
{
    Param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $LocalAdminCredential
    )

    Import-DscResource -ModuleName PSDesiredStateConfiguration
    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        WindowsFeature InstallAdfs
        {
            Name = 'ADFS-Federation'
        }

        AdfsFarm Contoso
        {
            FederationServiceName         = 'fs.corp.contoso.com'
            FederationServiceDisplayName  = 'Contoso ADFS Service'
            CertificateThumbprint         = '8169c52b4ec6e77eb2ae17f028fe5da4e35c0bed'
            GroupServiceAccountIdentifier = 'contoso\adfsgmsa$'
            SQLConnectionString           = 'Data Source=sql01.contoso.com;Integrated Security=True'
            Credential                    = $LocalAdminCredential
            AdminConfiguration            = @(
                @{
                    DKMContainerDn = 'CN=9530440c-bc84-4fe6-a3f9-8d60162a7bcf,CN=ADFS,CN=Microsoft,CN=Program Data,DC=contoso,DC=com'
                }
            )
        }
    }
}

Example 6

This configuration will create the first node in an Active Directory Federation Services (AD FS) server farm using the Windows Internal Database (WID) on the local server computer.

The certificate with the specified Certificate DNS name will be used as the SSL certificate and the service communications certificate. The certificate with the specified signing certificate DNS name will be used as the signing certificate and the certificate with the specified decryption certificate DNS name will be used for the decryption certificate.

The group Managed Service Account specified in the GroupServiceAccountIdentifier parameter will be used for the service account.

Configuration AdfsFarm_gMSA_Custom_Certs
{
    Param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $DomainAdminCredential
    )

    Import-DscResource -ModuleName PSDesiredStateConfiguration
    Import-DscResource -ModuleName AdfsDsc

    Node localhost
    {
        WindowsFeature InstallAdfs
        {
            Name = 'ADFS-Federation'
        }

        AdfsFarm Contoso
        {
            FederationServiceName         = 'fs.corp.contoso.com'
            FederationServiceDisplayName  = 'Contoso ADFS Service'
            CertificateDnsName            = 'fs.corp.contoso.com'
            SigningCertificateDnsName     = 'ADFS Signing - fs.corp.contoso.com'
            DecryptionCertificateDnsName  = 'ADFS Encryption - fs.corp.contoso.com'
            GroupServiceAccountIdentifier = 'contoso\adfsgmsa$'
            Credential                    = $DomainAdminCredential
        }
    }
}
⚠️ **GitHub.com Fallback** ⚠️