From 3f1a6576a425200e152417af3de4917d3a9252a0 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 20 Aug 2024 13:32:12 +0100 Subject: [PATCH 1/3] Minor rewording --- docs/index.md | 2 +- docs/tutorial/index.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 73b2ada5a..bdf83f55e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -23,7 +23,7 @@ explanation/index ```{grid-item} ### [Tutorials](tutorial/index) -**Start here**: a hands-on introduction to ADSys for new users +**Learn about ADSys features** with hands-on tutorials ``` ```{grid-item} diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 68e61c6d4..6014815e3 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -1,6 +1,6 @@ # Tutorials -This section contains step-by-step tutorials to help you get started with ADSys. We hope our tutorials make as few assumptions as possible and are accessible to anyone with an interest in ADSys. They should be a great place to start learning about ADSys, how it works, and what it’s capable of. +This section contains step-by-step tutorials to help you get started with ADSys and learn about some its key features. ```{toctree} :hidden: @@ -11,4 +11,4 @@ certificates-autoenrolment Explore the essentials of Ubuntu's Certificate Auto-Enrolment Feature, a crucial tool for seamless certificate management with Active Directory Certificate Services. -* [Certificates auto-enrolment demo](certificates-autoenrolment.md) +* [Certificates auto-enrolment](certificates-autoenrolment.md) From 0b98b8faab374ee53aa09d0f181f34a039787b24 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 20 Aug 2024 13:32:29 +0100 Subject: [PATCH 2/3] Add text version of certificates tutorial --- docs/.custom_wordlist.txt | 3 + docs/tutorial/certificates-autoenrolment.md | 182 +++++++++++++++++++- 2 files changed, 184 insertions(+), 1 deletion(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 6220599f1..c8d3cc258 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -100,6 +100,7 @@ su sss sssd SSSD +SSTP subcommands subdirectory subprofile @@ -130,6 +131,8 @@ URIs usr unticking vendoring +VPN +VPNs Winbind wm xauth diff --git a/docs/tutorial/certificates-autoenrolment.md b/docs/tutorial/certificates-autoenrolment.md index 299482cc9..5fea686a8 100644 --- a/docs/tutorial/certificates-autoenrolment.md +++ b/docs/tutorial/certificates-autoenrolment.md @@ -1,5 +1,185 @@ # Certificates Auto-Enrolment -[Certificate Auto-Enrolment](/explanation/certificates.md) is a key component of Ubuntu's Active Directory GPO support. This feature enables clients to seamlessly enrol for certificates from Active Directory Certificate Services. In this demonstration, we'll guide you through the entire process, starting from the initial setup requirements to configuring the Active Directory policy. This demonstration is designed to provide you with a hands-on understanding of how to efficiently implement and manage certificate auto-enrolment, ensuring your systems remain secure and compliant with organisational policies. +Certificate Auto-Enrolment is a key component of Ubuntu’s Active Directory GPO support. +This feature enables clients to seamlessly enrol for certificates from Active Directory Certificate Services. + +This tutorial is designed to help you develop an understanding of how to efficiently implement and manage certificate auto-enrolment, ensuring your systems remain secure and compliant with organisational policies. + +A video version of the tutorial is also available: [![Demo video](https://img.youtube.com/vi/RwVU7v0sEVY/hqdefault.jpg)](https://www.youtube.com/embed/RwVU7v0sEVY) + +## What you need + +- A client machine running Ubuntu 23.04 LTS, Ubuntu 23.10 or Ubuntu 24.04 LTS +- A VPN server that runs in the Azure cloud +- An Ubuntu VM accessible in the VPN + +## What you will do + +- Configure and update the auto-enrolment policy +- Connect to a VPN server using certificates +- Access resources on the virtual network + +## Setup + +You will need an installation of ADSys on your client Ubuntu Machine and the client should be joined to an Active Directory (AD) domain. +Please refer to our how-to guides on setting up the Ubuntu client machine: + +- [Join machine to AD during installation](../how-to/join-ad-installation.md) +- [Join machine to AD manually](../how-to/join-ad-manually.md) +- [Install ADSys](../how-to/set-up-adsys.md) + +For the Windows Domain controller, refer to: + +- [Set up AD](../how-to/set-up-ad.md) + +## Configure the auto-enrolment policy + +First the policy needs to be configured. +This is done through the same entry policy as that which is used to configure Windows clients. + +You can find the entry `Certificate Services Client - Auto-Enrollment` in the GPO tree: + +`Policies > Windows Settings > Security Settings > Public Key Policies` + +Open the entry and set the Configuration Model to `Enabled`. +You should also toggle the option for updating certificates that use certificate templates. + +Apply these changes and continue. + +## Update policies and query certificates + +Now update the policies with ADSys: + +```text +sudo adsysctl update -m -v +``` + +```{note} +This command also typically runs on a fixed schedule and during system reboots. +``` + +ADSys downloads certificates from the domain controller. +You can query information about the certificates with: + +```text +sudo getcert list +``` + +```{note} +The `getcert list` command is provided by the `certmonger` utility, which is being used to manage the lifecycle of the certificates, ensuring — for example — that they are automatically renewed. +``` + +The output of the above command should look something like this: + +```text +Number of certificates and requests being tracked: 2 +Request ID 'galacticcafe-CA.Machine': + status: MONITORING + stuck: no + key pair storage: type=FILE,location='/var/lib/adsys/private/certs/galacticcafe-CA.Machine.key' + certificate: type=FILE,location='/var/lib/adsys/certs/galacticcafe-CA.Machine.crt' + CA: galacticcafe-CA + issuer: CN=galacticcafe-CA,DC=galacticcafe,DC=com +... +... +Request ID 'galacticcafe-CA.Workstation': + status: MONITORING + stuck: no + key pair storage: type=FILE,location='/var/lib/adsys/private/certs/galacticcafe-CA.Workstation.key' + certificate: type=FILE,location='/var/lib/adsys/certs/galacticcafe-CA.Workstation.crt' + CA: galacticcafe-CA + issuer: CN=galacticcafe-CA,DC=galacticcafe,DC=com +... +... +``` + +From this truncated output we can see that there are two certificates being monitored: + +- `galactic-CA.Machine` +- `galactic-CA.Workstation` + +These correspond to certificate templates that are configured on the certificate authority. + +The paths to the private key and certificate are included in the `getcert list` output. +Everything should now be in place for the use of corporate services like VPNs and WiFi. + +## Connect to VPN server using certificates + +To check the VPN configuration run: + +```text +cat /etc/ppp/peers/azure-vpn +``` + +Output: + + +```text +remotename: azure-vpn +linkname: azure-vpn +ipparamname: azure-vpn +... +... +name keypress.galacticcafe.com +plugin sstp-pppd-plugin.so +... +... +ca: /var/lib/adsys/certs/galacticcafe-CA.2.crt +cert: /var/lib/adsys/certs/galacticcafe-CA.Machine.crt +key: /var/lib/adsys/private/certs/galacticcafe-CA.Machine.crt +... +... +``` + +An SSTP VPN is being used for this tutorial, connecting to a gateway in the Azure cloud. +The name specified is the FQDN of the machine that the certificates are generated for. +Confirm that paths to the `ca`, `cert` and private `key` are all specified. + +It should then be possible to connect to the VPN: + +```text +sudo pon azure-vpn +``` + +Establishing the connection may take a few seconds. + +To check the connection run: + +```text +ip a +``` + +This should output a point-to-point connection: + +```text +... +... +8: ppp0: mtu 1500 pfifo_fast state unknown group default qlen 3 +... +... + +``` + +## Accessing resources on a virtual network + +The machine should now be connected to a virtual network with access to virtual resources. + +For example, if an Ubuntu machine has no public IP but is set up in the same virtual network then it should be accessible: + +```text +ping +``` + +It should be possible to `ssh` into a machine on the network: + +```text +ssh -i ~/.ssh/adsys-integration.pem root@ +``` + +For example, an instance of Ubuntu Mantic Minotaur (development branch) will give an output that shows it is running on Azure based on the kernel version: + +```text +Welcome to Ubuntu Mantic Minotaur (development branch) (GNU/Linux 6.5.0-1004-azure x86_64)) +``` From 1270c01359b4840b6b57e6d06e7cfe0c867ab834 Mon Sep 17 00:00:00 2001 From: shanecrowley Date: Tue, 20 Aug 2024 17:10:17 +0100 Subject: [PATCH 3/3] Update Ubuntu refs to latest LTS --- docs/tutorial/certificates-autoenrolment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorial/certificates-autoenrolment.md b/docs/tutorial/certificates-autoenrolment.md index 5fea686a8..f020e0d69 100644 --- a/docs/tutorial/certificates-autoenrolment.md +++ b/docs/tutorial/certificates-autoenrolment.md @@ -178,8 +178,8 @@ It should be possible to `ssh` into a machine on the network: ssh -i ~/.ssh/adsys-integration.pem root@ ``` -For example, an instance of Ubuntu Mantic Minotaur (development branch) will give an output that shows it is running on Azure based on the kernel version: +For example, an instance of Ubuntu 24.04 LTS will give an output that shows it is running on Azure based on the kernel version: ```text -Welcome to Ubuntu Mantic Minotaur (development branch) (GNU/Linux 6.5.0-1004-azure x86_64)) +Welcome to Ubuntu 24.04 LTS (GNU/Linux 6.5.0-1004-azure x86_64)) ```