bunny-lab/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation Restructure
All checks were successful
GitOps Automatic Documentation Deployment / Sync Docs to https://kb.bunny-lab.io (push) Successful in 4s
Details
GitOps Automatic Documentation Deployment / Sync Docs to https://docs.bunny-lab.io (push) Successful in 6s
Details

Browse Source
This commit is contained in:
Nicole Rappe
2026-01-27 05:25:22 -07:00
parent 3ea11e04ff
commit e73bb0376f
205 changed files with 469 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
services/authentication/active-directory/certificate-services.md Normal file
View File

@@ -0,0 +1,227 @@
## Purpose
This document outlines the Microsoft-recommended best practices for deploying a secure, internal-use-only, two-tier Public Key Infrastructure (PKI) using Windows Server 2022 or newer. The PKI supports securing S/MIME email, 802.1X Wi-Fi with NPS, and LDAP over SSL (LDAPS).
!!! abstract "CA Deployment Breakdown"
The environment will consist of at least 2 virtual machines. For the purposes of this document they will be named `LAB-CA-01` and `LAB-CA-02`. This stands for "*Lab Certificate Authority [01|02]*". In a two-tier hierarchy, an offline (*you intentionally keep this VM offline*) Root CA signs a single "*Subordinate*" Enterprise CA certificate. The Subordinate CA is domain-joined and handles all certificate requests. Clients trust the PKI via Group Policy and Active Directory integration.
In this case, `LAB-CA-01` is the Root CA, while `LAB-CA-02` is the Intermediary/Subordinate CA. You can add more than one subordinate CA if you desire more redundancy in your environment. Making them operate together is generally automatic and does not require manual intervention.
!!! note "Certificate Authority Server Provisioning Assumptions"
- OS = Windows Server 2022/2025 bare-metal or as a VM
- You should give it at least 4GB of RAM.
- [Change the edition of Windows Server from "**Evaluation**" to "**Standard**" via DISM](../../../operations/windows/change-windows-edition.md)
- Ensure the server is fully updated
- [Ensure the server is activated](../../../operations/windows/change-windows-edition.md#force-activation-edition-switcher)
- Ensure the timezone is correctly configured
- Ensure the hostname is correctly configured
!!! note "Domain Environment Assumptions"
It is assumed that you already have existing infrastructure hosting an Active Directory Domain with at least one domain controller. This document does not outline how to set up a domain controller, you will need to figure that out on your own.
## Offline (Non-Domain-Joined) Root CA `LAB-CA-01`
### Role Deployment
This is the initial deployment of the root certificate authority, the settings here should be double and triple checked before proceeding through each step.
- Provision a **non-domain-joined** Windows Server
- This is critical that this device is not domain-joined for security purposes
- Navigate to "**Server Manager > Manage > Add Roles and Features**"
- Check "**Active Directory Certificate Services**"
- When prompted to confirm, click the "**Add Features**" button
- Ensure the "**Include management tools (if applicable)**" checkbox is checked.
- Click "**Next**" > "**Next**" > "**Next**"
- You will be told that the name of the server cannot be changed after this point, and it will be associated with `WORKGROUP` > This is fine and you can proceed.
- Check the boxes for the following role services:
- `Certification Authority`
- `Certification Authority Web Enrollment`
- When prompted to confirm multiple times, click the "**Add Features**" button
- Ensure the "**Include management tools (if applicable)**" checkbox is checked.
- There are additional steps such as `Configure AIA and CDP extensions with HTTP paths` and `Publish root cert and CRL to AD and internal HTTP`, but these do not apply to an LDAPS-only deployment, and are more meant for websites / webhosting. (current understanding)
- Click "**Next**" > "**Next**" > "**Next**" > "**Install**"
- Restart the Server
### Role Configuration
We have a few things we need to configure within the CA to make it ready to handle certificate requests.
- Navigate to "**Server Manager > (Alert Flag) > Post-deployment Configuration: Active Directory Certificate Services**"
- You will be prompted for an admin user, in this example, you will use the pre-populated `LAB-CA-01\Administrator`
- Check the boxes for `Certification Authority` and `Certification Authority Web Enrollment` then click "**Next**"
- Check the "**Standalone CA**" radio box then click "**Next**"
- Check the "**Root CA** radio box then click "**Next**"
- Check the "**Create a new private key**" radio box then click "**Next**"
- Click the dropdown menu for "**Select a crypotographic provider**" and ensure that "**RSA#Microsoft Software Key Storage Provider**" is selected
- *Microsoft Software Key Storage Provider (KSP) is the latest, most flexible provider designed to work with the Cryptography Next Generation (CNG) APIs. It offers better support for modern algorithms and improved security management (such as support for key attestation, better hardware integration, and improved key protection mechanisms).*
- Set the key length to `4096`
- Set the hash algorithm to `SHA256`
- Click "**Next**"
- **Common Name for this CA**: `BunnyLab-RootCA`
- **Distinguished name suffix**: `O=Bunny Lab,C=US`
- **Preview of distinguished name**: `CN=BunnyLab-RootCA,O=Bunny Lab,C=US`
- Click "**Next**"
- Specify the validity period: `10 Years` then click "**Next**" > "**Next**" > "**Configure**"
You will see a finalization screen confirming everything we have configured, it should look something like what is seen below:
| **Field** | **Value** |
| :--- | :--- |
| CA Type | Standalone Root |
| Cryptographic provider | RSA#Microsoft Software Key Storage Provider |
| Hash Algorithm | SHA256 |
| Key Length | 4096 |
| Allow Administrator Interaction | Disabled |
| Certificate Validity Period | `<10 Years from Today>` |
| Distinguished Name | CN=BunnyLab-RootCA,O=Bunny Lab,C=US |
| Certificate Database Location | C:\Windows\system32\CertLog |
| Certificate Database Log Location | C:\Windows\system32\CertLog |
!!! success "Active Directory Certificate Services"
If everything went well, you will see that the "**Certificate Authority**" and "**Certification Authority Web Enrollment**" both have a status of "**Configuration succeeded**". At this point, you can click the "**Close**" button to conclude the Root CA configuration.
## Online (Domain-Joined) Subordinate/Intermediary CA `LAB-CA-02`
### Role Deployment
Now that we have set up the root certificate authority, we can focus on setting up the subordinate CA.
!!! warning "Enterprise Admin Requirement"
When you are setting up the role, you **absolutely** have to use an "*Enterprise*" Admin account. This could be a service account like `svcCertAdmin` or something similar.
- Navigate to "**Server Manager > (Alert Flag) > Post-deployment Configuration: Active Directory Certificate Services**"
- Under credentials, enter the username for an Enterprise Admin. (e.g. `BUNNY-LAB\nicole.rappe`)
- Click "**Next**"
- Check the following roles (*we will add the rest after setting up the core CA functionality*)
- `Certification Authority`
- `Certification Authority Web Enrollment`
- Check the "**Enterprise CA**" radio box then click "**Next**"
- Check the "**Subordinate CA**" radio box then click "**Next**"
- Check the "**Create a new private key**" radio box then click "**Next**"
- Click the dropdown menu for "**Select a crypotographic provider**" and ensure that "**RSA#Microsoft Software Key Storage Provider**" is selected
- *Microsoft Software Key Storage Provider (KSP) is the latest, most flexible provider designed to work with the Cryptography Next Generation (CNG) APIs. It offers better support for modern algorithms and improved security management (such as support for key attestation, better hardware integration, and improved key protection mechanisms).*
- Set the key length to `4096`
- Set the hash algorithm to `SHA256`
- Click "**Next**"
- **Common Name for this CA**: `BunnyLab-SubordinateCA-01`
- **Distinguished name suffix**: `DC=bunny-lab,DC=io`
- This will be auto-filled based on the domain that the CA is joined to
- **Preview of distinguished name**: `CN=BunnyLab-SubordinateCA-01,DC=bunny-lab,DC=io`
- Click "**Next**"
- Select the "**Save a certificate request to file on the target machine**" radio button
- This will auto-populate the destination to something like "`C:\LAB-CA-02.bunny-lab.io_bunny-lab-LAB-CA-02-CA.req`"
- Click "**Next**" > "**Next**" > "**Configure**"
You will see a finalization screen confirming everything we have configured, it should look something like what is seen below:
| **Field** | **Value** |
| :--- | :--- |
| CA Type | Enterprise Subordinate |
| Cryptographic provider | RSA#Microsoft Software Key Storage Provider |
| Hash Algorithm | SHA256 |
| Key Length | 4096 |
| Allow Administrator Interaction | Disabled |
| Certificate Validity Period | Determined by the parent CA |
| Distinguished Name | CN=BunnyLab-SubordinateCA-01,DC=bunny-lab,DC=io |
| Offline Request File Location | `C:\LAB-CA-02.bunny-lab.io_bunny-lab-LAB-CA-02-CA.req` |
| Certificate Database Location | C:\Windows\system32\CertLog |
| Certificate Database Log Location | C:\Windows\system32\CertLog |
!!! quote "Pending Certificate Signing Request"
You will see a screen telling you that the **Certification Authority Web Enrollment** was successful but it will give a warning about the **Certification Authority**. The Active Directory Certificate Services installation is incomplete. To complete the installation, use the request file <file-name> to obtain a certificate from the parent CA [*The RootCA*]. Then, use the Certification Authority snap-in to install the certificate. To complete this procedure, right-click the node with the name of the CA, and then click "Install CA Certificate".
### Role Configuration
At this point, we will need to focus on getting the certificate signing request generated on `LAB-CA-02` to `LAB-CA-01` (the rootCA), this can be via temporary network access or via a USB flashdrive.
!!! danger
If using a USB flashdrive is not viable, don't leave the RootCA server on the network any longer than what is absolutely necessary.
- Once the certificate signing request file `C:\LAB-CA-02.bunny-lab.io_bunny-lab-LAB-CA-02-CA.req` is on `LAB-CA-01` (RootCA) we can proceed to get it signed.
- Navigate to "**Server Manager > Tools > Certification Authority**"
- Right-click the CA node in the treeview on the left-hand sidebar (e.g. `BunnyLab-RootCA`)
- Click on "**All Tasks" > "Submit new request...**"
- Browse to and select the subordinate CA’s .req file (e.g. `LAB-CA-02.bunny-lab.io_bunny-lab-LAB-CA-02-CA.req`)
- Click on "**BunnyLab-RootCA > Pending Requests**
- Right-click the request we just imported, and select "**All Tasks > Issue**"
- Click on ""**BunnyLab-RootCA > Issued Certificates**"
- Locate the new subordinate CA certificate, and double-click it.
- Click the "**Details**" tab
- Click the "**Copy to File**" button
- Click "**Next**"
- Choose `DER encoded binary X.509 (.CER)` and save as `LAB-CA-02-SubCA.cer`.
- Export the Root CA certificate:
- Right-click the `BunnyLab-RootCA` node > Properties > View Certificate > Details > Copy to File...
- Save as `RootCA.cer`
- Copy both `LAB-CA-02-SubCA.cer` (the signed subordinate CA cert) and `RootCA.cer` (the root CA cert) to the subordinate CA (`LAB-CA-02`), using a secure method (e.g. USB drive).
- On `LAB-CA-02` (Subordinate CA), Navigate to "**Server Manager > Tools > Certification Authority**"
- Right-click the CA node in the treeview on the left-hand sidebar (e.g. `BunnyLab-SubordinateCA-01`)
- Click on "**All Tasks" > "Install CA Certificate**"
- Browse to and select `LAB-CA-02-SubCA.cer` (*you may need to change the cert file extension filter to `X.509 Certificate`*)
- When prompted for the CA chain or root certificate, browse for and select the `RootCA.cer` you transferred earlier along with the `LAB-CA-02-SubCA.cer`
- Launch `certlm.msc` to open the `[Certificates - Local Computer]` management window
- Right-Click "**Trusted Root Certification Authorities**" > All Tasks > Import
- Click "**Next**"
- Browse to the `BunnyLab-RootCA.crl` located on `\\LAB-CA-01\CertEnroll\BunnyLab-RootCA.crl` (*if the RootCA is temporarily on the network*) or copy the file manually via USB drive from `C:\Windows\System32\certsrv\CertEnroll\BunnyLab-RootCA.crl`
- Place all certificates in the following store: "Trusted Root Certification Authorities"
- Click "**Next**" and finish importing the Certificate Revocation List
- Right-click the CA node in the treeview on the left-hand sidebar (e.g. `BunnyLab-SubordinateCA-01`)
- Click on "**All Tasks" > "Start Service**"
- Verify that the CA status is now green (running).
## Create Auto-Enrollment Group Policy
The Certificate Auto-Enrollment Group Policy enables domain-joined devices (*computers, including domain controllers*) to automatically request, renew, and install certificates from the Enterprise CA (in this case, the Subordinate CA `LAB-CA-02`).
### Create GPO
- Open the Group Policy Management editor on one of your domain controllers, then "Create a GPO in this domain, and link it here" wherever it will be able to target the domain controllers, this may be at the root, or in a specific OU that holds domain controllers. (e.g. `bunny-lab.io\Domain Controllers` )
- Name the new GPO something like "**Certificate Auto-Enrollment**"
- Edit the GPO
- Navigate to "**Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies**"
- Find and open "**Certificate Services Client - Auto-Enrollment.**"
- Set the Configuration Model to "**Enabled**"
- Check both checkboxes for "**Renew expired certificates, update pending certificates, and remove revoked certificates**" and "**Update certificates that use certificate templates**"
- Click "**OK**"
- Navigate to "**Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies > Trusted Root Certification Authorities**"
- Right-click the "**Trusted Root Certification Authorities**" folder and select "**Import...**" > Proceed to browse for the `RootCA.cer` that you previously generated. (*copy it to the domain controller if needed from one of the Certificate Authorities*)
- Proceed to import the certificate, clicking-through all of the prompts and confirmations until it finishes the import.
- Navigate to "**Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies > Intermediate Certification Authorities**"
- Right-click the "**Trusted Root Certification Authorities**" folder and select "**Import...**" > Proceed to browse for the `LAB-CA-02-SubCA.cer` that you previously generated. (*copy it to the domain controller if needed from one of the Certificate Authorities*)
- Proceed to import the certificate, clicking-through all of the prompts and confirmations until it finishes the import.
- Run a `gpupdate /force` on your domain controller(s) and give it a few minutes to pull down their new domain controller certificates
### Validate Auto-Enrollment Functionality
At this point, you need to check that there is a certificate installed within "**Certificates - Local Computer > Personal > Certificates**" for "Domain Controller Server Authentication"
- Load the Certificate - Local Machine (`certlm.msc`) and navigate to "**Personal > Certificates**" > You should see something similar to the following:
| **Issued To** | **Issued By** | **Expiration Date** | **Intended Purposes** | **Certificate Template** |
| :--- | :--- | :--- | :--- | :--- |
| LAB-DC-01.bunny-lab.io | BunnyLab-SubordinateCA-01 | 7/15/2026 | Directory Service Email Replication | Directory Email Replication |
| LAB-DC-01.bunny-lab.io | BunnyLab-SubordinateCA-01 | 7/15/2026 | Client Authentication, Server Authentication, Smart Card Logon | Domain Controller Authentication |
| LAB-DC-01.bunny-lab.io | BunnyLab-SubordinateCA-01 | 7/15/2026 | Client Authentication, Server Authentication, Smart Card Logon, KDC Authentication | Kerberos Authentication |
### Validate LDAPS Connectivity
Lastly, we want to ensure that LDAPS is functioning. By default, once these certs are enrolled on the domain controller(s), LDAPS *should* just work out of the box. To verify this, you can run this command on any device on the same network as the domain controllers. If it comes back successful like in the following example output, then you are golden:
```powershell
PS C:\Users\nicole.rappe> Test-NetConnection LAB-DC-01.bunny-lab.io -Port 636
ComputerName : LAB-DC-01.bunny-lab.io
RemoteAddress : 192.168.3.25
RemotePort : 636
InterfaceAlias : Ethernet
SourceAddress : 192.168.3.254
TcpTestSucceeded : True
PS C:\Users\nicole.rappe> Test-NetConnection LAB-DC-02.bunny-lab.io -Port 636
ComputerName : LAB-DC-02.bunny-lab.io
RemoteAddress : 192.168.3.26
RemotePort : 636
InterfaceAlias : Ethernet
SourceAddress : 192.168.3.254
TcpTestSucceeded : True
```
!!! success "Successful LDAPS Connectivity"
LDAPS should now be functional on your domain controller(s).
!!! abstract "Raw Unprocessed/Unimplemented Steps"
Publish CRLs regularly, configure overlap periods, and monitor expiration. Enable Delta CRLs on the Subordinate CA, but not on the Root.
Security Recommendations
- Harden CA servers; limit access to PKI admins.
- Use BitLocker or HSM for key protection.
- Monitor issuance and renewals with audit logs and scripts.

27
services/authentication/active-directory/group-policy/desktop-shortcut-to-unc-path.md Normal file
View File

@@ -0,0 +1,27 @@
**Purpose**:
To deploy a shortcut to the desktop pointing to a network share's root path. (e.g. `\\storage.bunny-lab.io`). There is a quirk with how Windows handles network shares and shortcuts and doesn't like when you point the shortcut to a root UNC path.
### Group Policy Location
``` mermaid
graph LR
A[Create Group Policy] --> B[User Configuration]
B --> C[Preferences]
C --> D[Windows Settings]
D --> E[Shortcuts]
```
### Group Policy Settings
- **Action**: `Update`
- **Name**: `<FriendlyName>`
- **Target Type**: `File System Object`
- **Location**: `Desktop`
- **Target Path**: `C:\windows\explorer.exe`
- **Arguments**: `\\storage.bunny-lab.io`
- **Start In**: `<Blank>`
- **Shortcut Key**: `<None>`
- **Run**: `Normal Window`
- **Icon File Path**: `%SystemRoot%\System32\SHELL32.dll`
- **Icon Index**: `9`
### Additional Notes
Navigate to the "**Common**" tab in the properties of the shortcut, and check the "**Run in logged-on user's security context (user policy option)**".

12
services/authentication/active-directory/ldap-settings.md Normal file
View File

@@ -0,0 +1,12 @@
**Purpose**: LDAP settings are used in various services from privacyIDEA to Nextcloud. This will outline the basic parameters in my homelab that are necessary to make it function.
| **Field** | **Value** | **Description** |
| :--- | :--- | :--- |
| Server Address(s) | `ldap://bunny-dc-01.bunny-lab.io` / `192.168.3.8`, `ldap://bunny-db-02.bunny.lab.io` / `192.168.3.9` | Domain Controllers |
| Port | `389` | Unencrypted LDAP |
| STARTTLS | `Disabled` | |
| Base DN | `CN=Users,DC=bunny-lab,DC=io` | This is where users are pulled from |
| User / Bind DN | `CN=Nicole Rappe,CN=Users,DC=bunny-lab,DC=io` | This is the domain admin used to connect to LDAP |
| User / Bind Password | `<Password for User / Bind DN>` | Domain Credentials for Domain Admin account |
| Login Attribute | ` LDAP Filter: (&(&(|(objectclass=person))(|(|(memberof=CN=Domain Users,CN=Users,DC=bunny-lab,DC=io)(primaryGroupID=513))))(samaccountname=%uid)) ` | Used by Nextcloud |
| Login Attribute | `(sAMAccountName=*)(objectCategory=person)` | Used by PrivacyIDEA |

8
services/authentication/active-directory/restore-domain-trust.md Normal file
View File

@@ -0,0 +1,8 @@
## Purpose
If you have a device that lost trust in the domain for some reason, and won't let you login using domain credentials, run the following command as a local administrator on the device to repair trust.
```powershell
Test-ComputerSecureChannel -Repair -Credential (Get-Credential)
```
If it outputs `True`, go ahead and log out then try to login again with the domain credentials.

45
services/authentication/authelia.md Normal file
View File

@@ -0,0 +1,45 @@
**Purpose**: Authelia is an open-source authentication and authorization server and portal fulfilling the identity and access management (IAM) role of information security in providing multi-factor authentication and single sign-on (SSO) for your applications via a web portal. It acts as a companion for common reverse proxies.
```yaml title="docker-compose.yml"
services:
authelia:
image: authelia/authelia
container_name: authelia
volumes:
- /mnt/authelia/config:/config
networks:
docker_network:
ipv4_address: 192.168.5.159
expose:
- 9091
restart: unless-stopped
healthcheck:
disable: true
environment:
- TZ=America/Denver
redis:
image: redis:alpine
container_name: redis
volumes:
- /mnt/authelia/redis:/data
networks:
docker_network:
ipv4_address: 192.168.5.158
expose:
- 6379
restart: unless-stopped
environment:
- TZ=America/Denver
networks:
default:
external:
name: docker_network
docker_network:
external: true
```
```jsx title=".env"
Not Applicable
```

168
services/authentication/authentik.md Normal file
View File

@@ -0,0 +1,168 @@
!!! bug
The docker-compose version of the deployment appears bugged and has known issues, deployment via Kubernetes is required to stability and support.
**Purpose**: Authentik is an open-source Identity Provider, focused on flexibility and versatility. With authentik, site administrators, application developers, and security engineers have a dependable and secure solution for authentication in almost any type of environment. There are robust recovery actions available for the users and applications, including user profile and password management. You can quickly edit, deactivate, or even impersonate a user profile, and set a new password for new users or reset an existing password.
This document is based on the [Official Docker-Compose Documentation](https://goauthentik.io/docs/installation/docker-compose). It is meant for testing / small-scale production deployments.
## Docker Configuration
```yaml title="docker-compose.yml"
---
version: "3.4"
services:
postgresql:
image: docker.io/library/postgres:12-alpine
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
start_period: 20s
interval: 30s
retries: 5
timeout: 5s
volumes:
- /srv/containers/authentik/db:/var/lib/postgresql/data
environment:
POSTGRES_PASSWORD: ${PG_PASS:?database password required}
POSTGRES_USER: ${PG_USER:-authentik}
POSTGRES_DB: ${PG_DB:-authentik}
env_file:
- stack.env
networks:
docker_network:
ipv4_address: 192.168.5.2
redis:
image: docker.io/library/redis:alpine
command: --save 60 1 --loglevel warning
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
start_period: 20s
interval: 30s
retries: 5
timeout: 3s
volumes:
- /srv/containers/authentik/redis:/data
networks:
docker_network:
ipv4_address: 192.168.5.3
server:
image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2023.10.7}
restart: unless-stopped
command: server
environment:
AUTHENTIK_REDIS__HOST: redis
AUTHENTIK_POSTGRESQL__HOST: postgresql
AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
volumes:
- /srv/containers/authentik/media:/media
- /srv/containers/authentik/custom-templates:/templates
env_file:
- stack.env
ports:
- "${COMPOSE_PORT_HTTP:-9000}:9000"
- "${COMPOSE_PORT_HTTPS:-9443}:9443"
depends_on:
- postgresql
- redis
networks:
docker_network:
ipv4_address: 192.168.5.4
worker:
image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2023.10.7}
restart: unless-stopped
command: worker
environment:
AUTHENTIK_REDIS__HOST: redis
AUTHENTIK_POSTGRESQL__HOST: postgresql
AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
# `user: root` and the docker socket volume are optional.
# See more for the docker socket integration here:
# https://goauthentik.io/docs/outposts/integrations/docker
# Removing `user: root` also prevents the worker from fixing the permissions
# on the mounted folders, so when removing this make sure the folders have the correct UID/GID
# (1000:1000 by default)
user: root
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /srv/containers/authentik/media:/media
- /srv/containers/authentik/certs:/certs
- /srv/containers/authentik/custom-templates:/templates
env_file:
- stack.env
depends_on:
- postgresql
- redis
networks:
docker_network:
ipv4_address: 192.168.5.5
networks:
default:
external:
name: docker_network
docker_network:
external: true
```
```yaml title=".env"
PG_PASS=<See Below>
AUTHENTIK_SECRET_KEY=<See Below>
AUTHENTIK_BOOTSTRAP_PASSWORD=<SecurePassword>
AUTHENTIK_BOOTSTRAP_TOKEN=<SecureOneTimePassword>
AUTHENTIK_BOOTSTRAP_EMAIL=nicole.rappe@bunny-lab.io
## SMTP Host Emails are sent to
#AUTHENTIK_EMAIL__HOST=localhost
#AUTHENTIK_EMAIL__PORT=25
## Optionally authenticate (don't add quotation marks to your password)
#AUTHENTIK_EMAIL__USERNAME=
#AUTHENTIK_EMAIL__PASSWORD=
## Use StartTLS
#AUTHENTIK_EMAIL__USE_TLS=false
## Use SSL
#AUTHENTIK_EMAIL__USE_SSL=false
#AUTHENTIK_EMAIL__TIMEOUT=10
## Email address authentik will send from, should have a correct @domain
#AUTHENTIK_EMAIL__FROM=authentik@localhost
```
!!! note "Generating Passwords"
Navigate to the online [PWGen Password Generator](https://pwgen.io/en/) to generate the passwords for `PG_PASS` (40 characters) and `AUTHENTIK_SECRET_KEY` (50 characters).
Because of a PostgreSQL limitation, only passwords up to 99 characters are supported
See https://www.postgresql.org/message-id/09512C4F-8CB9-4021-B455-EF4C4F0D55A0@amazon.com
!!! warning "Password Symbols"
You may encounter the Authentik WebUI throwing `Forbidden` errors, and this is likely caused by you using a password with "problematic" characters for the `PG_PASS` environment variable. Try to avoid using `,` or `;` or `:` in the password you generate.
## WebUI Initial Setup
To start the initial setup, navigate to https://192.168.5.4:9443/if/flow/initial-setup/
## Traefik Reverse Proxy Configuration
If the container does not run on the same host as Traefik, you will need to manually add configuration to Traefik's dynamic config file, outlined below.
``` yaml
http:
routers:
PLACEHOLDER:
entryPoints:
- websecure
tls:
certResolver: myresolver
service: PLACEHOLDER
rule: Host(`PLACEHOLDER.bunny-lab.io`)
services:
PLACEHOLDER:
loadBalancer:
servers:
- url: http://PLACEHOLDER:80
passHostHeader: true
```

231
services/authentication/keycloak/deployment.md Normal file
View File

@@ -0,0 +1,231 @@
**Purpose**: Keycloak is an open source identity and access management system for modern applications and services.
- [Original Reference Compose File](https://github.com/JamesTurland/JimsGarage/blob/main/Keycloak/docker-compose.yaml)
- [Original Reference Deployment Video](https://www.youtube.com/watch?v=6ye4lP9EA2Y)
- [Theme Customization Documentation](https://www.baeldung.com/spring-keycloak-custom-themes)
## Keycloak Authentication Sequence
``` mermaid
sequenceDiagram
participant User
participant Traefik as Traefik Reverse Proxy
participant Keycloak
participant Services
User->>Traefik: Access service URL
Traefik->>Keycloak: Redirect to Keycloak for authentication
User->>Keycloak: Provide credentials for authentication
Keycloak->>User: Return authorization token/cookie
User->>Traefik: Send request with authorization token/cookie
Traefik->>Keycloak: Validate token/cookie
Keycloak->>Traefik: Token/cookie is valid
Traefik->>Services: Forward request to services
Services->>Traefik: Response back to Traefik
Traefik->>User: Return service response
```
## Docker Configuration
=== "docker-compose.yml"
```yaml
version: '3.7'
services:
postgres:
image: postgres:16.2
volumes:
- /srv/containers/keycloak/db:/var/lib/postgresql/data
environment:
POSTGRES_DB: ${POSTGRES_DB}
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
healthcheck:
test: ["CMD-SHELL", "pg_isready -U keycloak"]
interval: 10s
timeout: 5s
retries: 5
networks:
keycloak_internal_network: # Network for internal communication
ipv4_address: 172.16.238.3 # Static IP for PostgreSQL in internal network
keycloak:
image: quay.io/keycloak/keycloak:23.0.6
command: start
volumes:
- /srv/containers/keycloak/themes:/opt/keycloak/themes
- /srv/containers/keycloak/base-theme:/opt/keycloak/themes/base
environment:
TZ: America/Denver # (1)
KC_PROXY_ADDRESS_FORWARDING: true # (2)
KC_HOSTNAME_STRICT: false
KC_HOSTNAME: auth.bunny-lab.io # (3)
KC_PROXY: edge # (4)
KC_HTTP_ENABLED: true
KC_DB: postgres
KC_DB_USERNAME: ${POSTGRES_USER}
KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
KC_DB_URL_HOST: postgres
KC_DB_URL_PORT: 5432
KC_DB_URL_DATABASE: ${POSTGRES_DB}
KC_TRANSACTION_RECOVERY: true
KEYCLOAK_ADMIN: ${KEYCLOAK_ADMIN}
KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
KC_HEALTH_ENABLED: true
DB_POOL_MAX_SIZE: 20 # (5)
DB_POOL_MIN_SIZE: 5 # (6)
DB_POOL_ACQUISITION_TIMEOUT: 30 # (7)
DB_POOL_IDLE_TIMEOUT: 300 # (8)
JDBC_PARAMS: "connectTimeout=30"
KC_HOSTNAME_DEBUG: false # (9)
ports:
- 8080:8080
restart: always
depends_on:
postgres:
condition: service_healthy
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/auth"] # Health check for Keycloak
interval: 30s # Health check interval
timeout: 10s # Health check timeout
retries: 3 # Health check retries
networks:
docker_network:
ipv4_address: 192.168.5.2
keycloak_internal_network: # Network for internal communication
ipv4_address: 172.16.238.2 # Static IP for Keycloak in internal network
networks:
default:
external:
name: docker_network
docker_network:
external: true
keycloak_internal_network: # Internal network for private communication
driver: bridge # Network driver
ipam: # IP address management
config:
- subnet: 172.16.238.0/24 # Subnet for internal network
```
1. This sets the timezone of the Keycloak server to your timezone. This is not really necessary according to the official documentation, however I just like to add it to all of my containers as a baseline environment variable to add
2. This assumes you are running Keycloak behind a reverse proxy, in my particular case, Traefik
3. Set this to the FQDN that you are expecting to reach the Keycloak server at behind your reverse proxy
4. This assumes you are running Keycloak behind a reverse proxy, in my particular case, Traefik
5. Maximum connections in the database pool
6. Minimum idle connections in the database pool
7. Timeout for acquiring a connection from the database pool
8. Timeout for closing idle connections to the database
9. If this is enabled, Navigate to https://auth.bunny-lab.io/realms/master/hostname-debug to troubleshoot issues with the deployment if you experience any issues logging into the web portal or admin UI
=== ".env"
```yaml
POSTGRES_DB=keycloak
POSTGRES_USER=keycloak
POSTGRES_PASSWORD=SomethingSecure # (1)
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=SomethingSuperSecureToLoginAsAdmin # (2)
```
1. This is used internally by Keycloak to interact with the PostgreSQL database server
2. This is used to log into the web admin portal at https://auth.bunny-lab.io
## Traefik Reverse Proxy Configuration
If the container does not run on the same host as Traefik, you will need to manually add configuration to Traefik's dynamic config file, outlined below.
```yaml
http:
routers:
auth:
entryPoints:
- websecure
tls:
certResolver: letsencrypt
service: auth
rule: Host(`auth.bunny-lab.io`)
middlewares:
- auth-headers
services:
auth:
loadBalancer:
servers:
- url: http://192.168.5.2:8080
passHostHeader: true
middlewares:
auth-headers:
headers:
sslRedirect: true
stsSeconds: 31536000
stsIncludeSubdomains: true
stsPreload: true
forceSTSHeader: true
customRequestHeaders:
X-Forwarded-Proto: https
X-Forwarded-Port: "443"
```
# Traefik Keycloak Middleware
At this point, we need to add the official Keycloak plugin to Traefik's main configuration. In this example, it will be assumed you need to configure this in Portainer/Docker Compose, and not via a static yml/toml file. Assume you follow the [Docker Compose based Traefik Deployment](../../edge/traefik.md).
## Install Keycloak Plugin
If you do not already have the following added to the end of your `command:` section of the docker-compose.yml file in Portainer, go ahead and add it:
``` yaml
# Keycloak plugin configuration
- "--experimental.plugins.keycloakopenid.moduleName=github.com/Gwojda/keycloakopenid"
- "--experimental.plugins.keycloakopenid.version=v0.1.34"
```
## Add Middleware to Traefik Dynamic Configuration
You will want to ensure the following exists in the dynamically-loaded config file folder, you can name the file whatever you want, but it will be a one-all middleware for any services you want to have communicating as a specific OAuth2 `Client ID`. For example, you might want to have some services exist in a particular realm of Keycloak, or to have different client rules apply to certain services. If this is the case, you can create multiple middlewares in this single yaml file, each handling a different service / realm. It can get pretty complicated if you want to handle a multi-tenant environment, such as one seen in an enterprise environment.
```jsx title="keycloak-middleware.yml"
http:
middlewares:
auth-bunny-lab-io:
plugin:
keycloakopenid:
KeycloakURL: "https://auth.bunny-lab.io" # <- Also supports complete URL, e.g. https://my-keycloak-url.com/auth
ClientID: "traefik-reverse-proxy"
ClientSecret: "https://auth.bunny-lab.io > Clients > traefik-reverse-proxy > Credentials > Client Secret"
KeycloakRealm: "master"
Scope: "openid profile email"
TokenCookieName: "AUTH_TOKEN"
UseAuthHeader: "false"
# IgnorePathPrefixes: "/api,/favicon.ico [comma deliminated] (optional)"
```
## Configure Valid Redirect URLs
At this point, within Keycloak, you need to configure domains that you are allowed to visit after authenticating. You can do this with wildcards, but generally you navigate to "**https://auth.bunny-lab.io > Clients > traefik-reverse-proxy > Valid redirect URIs**" A simple example is adding `https://tools.bunny-lab.io/*` to the list of valid redirect URLs. If the site is not in this list, even if it has the middleware configured in Traefik, it will fail to authenticate and not let the user proceed to the website being protected behind Keycloak.
## Adding Middleware to Dynamic Traefik Service Config Files
At this point, you are in the final stretch, you just need to add the middleware to the Traefik dynamic config files to ensure that it routes the traffic to Keycloak when someone attempts to access that service. Put the following middleware section under the `routers:` section of the config file.
```yaml
middlewares:
- auth-bunny-lab-io # Referencing the Keycloak Server
```
A full example config file would look like the following:
```yaml
http:
routers:
example:
entryPoints:
- websecure
tls:
certResolver: letsencrypt
service: example
rule: Host(`example.bunny-lab.io`)
middlewares:
- auth-bunny-lab-io # Referencing the Keycloak Server Traefik Middleware
services:
example:
loadBalancer:
servers:
- url: http://192.168.5.16:80
passHostHeader: true
```

2
services/authentication/keycloak/oauth2/deployment.md Normal file
View File

@@ -0,0 +1,2 @@
You can deploy Keycloak via a [docker-compose stack](../deployment.md) found within the "Containerization" section of the documentation.

12
services/authentication/keycloak/oauth2/gitea-oauth2.md Normal file
View File

@@ -0,0 +1,12 @@
### OAuth2 Configuration
These are variables referenced by the associated service to connect its authentication system to [Keycloak](../deployment.md).
| **Parameter** | **Value** |
| :--- | :--- |
| Authentication Name | `auth-bunny-lab-io` |
| OAuth2 Provider | `OpenID Connect` |
| Client ID (Key) | `git-bunny-lab-io` |
| Client Secret | `https://auth.bunny-lab.io > Clients > git-bunny-lab-io > Credentials > Client Secret` |
| OpenID Connect Auto Discovery URL | `https://auth.bunny-lab.io/realms/master/.well-known/openid-configuration` |
| Skip Local 2FA | Yes |

15
services/authentication/keycloak/oauth2/portainer-oauth2.md Normal file
View File

@@ -0,0 +1,15 @@
### OAuth2 Configuration
These are variables referenced by the associated service to connect its authentication system to [Keycloak](../deployment.md).
| **Parameter** | **Value** |
| :--- | :--- |
| Client ID | `container-node-01` |
| Client Secret | `https://auth.bunny-lab.io > Clients > container-node-01 > Credentials > Client Secret` |
| Authorization URL | `https://auth.bunny-lab.io/realms/master/protocol/openid-connect/auth` |
| Access Token URL | `https://auth.bunny-lab.io/realms/master/protocol/openid-connect/token` |
| Resource URL | `https://auth.bunny-lab.io/realms/master/protocol/openid-connect/userinfo` |
| Redirect URL | `https://192.168.3.19:9443` |
| Logout URL | `https://auth.bunny-lab.io/realms/master/protocol/openid-connect/logout` |
| User Identifier | `email` |
| Scopes | `email openid profile` |

138
services/authentication/privacyidea.md Normal file
View File

@@ -0,0 +1,138 @@
**Purpose**: privacyIDEA is a modular authentication system. Using privacyIDEA you can enhance your existing applications like local login, VPN, remote access, SSH connections, access to web sites or web portals with a second factor during authentication.
!!! info "Assumptions"
It is assumed you have a provisioned virtual machine / physical machine, running Ubuntu Server 22.04 to deploy a privacyIDEA server.
## AWX Deployment
### Add Server to Inventory and Pull Inventory/Playbook Updates from Gitea
You need to target the new server using a template in AWX (preferrably).
- We will assume the FQDN of the server is `auth.bunny-lab.io` or just `auth`
- Be sure to add the host into the [AWX Homelab Inventory File](https://git.bunny-lab.io/GitOps/awx.bunny-lab.io/src/branch/main/inventories/homelab.ini)
- Update / Sync the "**Bunny-Lab**" project in AWX ([Resources > Projects > Bunny-Lab > Sync](https://awx.bunny-lab.io/#/projects/8/details))
- Update / Sync the git.bunny-lab.io Inventory Source ([Resources > Inventories > Homelab > Sources > git.bunny-lab.io > Sync](https://awx.bunny-lab.io/#/inventories/inventory/2/sources/9/details))
### Create a Template
Next, you want to make a template to automate the deployment of privacyIDEA on any servers that are members of the `[privacyideaServers]` inventory host group. This is useful for development / testing, as well as rapid re-deployment / scaling.
- Navigate to **Resources > Templates > Add**
| **Field** | **Value** |
| :--- | :--- |
| Template Name | `Deploy PrivacyIDEA Server` |
| Description | `Ubuntu Server 22.04 Required` |
| Project | `Bunny-Lab` *(Click the Magnifying Lens)* |
| Inventory | `Homelab` |
| Playbook | `playbooks/Linux/Deployments/privacyIDEA.yml` |
| Execution Environment | `AWX EE (latest)` *(Click the Magnifying Lens)* |
| Credentials | `SSH: (LINUX) nicole` |
**Options**:
- [X] Privilege Escalation: Checked
- [X] Enable Fact Storage: Checked
### Launch the Template
Now we need to launch the template. Assuming all of the above was completed, we can now deploy the playbook/template against the Ubuntu Server via SSH.
- Launch the Template (Rocket Button)
- As the template runs, you will see deployment progress output on the screen
!!! success
You will know if everything was successful if you see something that looks like the following:
``` sh
ok: [auth]
TASK [Install wget and software-properties-common] *****************************
ok: [auth]
TASK [Download PrivacyIDEA signing key] ****************************************
changed: [auth]
TASK [Add signing key for Ubuntu 22.04LTS] *************************************
changed: [auth]
TASK [Add PrivacyIDEA repository] **********************************************
changed: [auth]
TASK [Update apt cache] ********************************************************
changed: [auth]
TASK [Install PrivacyIDEA with Apache2] ****************************************
changed: [auth]
PLAY RECAP *********************************************************************auth : ok=7 changed=5 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
```
## Admin Access to WebUI
### Create a privacyIDEA Administrator Account
You will need to use the CLI in the server in order to create the first administrative account. Run the following command and provide a password for the administrator account.
``` sh
sudo pi-manage admin add nicole.rappe -e nicole.rappe@bunny-lab.io
```
### Log into the WebUI
Assuming you created an `A` record in the DNS server pointing to the IP address of the privacyIDEA server, Navigate to https://auth.bunny-lab.io and sign in with your newly-created username and password. (e.g. `nicole.rappe`)
## Connect to Active Directory/LDAP
### Create a LDAP User ID Resolver
This is what will connect privacyIDEA to an LDAP backend to pull-down users for authentication in Active Directory. Begin by navigating to "**Config > Users > New LDAP Resolver**"
| **Field** | **Value** |
| :--- | :--- |
| Resolver Name | `BunnyLab-LDAP` |
| Server URI | `ldap://bunny-dc-01.bunny-lab.io, ldap://bunny-db-02.bunny.lab.io` |
| Pooling Strategy | `ROUND_ROBIN` |
| StartTLS | `<Unchecked>` |
| Base DN | `CN=Users,DC=bunny-lab,DC=io` |
| Scope | `SUBTREE` |
| Bind Type | `Simple` |
| Bind DN | `CN=Nicole Rappe,CN=Users,DC=bunny-lab,DC=io`
| Bind Password | `<Domain Admin Password for "nicole.rappe">` |
- Click the "**Preset Active Directory**" button.
- Click the "**Test LDAP Resolver**" button.
### Associate User ID Resolver with a Realm
Now we need to create what is called a "**Realm**". Users need to be in realms to have tokens assigned. A user, who is not member of a realm can not have a token assigned and can not authenticate. You can combine several different User ID Resolvers (see UserIdResolvers) into a realm. Navigate to "**Config > Realms**"
| **Field** | **Value** |
| :--- | :--- |
| Realm Name | `Bunny-Lab` |
| Resolver(s) | `BunnyLab-LDAP` |
## Configure Push Notifications
### Create Policies
You will need to create several policies, you can make them all individual, or merge the ones with identical scopes together to keep things more organized. To begin, navigate to "**Config > Policies > Create New Policy**"
- **Scope**: `Enrollment` > "**push_firebase_configuration**" = `poll only`
- **Scope**: `Enrollment` > "**push_registration_url**" = `https://auth.bunny-lab.io/ttype/push`
- **Scope**: `Enrollment` > "**push_ssl_verify**" = `0`
- **Scope**: `Authentication` > "**push_allow_polling**" = `allow`
## Enrolling the First Token
!!! bug "Push Notifications Broken"
Currently, the push notification system (e.g. Cisco DUO") is not behaving as-expected. For now, you can use other authentication methods for the tokens, such as HOTP (on-demand MFA codes) or TOTP (conventional time-based MFA codes).
### TOTP Token
Navigate to "**Tokens > Enroll Token**"
| **Field** | **Value** |
| :--- | :--- |
| Token Type | `TOTP` |
| Realm | `Bunny-Lab` |
| Username | `[256da6f8-9ddb-4ec5-9409-1a95fea27615] nicole.rappe (Nicole Rappe)` |
Use any MFA authenticator app like Bitwarden or Google Authenticator to add the code and store the secret key somewhere safe.
## Install Credential Provider
### Install Credential Provider Subscription File
In order to use the Credential Provider, you have to upload a subscription file. The free-tier allows up to 50 devices using the Credential Provider, but you can alter the source code of privacyIDEA to ignore subscriptions and just unlock everything (custom python code planned).
When you want to leverage MFA in an environment using the server, you need to have a domain-joined computer running the Credential Provider, which can be found on the [Official Credential Provider Github Page](https://github.com/privacyidea/privacyidea-credential-provider/releases).
- Download the MSI
- Run the installer on the computer
- Click "**Next**"
- Check the "**Agree**" checkbox, then click "**Next**"
- Hostname: `auth.bunny-lab.io`
- Path: `/path/to/pi`
- [x] Ignore Unknown CA Errors when Using SSL
- [x] Ignore Invalid Common Name Errors when Using SSL
- Click "**Next**" > "**Next**" > "**Next**"
- Click "**Install**" then "**Finish**"
You can now log out and verify that the credential provider is displayed as an option, and can log in using your domain username, domain password, and TOTP that you configured in the privacyIDEA WebUI.