NewResourceName: AdcsAiaExtension. A feature to add/remove AIA URI extensions - New Resource Issue #78.

ActiveDirectoryCSDsc.psd1

@@ -41,7 +41,8 @@
         'AdcsEnrollmentPolicyWebService',
         'AdcsOnlineResponder',
         'AdcsWebEnrollment',
-        'AdcsOcspExtension'
+        'AdcsOcspExtension',
+        'AdcsAiaExtension'
         )
 
     # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
@@ -84,4 +85,3 @@
         } # End of PSData hashtable
     } # End of PrivateData hashtable
 }
-

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Added new resource AdcsAiaExtension - see [Issue #78](https://github.com/PowerShell/ActiveDirectoryCSDsc/issues/78).
 - Remove reference to StorageDsc in README.md - fixes [Issue #76](https://github.com/PowerShell/ActiveDirectoryCSDsc/issues/76).
 
 ## 3.2.0.0

DSCResources/MSFT_AdcsAiaExtension/MSFT_AdcsAiaExtension.psm1

@@ -0,0 +1,273 @@
+$modulePath = Join-Path -Path (Split-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -Parent) -ChildPath 'Modules'
+
+# Import the ADCS Deployment Resource Common Module.
+Import-Module -Name (Join-Path -Path $modulePath `
+        -ChildPath (Join-Path -Path 'ActiveDirectoryCSDsc.CommonHelper' `
+            -ChildPath 'ActiveDirectoryCSDsc.CommonHelper.psm1'))
+
+# Import the ADCS Deployment Resource Helper Module.
+Import-Module -Name (Join-Path -Path $modulePath `
+        -ChildPath (Join-Path -Path 'ActiveDirectoryCSDsc.ResourceHelper' `
+            -ChildPath 'ActiveDirectoryCSDsc.ResourceHelper.psm1'))
+
+# Import Localization Strings.
+$LocalizedData = Get-LocalizedData `
+    -ResourceName 'MSFT_AdcsAiaExtension' `
+    -ResourcePath (Split-Path -Parent $script:MyInvocation.MyCommand.Path)
+
+<#
+    .SYNOPSIS
+        Gets the current certificate Authority Information Access (AIA) Uniform Resource Identifiers (URI)
+        settings.
+
+    .PARAMETER IsSingleInstance
+        Specifies the resource is a single instance, the value must be 'Yes'.
+        Not used in Get-TargetResource.
+
+    .PARAMETER AiaUri
+        Specifies the URI location where issuer of certificate is located.
+        Not used in Get-TargetResource.
+
+    .PARAMETER RestartService
+        Specifies if the service should be restarted.
+        Not used in Get-TargetResource.
+
+    .PARAMETER Ensure
+        Ensures that the Authority Information Access (AIA) Uniform Resource Identifiers (URI) is Present or Absent.
+        Not used in Get-TargetResource.
+#>
+function Get-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [System.String]
+        $IsSingleInstance,
+
+        [Parameter(Mandatory = $true)]
+        [System.String[]]
+        $AiaUri,
+
+        [Parameter()]
+        [System.Boolean]
+        $RestartService,
+
+        [Parameter()]
+        [ValidateSet('Present', 'Absent')]
+        [System.String]
+        $Ensure = 'Present'
+    )
+
+    Write-Verbose -Message $localizedData.GetAiaUris
+
+    [System.Array] $currentAiaUriList = (Get-CAAuthorityInformationAccess).Where( {
+            $_.AddToCertificateAia -eq $true
+        } ).Uri
+
+    return @{
+        AiaUri      = $currentAiaUriList
+        Ensure           = $Ensure
+        IsSingleInstance = $IsSingleInstance
+        RestartService   = $RestartService
+    }
+}
+
+<#
+    .SYNOPSIS
+        Configures the current Authority Information Access (AIA) settings for the certification authority.
+
+    .PARAMETER IsSingleInstance
+        Specifies the resource is a single instance, the value must be 'Yes'.
+
+    .PARAMETER AiaUri
+        Specifies the URI location where issuer of certificate is located.
+
+    .PARAMETER RestartService
+        Specifies if the service should be restarted.
+
+    .PARAMETER Ensure
+        Ensures that the Authority Information Access (AIA) Uniform Resource Identifiers (URI) is Present or Absent.
+#>
+function Set-TargetResource
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [System.String]
+        $IsSingleInstance,
+
+        [Parameter(Mandatory = $true)]
+        [System.String[]]
+        $AiaUri,
+
+        [Parameter()]
+        [System.Boolean]
+        $RestartService,
+
+        [Parameter()]
+        [ValidateSet('Present', 'Absent')]
+        [System.String]
+        $Ensure = 'Present'
+    )
+
+    $currentState = Get-TargetResource @PSBoundParameters
+    $change = $false
+
+    if ($Ensure -eq 'Present')
+    {
+        foreach ($uri in $currentState.AiaUri)
+        {
+            if ($AiaUri -notcontains $uri)
+            {
+                Write-Verbose -Message ($localizedData.RemoveAiAUri -f $uri)
+                Remove-CAAuthorityInformationAccess -Uri $uri -AddToCertificateAIA -Force
+                $change = $true
+            }
+        }
+
+        foreach ($uri in $AiaUri)
+        {
+            if ($currentState.AiaUri -contains $uri)
+            {
+                Write-Verbose -Message ($localizedData.RemoveAiAUri -f $uri)
+                Remove-CAAuthorityInformationAccess -Uri $uri -AddToCertificateAIA -Force
+                $change = $true
+            }
+
+            Write-Verbose -Message ($localizedData.AddAiAUri -f $uri)
+            Add-CAAuthorityInformationAccess -Uri $uri -AddToCertificateAIA -Force
+            $change = $true
+        }
+    }
+    else
+    {
+        foreach ($uri in $AiaUri)
+        {
+            Write-Verbose -Message ($localizedData.RemoveAiaUri -f $uri)
+            Remove-CAAuthorityInformationAccess -Uri $uri -Force -ErrorAction Stop
+            $change = $true
+        }
+    }
+
+    if (($RestartService) -and ($change))
+    {
+        Write-Verbose -Message $localizedData.RestartService
+        Restart-ServiceIfExists -Name CertSvc
+    }
+}
+
+<#
+    .SYNOPSIS
+        Tests the current certification authority AddToCertificateAia (boolean) and Uniform Resource Identifiers (URI)
+        settings.
+
+    .PARAMETER IsSingleInstance
+        Specifies the resource is a single instance, the value must be 'Yes'.
+
+    .PARAMETER AiaUri
+        Specifies the URI location where issuer of certificate is located.
+
+    .PARAMETER RestartService
+        Specifies if the service should be restarted.
+
+    .PARAMETER Ensure
+        Ensures that the Authority Information Access (AIA) Uniform Resource Identifiers (URI) is Present or Absent.
+#>
+function Test-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Yes')]
+        [System.String]
+        $IsSingleInstance,
+
+        [Parameter(Mandatory = $true)]
+        [System.String[]]
+        $AiaUri,
+
+        [Parameter()]
+        [System.Boolean]
+        $RestartService,
+
+        [Parameter()]
+        [ValidateSet('Present', 'Absent')]
+        [System.String]
+        $Ensure = 'Present'
+    )
+
+    $currentState = Get-TargetResource @PSBoundParameters
+
+    $inDesiredState = $true
+
+    if ($Ensure -eq 'Present')
+    {
+        if ($currentState.AiaUri.Count -ne $AiaUri.Count)
+        {
+            if ($null -ne $currentState.AiaUri)
+            {
+                $compareAiaUris = Compare-Object -ReferenceObject $AiaUri -DifferenceObject $currentState.AiaUri -PassThru
+
+                # Desired state AIA URI(s) not found in reference set.
+                $desiredAiaUrisMissing = $compareAiaUris.Where( {
+                        $_.SideIndicator -eq '<='
+                    } ) -join ', '
+
+                # AIA URI(s) found in $currentState that do not match $AiaUri desired state.
+                $notDesiredAiaUrisFound = $compareAiaUris.Where( {
+                        $_.SideIndicator -eq '=>'
+                    } ) -join ', '
+
+                if ($desiredAiaUrisMissing)
+                {
+                    Write-Verbose -Message ($localizedData.DesiredAiasMissing -f $desiredAiaUrisMissing)
+                    $inDesiredState = $false
+                }
+
+                if ($notDesiredAiaUrisFound)
+                {
+                    Write-Verbose -Message ($localizedData.AdditionalAiasFound -f $notDesiredAiaUrisFound)
+                    $inDesiredState = $false
+                }
+            }
+            else
+            {
+                $aiaUriList = $AiaUri -join ', '
+
+                Write-Verbose -Message ($localizedData.AiasNull -f $aiaUriList)
+                $inDesiredState = $false
+            }
+        }
+
+        foreach ($uri in $currentState.AiaUri)
+        {
+            if ($uri -notin $AiaUri)
+            {
+                Write-Verbose -Message ($localizedData.IncorrectAiaUriFound -f $uri)
+                $inDesiredState = $false
+            }
+        }
+    }
+    else
+    {
+        foreach ($uri in $AiaUri)
+        {
+            if ($uri -in $currentState.AiaUri)
+            {
+                Write-Verbose -Message ($localizedData.EnsureAbsentButUrisExist -f $uri)
+                $inDesiredState = $false
+            }
+        }
+    }
+
+    return $inDesiredState
+}
+
+Export-ModuleMember -Function Get-TargetResource, Test-TargetResource, Set-TargetResource

