Skip to content

Commit

Permalink
Improve ADCS integration guide (#130)
Browse files Browse the repository at this point in the history
  • Loading branch information
@3keyroman
3keyroman authored Feb 2, 2024
1 parent 5e9ac8e commit cb85b4a
Show file tree
Hide file tree
Showing 11 changed files with 583 additions and 101 deletions.
56 changes: 56 additions & 0 deletions docs/10-certificate-key/20-integration-guides/14-adcs/01-overview.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Overview

This document outlines the steps necessary to be taken on the Windows Server before the integration with ADCS can be configured.

This integration guide was tested on:
- Windows Server 2012 R2
- Windows Server 2016
- Windows Server 2019

## Active Directory presence

Depending on your environment, install the Active Directory Server Role according to the instructions from Microsoft and promote the Domain. Omit the step if you already have an onsite Active Directory structure. Make sure, the machine you are connecting is a member of the AD Domain.

:::info[How to install AD]
You can use as example the following guide:
[Install a New Windows Server 2012 Active Directory Forest (Level 200) | Microsoft Docs](https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/deploy/install-a-new-windows-server-2012-active-directory-forest--level-200-)
:::

## Active Directory Certificate Services presence

Depending on your environment, install the Active Directory Certificate Services Server Role according to the instructions from Microsoft. Omit the step if you already have Microsoft Certification Authority Running.

:::info[How to install ADCS]
You can use as example the following guide:
[Install Active Directory Certificate Services | Microsoft Docs](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-r2-and-2012/jj717285(v=ws.11))
:::

## PowerShell remoting

PowerShell remoting is used to facilitate client-less integration with ADCS. PowerShell remoting is enabled by default on Windows Server platforms. You can use [`Enable-PSRemoting`](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/enable-psremoting?view=powershell-7.4) to enable PowerShell remoting on other supported versions of Windows and to re-enable remoting if it becomes disabled.

You have to run this command only one time on each computer that will receive commands.

PowerShell remoting can be facilitated using the following protocols:

| Protocol | Description |
|-----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [WinRM](https://learn.microsoft.com/en-us/windows/win32/winrm/portal) | Windows Remote Management (WinRM) is the Microsoft implementation of the WS-Management protocol, which is a standard Simple Object Access Protocol (SOAP)-based, firewall-friendly protocol that allows interoperation between hardware and operating systems from different vendors. |
| [SSH](https://learn.microsoft.com/en-us/powershell/scripting/learn/remoting/ssh-remoting-in-powershell?view=powershell-7.4) | SSH remoting lets you do basic PowerShell session remoting between Windows and Linux computers. SSH remoting creates a PowerShell host process on the target computer as an SSH subsystem. SSH-based remoting doesn't currently support remote endpoint configuration and Just Enough Administration (JEA). |

## Integration

The following steps should be done to successfully integrate ADCS with CZERTAINLY:

| # | Reference | Short description |
|-------|----------------------------------------------------|----------------------------------------------|
| **1** | [Install PSPKI Module](./install-pspki) | Prepare PowerShell PKI Module |
| **2** | [WinRM Configuration](./winrm-configuration) | Configure Windows Remote Management protocol |
| **3** | [SSH Configuration](./ssh-configuration) | Configure Secure Shell protocol |
| **4** | [Firewall Configuration](./firewall-configuration) | Configure inbound connections and delegation |
| **5** | [Create User](./create-user) | Create user to access ADCS |
| **6** | [Testing Integraton](./test-integration) | Test integration and access to ADCS |

## Troubleshooting

For common issues and troubleshooting, refer to [Troubleshooting](./troubleshooting).
69 changes: 69 additions & 0 deletions docs/10-certificate-key/20-integration-guides/14-adcs/03-install-pspki.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Install PSPKI Module

The [**PSPKI module for PowerShell**](https://github.com/PKISolutions/PSPKI) is intended to simplify various PKI and Active Directory Certificate Services management tasks by using automation with Windows PowerShell. The module provides features and capabilities for managing and configuring Certification Authorities.

Although it is an optional component, majority of providers and connectors are using it to provide better user experience and more features.

To install the PSPKI module, first make sure you are using the newest version of PowerShell from Microsoft. At least version 5 is required.

:::info[PSPKI module requirements]
The PSPKI module requires Windows PowerShell 3.0 or higher and .NET Framework 4.7.2 or higher. Check the [official project page](https://github.com/PKISolutions/PSPKI) for more information.
:::

## Installation steps

- Enable TLSv1.2 Protocol for PowerShell by running the following in an elevated PowerShell console on the server:
```powershell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
```

- Register a PSRepository for installation of modules to PowerShell by running the following in an elevated PowerShell console on the server:
```powershell
Register-PSRepository -Default
```

- Finally, install the PSPKI module by running the following in an elevated PowerShell console on the server:
```powershell
Install-Module -Name PSPKI
```

## Test PSPKI module installation

To test the PSPKI module, run the following in PowerShell console on the server:
```powershell
Get-Command -Module PSPKI
```

The output should look similar to this:
```powershell
CommandType Name Version Source
----------- ---- ------- ------
Alias Add-AIA 3.7.2 PSPKI
Alias Add-CAAccessControlEntry 3.7.2 PSPKI
Alias Add-CAACL 3.7.2 PSPKI
Alias Add-CDP 3.7.2 PSPKI
Alias Add-OCSPACL 3.7.2 PSPKI
Alias Connect-CA 3.7.2 PSPKI
Alias Disable-CRLFlag 3.7.2 PSPKI
Alias Disable-KRAFlag 3.7.2 PSPKI
Alias Enable-CRLFlag 3.7.2 PSPKI
Alias Enable-KRAFlag 3.7.2 PSPKI
Alias Get-AIA 3.7.2 PSPKI
Alias Get-CA 3.7.2 PSPKI
Alias Get-CAACL 3.7.2 PSPKI
Alias Get-CASecurityDescriptor 3.7.2 PSPKI
Alias Get-CDP 3.7.2 PSPKI
Alias Get-CRL 3.7.2 PSPKI
Alias Get-CRLFlag 3.7.2 PSPKI
Alias Get-Csp 3.7.2 PSPKI
Alias Get-CTL 3.7.2 PSPKI
...
```

:::tip[Using PSPKI module]
Using PSPKI module commands requires to import the module first. To import the module, run the following in PowerShell console on the server:
```powershell
Import-Module PSPKI
```
:::
200 changes: 200 additions & 0 deletions docs/10-certificate-key/20-integration-guides/14-adcs/05-winrm-configuration.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
# WinRM Configuration

WinRM is a Microsoft implementation of the WS-Management Protocol, which is a standard Simple Object Access Protocol (SOAP)-based, firewall-friendly protocol that allows interoperation between hardware and operating systems from different vendors.

It is used to facilitate client-less integration with Microsoft ADCS.

## WinRM authentication

Windows Remote Management maintains security for communication between computers by supporting several standard methods of authentication and message encryption.

The following table lists the [authentication methods](https://learn.microsoft.com/en-gb/windows/win32/winrm/authentication-for-remote-connections) that are supported by WinRM:

| Authentication Method | Local Accounts | Active Directory Accounts | Credential Delegation | HTTP Encryption |
|-----------------------|-----------------------------------------------|-----------------------------------------------|-----------------------------------------------|-----------------------------------------------|
| Basic | <span class="badge badge--success">Yes</span> | <span class="badge badge--danger">No</span> | <span class="badge badge--danger">No</span> | <span class="badge badge--danger">No</span> |
| NTLM | <span class="badge badge--success">Yes</span> | <span class="badge badge--success">Yes</span> | <span class="badge badge--danger">No</span> | <span class="badge badge--danger">No</span> |
| Kerberos | <span class="badge badge--danger">No</span> | <span class="badge badge--success">Yes</span> | <span class="badge badge--success">Yes</span> | <span class="badge badge--success">Yes</span> |
| CredSSP | <span class="badge badge--success">Yes</span> | <span class="badge badge--success">Yes</span> | <span class="badge badge--success">Yes</span> | <span class="badge badge--success">Yes</span> |
| Certificate | <span class="badge badge--success">Yes</span> | <span class="badge badge--danger">No</span> | <span class="badge badge--danger">No</span> | <span class="badge badge--danger">No</span> |

:::warning[Access delegation]
Enterprise ADCS is using multiple stores for its configuration, therefore for successful integration it is usually needed to have access to the ADCS service and Active Directory containers on Domain Controllers that host for instance the AD Certificate Templates. For security reasons, Windows Remote Management allows access delegation only for Kerberos and CredSSP authentication mechanisms.
:::

## WinRM encryption

By default, WinRM will fail to work when running over an unencrypted channel. Using WinRM with TLS is the recommended option as it works with all authentication options, but requires a certificate to be created and used on the WinRM listener.

The certificate can be created using the `New-SelfSignedCertificate` cmdlet, or by using the `certreq` command to create a certificate request and then submitting it to a Certificate Authority (CA). If in a domain environment, ADCS can create a certificate for the host that is issued by the domain itself.

If using HTTPS is not an option, then WinRM can be used with encrypted payload when the authentication option is `NTLM`, `Kerberos` or `CredSSP`. The message-level encryption is not used when running over HTTPS because the encryption uses the more secure TLS protocol instead.

## WinRM configuration

To configure Windows Remote Management (WinRM), run the following command from an elevated PowerShell console:
```powershell
winrm quickconfig
```

Check that the WinRM Service is listening on port `5985` by running the following command from an elevated PowerShell console:
```powershell
winrm e winrm/config/listener
Listener
Address = *
Transport = HTTP
Port = 5985
Hostname
Enabled = true
URLPrefix = wsman
CertificateThumbprint
ListeningOn = ..., ::1
Listener
Address = *
Transport = HTTPS
Port = 5986
Hostname = test.example.com
Enabled = true
URLPrefix = wsman
CertificateThumbprint = 4feb511be2cdb7ef1a58fdd4be0a56e2e17450a3
ListeningOn = ..., ::1
```

Validate the default configuration of WinRM service by running the following command from the elevated PowerShell console:
```powershell
winrm get winrm/config
Config
MaxEnvelopeSizekb = 500
MaxTimeoutms = 60000
MaxBatchItems = 32000
MaxProviderRequests = 4294967295
Client
NetworkDelayms = 5000
URLPrefix = wsman
AllowUnencrypted = true
Auth
Basic = true
Digest = true
Kerberos = true
Negotiate = true
Certificate = true
CredSSP = false
DefaultPorts
HTTP = 5985
HTTPS = 5986
TrustedHosts
Service
RootSDDL = O:NSG:BAD:P(A;;GXGR;;;S-1-5-21-3820024857-2695711099-450958038-1618)(A;;GA;;;DA)(A;;GA;;;BA)(A;;GAGR;;;RM)(A;;GR;;;IU)S:P(AU;FA;GA;;;WD)(AU;SA;GXGW;;;WD)
MaxConcurrentOperations = 4294967295
MaxConcurrentOperationsPerUser = 1500
EnumerationTimeoutms = 240000
MaxConnections = 300
MaxPacketRetrievalTimeSeconds = 120
AllowUnencrypted = true
Auth
Basic = true
Kerberos = true
Negotiate = true
Certificate = false
CredSSP = true
CbtHardeningLevel = Relaxed
DefaultPorts
HTTP = 5985
HTTPS = 5986
IPv4Filter = *
IPv6Filter = *
EnableCompatibilityHttpListener = false
EnableCompatibilityHttpsListener = false
CertificateThumbprint = 4feb511be2cdb7ef1a58fdd4be0a56e2e17450a3
AllowRemoteAccess = true
Winrs
AllowRemoteShellAccess = true
IdleTimeout = 7200000
MaxConcurrentUsers = 2147483647
MaxShellRunTime = 2147483647
MaxProcessesPerShell = 2147483647
MaxMemoryPerShellMB = 2147483647
MaxShellsPerUser = 2147483647
```

Under the service configuration, negotiation authentication needs to be enabled. Check the output of the previous command to verify that `Negotiate = true`.

## CredSSP configuration

Enable CredSSP authentication on the server (that CZERTAINLY is going to connect to) by running the following command:

```powershell
Enable-WSManCredSSP -Role Server
```

Validate the default configuration of WinRM service by running the following command from the elevated PowerShell console:

```powershell
winrm get winrm/config
```

Check the output of the previous command to verify that under WinRM service (not client) `CredSSP = true`.

By default, the WinRM service will create a self-signed certificate that is used for CredSSP security (message encryption and signing). **However, if Server Authentication certificate is present in Computer Certification store, it will try to use it instead.**

Check the certificate thumbprint by running the following command:

```powershell
winrm get winrm/config/service
```

In case a certificate was selected from the computer store you will see the Certificate Thumbprint in the WinRM service configuration `CertificateThumbprint`.

The account that is running Windows Remote Management service (Network Service by default) must have access to the private key of the certificate.
This is configured on the server. Locate the certificate with the thumbprint configured under `winrm service` (previous step), and configure account to have at least `Read` access for the private key. (select All Tasks and Manage Private Keys in the Manager).

### Delegate credentials

Enabling CredSSP account delegation on a Windows client involves configuring Group Policy or Registry Items settings.

Using Group Policy Editor, navigate to Computer Configuration, Administrative Templates, System and Credentials Delegation. Enable Allow delegating fresh credentials and allow delegating fresh credentials with NTLM-only server authentication. In the options add your servers to the list or use an asterisk (*) to allow for all connections.

You can use PowerShell to automate these changes:

```powershell
New-Item `
-Path HKLM:\SOFTWARE\Policies\Microsoft\Windows\CredentialsDelegation `
-Name AllowFreshCredentialsWhenNTLMOnly `
-Force
New-ItemProperty `
-Path HKLM:\SOFTWARE\Policies\Microsoft\Windows\CredentialsDelegation\AllowFreshCredentialsWhenNTLMOnly `
-Name 1 `
-Value * `
-PropertyType String
New-Item `
-Path HKLM:\SOFTWARE\Policies\Microsoft\Windows\CredentialsDelegation `
-Name AllowFreshCredentials `
-Force
New-ItemProperty `
-Path HKLM:\SOFTWARE\Policies\Microsoft\Windows\CredentialsDelegation\AllowFreshCredentials `
-Name 1 `
-Value * `
-PropertyType String
# Update Group Policy settings to apply changes
gpupdate /force
```

Make sure to replace "Server1", "Server2" with the actual names of your servers.

:::warning
Modifying the registry and Group Policy settings should be done with caution. Ensure that you have the necessary permissions to make these changes. Also, running these commands may require elevated privileges (Run PowerShell as Administrator). Additionally, changes to Group Policy may not take effect immediately, and you might need to log out or restart your computer for the settings to apply.
:::

## Limitations

There are some limitations to the WinRM integration to manage ADCS:

- Credentials are delegated for only `Kerberos` and `CredSSP` authentication method.
- Commands under WinRM are done under a non-interactive session, which can prevent certain commands or executables from running to manage ADCS.
Loading

0 comments on commit cb85b4a

Please sign in to comment.