|
1 | 1 | --- |
2 | 2 | myst: |
3 | 3 | html_meta: |
4 | | - description: "Configure certificate auto-enrollment for Ubuntu clients using Active Directory Certificate Services with certmonger and cepces integration." |
| 4 | + description: "Explanation of how certificate auto-enrollment is implemented and applied with ADSys." |
5 | 5 | --- |
6 | 6 |
|
7 | | -# Certificate auto-enrollment |
| 7 | +# Details of certificate auto-enrollment implementation |
8 | 8 |
|
9 | 9 | ```{include} ../pro_content_notice.txt |
10 | 10 | :start-after: <!-- Include start pro --> |
11 | 11 | :end-before: <!-- Include end pro --> |
12 | 12 | ``` |
13 | 13 |
|
14 | | -The certificate policy manager allows clients to enroll for certificates from **Active Directory Certificate Services**. Certificates are then continuously monitored and refreshed by the [`certmonger`](https://www.freeipa.org/page/Certmonger) daemon. Currently, only machine certificates are supported. |
15 | | - |
16 | | -Unlike the other ADSys policy managers which are configured in the special Ubuntu section provided by the ADMX files (Administrative Templates), settings for certificate auto-enrollment are configured in the Microsoft GPO tree: |
17 | | - |
18 | | -* `Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies > Certificate Services Client - Auto-Enrollment` |
19 | | - |
20 | | - |
21 | | - |
22 | | -## Required packages |
23 | | - |
24 | | -The following packages must be installed on the client in order for auto-enrollment to work: |
25 | | - |
26 | | -* [`certmonger`](https://www.freeipa.org/page/Certmonger) — daemon that monitors and updates certificates |
27 | | -* [`cepces`](https://github.com/openSUSE/cepces) — `certmonger` extension that can communicate with **Active Directory Certificate Services** |
28 | | - |
29 | | -On Ubuntu systems, run the following to install them: |
30 | | - |
31 | | -```bash |
32 | | -sudo apt install certmonger python3-cepces |
33 | | -``` |
34 | | - |
35 | | -On the Windows side, the following roles must be installed and configured: |
36 | | - |
37 | | -* `Certification Authority` |
38 | | -* `Certificate Enrollment Policy Web Service` |
39 | | -* `Certificate Enrollment Web Service` |
40 | | - |
41 | | -## Rules precedence |
42 | | - |
43 | | -Auto-enrollment configuration will override any settings referenced higher in the GPO hierarchy. |
44 | | - |
45 | | -## Policy configuration |
46 | | - |
47 | | -Certificate auto-enrollment is configured by setting the **Configuration Model** to **Enabled** and ticking the following checkbox: **Update certificates that use certificate templates**. |
48 | | - |
49 | | - |
50 | | - |
51 | | -The policy can be disabled by performing _any_ of the following: |
52 | | - |
53 | | -* unticking the **Update certificates that use certificate templates** checkbox |
54 | | -* setting the **Configuration Model** to **Disabled** or **Not configured** |
55 | | - |
56 | | -The other settings in this GPO entry do not affect ADSys in any way. |
57 | | - |
58 | | -For more advanced configuration, a list of policy servers can be specified in the following GPO entry: |
59 | | - |
60 | | -* `Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies > Certificate Services Client - Certificate Enrollment Policy` |
61 | | - |
62 | | - |
63 | | - |
64 | | -## Applying the policy |
65 | | - |
66 | | -On the client system, a successful auto-enrollment will place certificate data in the following paths: |
67 | | - |
68 | | -* `/var/lib/adsys/certs` - certificate data |
69 | | -* `/var/lib/adsys/private/certs` - private key data |
70 | | -* `/usr/local/share/ca-certificates` - root certificate data (symbolic link pointing to `/var/lib/adsys/certs`) |
71 | | - |
72 | | -For detailed information on the tracked certificates, `certmonger` can be directly interacted with: |
73 | | - |
74 | | -```output |
75 | | -# Query monitored certificates |
76 | | -> getcert list |
77 | | -Number of certificates and requests being tracked: 1. |
78 | | -Request ID 'galacticcafe-CA.Machine': |
79 | | - status: MONITORING |
80 | | - stuck: no |
81 | | - key pair storage: type=FILE,location='/var/lib/adsys/private/certs/galacticcafe-CA.Machine.key' |
82 | | - certificate: type=FILE,location='/var/lib/adsys/certs/galacticcafe-CA.Machine.crt' |
83 | | - CA: galacticcafe-CA |
84 | | - issuer: CN=galacticcafe-CA,DC=galacticcafe,DC=com |
85 | | - subject: CN=keypress.galacticcafe.com |
86 | | - issued: 2023-08-18 18:44:27 EEST |
87 | | - expires: 2024-08-17 18:44:27 EEST |
88 | | - dns: keypress.galacticcafe.com |
89 | | - key usage: digitalSignature,keyEncipherment |
90 | | - eku: id-kp-clientAuth,id-kp-serverAuth |
91 | | - certificate template/profile: Machine |
92 | | - profile: Machine |
93 | | - pre-save command: |
94 | | - post-save command: |
95 | | - track: yes |
96 | | - auto-renew: yes |
97 | | -
|
98 | | -# Query known CAs |
99 | | -> getcert list-cas |
100 | | -(...) |
101 | | -CA 'galacticcafe-CA': |
102 | | - is-default: no |
103 | | - ca-type: EXTERNAL |
104 | | - helper-location: /usr/libexec/certmonger/cepces-submit --server=win-mk85nrq26nu.galacticcafe.com --auth=Kerberos |
105 | | -``` |
106 | | - |
107 | 14 | ## Policy implementation |
108 | 15 |
|
109 | | -With the exception of policy parsing, ADSys leverages the Samba implementation of certificate auto-enrollment. As this feature is only available in newer versions of Samba, we have taken the liberty of vendoring the required Samba files to allow this policy to work on Ubuntu versions that ship an older Samba version. These files are shipped in `/usr/share/adsys/python/vendor_samba`. |
| 16 | +With the exception of policy parsing, ADSys leverages the Samba implementation of certificate auto-enrollment. As this feature is only available in newer versions of Samba, we have vendored the required Samba files to allow this policy to work on Ubuntu versions that ship an older Samba version. These files are shipped in `/usr/share/adsys/python/vendor_samba`. |
110 | 17 |
|
111 | | -To ensure idempotency when applying the policy, we set up a Samba [TDB cache file](https://wiki.samba.org/index.php/TDB) at `/var/lib/adsys/samba/cert_gpo_state_$(hostname).tdb` which contains various information pertaining to the enrolled certificate(s). |
| 18 | +To ensure idempotency when applying the policy, we set up a Samba [TDB cache file](https://wiki.samba.org/index.php/TDB) at `/var/lib/adsys/samba/cert_gpo_state_$(hostname).tdb` which contains information pertaining to the enrolled certificate(s). |
112 | 19 |
|
113 | | -Here is an overview of what happens during policy application: |
114 | | - |
115 | | -* GPO parsing (ADSys) |
116 | | -* execute Python helper script (ADSys) |
117 | | -* fetch root CA and policy servers (Samba) |
118 | | -* start monitoring certificate using `certmonger` and `cepces` (Samba) |
119 | | - |
120 | | -## Troubleshooting |
121 | | - |
122 | | -### Some dependencies are not available in the client Ubuntu installation |
123 | | - |
124 | | -While `certmonger` has been available for a while in Ubuntu, `python3-cepces` is a new package, available starting with Ubuntu 23.10. If unavailable on the client version, it can also be manually installed from the [source repository](https://github.com/openSUSE/cepces). The certificate policy manager only checks for the existence of the `cepces-submit` and `getcert` binaries, not their respective packages, in order to allow some wiggle room for this. |
125 | | - |
126 | | -### Manipulating certificates with `getcert` |
127 | | - |
128 | | -While not encouraged, certificates can be manipulated with the same tool. This could be helpful for debugging purposes. |
129 | | - |
130 | | -```output |
131 | | -# Regenerate a certificate |
132 | | -> getcert rekey -i galacticcafe-CA.Machine |
133 | | -Resubmitting "galacticcafe-CA.Machine" to "galacticcafe-CA". |
| 20 | +### Policy application sequence |
134 | 21 |
|
135 | | -# Unmonitor a certificate |
136 | | -> getcert stop-tracking -i galacticcafe-CA.Machine |
137 | | -Request "galacticcafe-CA.Machine" removed. |
138 | | -
|
139 | | -# Remove CA |
140 | | -> getcert remove-ca -c galacticcafe-CA |
141 | | -CA "galacticcafe-CA" removed. |
142 | | -``` |
143 | | - |
144 | | -Note that tampering with certificate data outside of ADSys (e.g. manually unmonitoring using `getcert`) will render the GPO cache obsolete as it will cause a drift between the actual state and the "known" cached state. In this case, it's best to remove the cache file at `/var/lib/adsys/samba/*.tdb` together with any enrolled certificates and CAs to ensure a clean slate. |
145 | | - |
146 | | -### Debugging `auto-enroll` script |
147 | | - |
148 | | -While certificate parsing happens in ADSys itself, enrollment is done via an embedded Python helper script. For debugging purposes, it can be dumped to the current directory and made executable by executing the following commands: |
149 | | - |
150 | | -```output |
151 | | -> adsysctl policy debug cert-autoenroll-script |
152 | | -> chmod +x ./cert-autoenroll |
153 | | -``` |
154 | | - |
155 | | -Before executing the script manually, the following environment variables have to be set: |
156 | | - |
157 | | -```sh |
158 | | -export PYTHONPATH=/usr/share/adsys/python |
159 | | -export KRB5CCNAME=/var/run/adsys/krb5cc/$(hostname) |
160 | | -``` |
161 | | - |
162 | | -Then, run the script passing the required arguments (the argument list is also printed in the ADSys debug logs during policy application): |
163 | | - |
164 | | -```output |
165 | | -# Un-enroll machine |
166 | | -> ./cert-autoenroll unenroll keypress galacticcafe.com --state_dir /var/lib/adsys --debug |
167 | | -``` |
168 | | - |
169 | | -### Errors communicating with the CEP/CES servers |
170 | | - |
171 | | -If ADSys successfully applies the policy but `getcert list` does not list the certificates or they are in an unexpected state, check the `certmonger` logs for details (`journalctl -u certmonger`). Additionally, debug logging for `cepces` can be enabled by editing the logging configuration at `/etc/cepces/logging.conf`. |
172 | | - |
173 | | -The `cepces` configuration itself is batteries-included, meaning it should work out of the box for most setups. All configuration options are documented and configurable at `/etc/cepces/cepces.conf`. |
174 | | - |
175 | | -## Additional information |
176 | | - |
177 | | -While configuring Active Directory Certificate Services is outside the scope of the policy manager documentation, we have found the following resources to be useful: |
178 | | - |
179 | | -* [How to setup Microsoft Active Directory Certificate Services](https://www.virtuallyboring.com/setup-microsoft-active-directory-certificate-services-ad-cs/) |
180 | | -* [How to increase your CSR key size on Microsoft IIS without removing the production certificate?](https://leonelson.com/2011/08/15/how-to-increase-your-csr-key-size-on-microsoft-iis-without-removing-the-production-certificate/) |
181 | | - |
182 | | -## Acknowledgements |
| 22 | +Here is an overview of what happens during policy application: |
183 | 23 |
|
184 | | -We would like to thank the Samba team for making great strides in the research and implementation of certificate auto-enrollment via Active Directory Certificate Services. |
| 24 | +* Parse GPO (ADSys) |
| 25 | +* Execute Python helper script (ADSys) |
| 26 | +* Fetch root CA and policy servers (Samba) |
| 27 | +* Start monitoring certificate using `certmonger` and `cepces` (Samba) |
0 commit comments