DSCResources/MSFT_AdcsAiaExtension/MSFT_AdcsAiaExtension.schema.mof

@@ -0,0 +1,8 @@
+[ClassVersion("1.0.0"), FriendlyName("AdcsAiaExtension")]
+class MSFT_AdcsAiaExtension : OMI_BaseResource
+{
+    [Key, Description("Specifies the resource is a single instance, the value must be 'Yes'."), ValueMap{"Yes"}, Values{"Yes"}] String IsSingleInstance;
+    [Required, Description("Specifies the URI location where issuer of certificate is located.")] String AiaUri[];
+    [Write, Description("Specifies if the service should be restarted.")] Boolean RestartService;
+    [Write, Description("Ensures that the Authority Information Access (AIA) Uniform Resource Identifiers (URI) is Present or Absent."), ValueMap{"Present", "Absent"}, Values{"Present", "Absent"}] String Ensure;
+};

DSCResources/MSFT_AdcsAiaExtension/README.md

@@ -0,0 +1,6 @@
+# Description
+
+This resource can be used to configure the AIA URI extensions on the
+Certificate Authority after the feature has been installed on the server.
+Using this DSC Resource to configure an ADCS Certificate AIA assumes that
+the `ADCS-Cert-Authority` feature has already been installed.

DSCResources/MSFT_AdcsAiaExtension/en-US/MSFT_AdcsAiaExtension.strings.psd1

@@ -0,0 +1,11 @@
+ConvertFrom-StringData @'
+    AdditionalAiasFound          = Not in desired state, additional AIA URIs found, "{0}".
+    AddAiaUri                    = Adding "{0}" to desired AIA URIs.
+    DesiredAiasMissing           = Not in desired state, missing desired AIA URIs, "{0}".
+    EnsureAbsentButUrisExist     = Not in desired state, AIA URIs should be Absent, but found "{0}".
+    GetAiaUris                   = Getting all AIA URIs.
+    AiasNull                     = Not in desired state, AIA URIs empty, missing "{0}".
+    RemoveAiaUri                 = Removing "{0}" AIA URIs.
+    RestartService               = Preparing to restart the CertSvc for changes to take affect.
+    IncorrectAiaUriFound         = Not in desired state, AIA URI incorrect, found "{0}".
+'@

Examples/Resources/AdcsAiaExtension/1-AdcsAiaExtension_AddAia_Config.ps1

@@ -0,0 +1,43 @@
+<#PSScriptInfo
+.VERSION 1.0.0
+.GUID 93c71497-c4ac-452e-baf1-aff17bd4ecac
+.AUTHOR Microsoft Corporation
+.COMPANYNAME Microsoft Corporation
+.COPYRIGHT
+.TAGS DSCConfiguration
+.LICENSEURI https://github.com/PowerShell/ActiveDirectoryCSDsc/blob/master/LICENSE
+.PROJECTURI https://github.com/PowerShell/ActiveDirectoryCSDsc
+.ICONURI
+.EXTERNALMODULEDEPENDENCIES
+.REQUIREDSCRIPTS
+.EXTERNALSCRIPTDEPENDENCIES
+.RELEASENOTES First version.
+.PRIVATEDATA 2016-Datacenter,2016-Datacenter-Server-Core
+#>
+
+#Requires -module ActiveDirectoryCSDsc
+
+<#
+    .DESCRIPTION
+        A DSC configuration script to add desired AIA URI extensions for a Certificate Authority.
+        This will remove all existing AIA URIs from the Certificate Authority.
+#>
+configuration AdcsAiaExtension_AddAia_Config
+{
+    Import-DscResource -ModuleName ActiveDirectoryCSDsc
+
+    node localhost
+    {
+        AdcsAiaExtension AddAiaUri
+        {
+            IsSingleInstance = 'Yes'
+            AiaUri           = @(
+                'http://setAIATest1/Certs/<CATruncatedName>.cer'
+                'http://setAIATest2/Certs/<CATruncatedName>.cer'
+                'http://setAIATest3/Certs/<CATruncatedName>.cer'
+            )
+            RestartService   = $true
+            Ensure           = 'Present'
+        }
+    }
+}