From 03d0899a7689ea04d1fa3dfbd624d7fff8d44fd8 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Mon, 23 Jun 2025 14:56:50 -0400 Subject: [PATCH] website/docs: sys mgmt: clean up certificates and add steps to download saml certs (#14497) * website/docs: sys mgmt: clean up certificates and add steps to download saml certs * fix broken link * Apply suggestions from code review Co-authored-by: Dewi Roberts Signed-off-by: Dominic R * Dewi review comments * Update website/docs/sys-mgmt/certificates.md Signed-off-by: Dominic R * Apply suggestions from code review Signed-off-by: Dominic R * Update website/docs/sys-mgmt/certificates.md Signed-off-by: Tana M Berry * Update website/docs/sys-mgmt/certificates.md Signed-off-by: Tana M Berry * Update website/docs/sys-mgmt/certificates.md Signed-off-by: Dominic R * Update website/docs/sys-mgmt/certificates.md Co-authored-by: Dewi Roberts Signed-off-by: Dominic R * Update website/docs/sys-mgmt/certificates.md Co-authored-by: Dewi Roberts Signed-off-by: Dominic R * Update website/docs/sys-mgmt/certificates.md Signed-off-by: Dominic R * Update website/docs/sys-mgmt/certificates.md Signed-off-by: Dominic R * Update website/docs/sys-mgmt/certificates.md Signed-off-by: Dominic R * lint fix following header rm --------- Signed-off-by: Dominic R Signed-off-by: Tana M Berry Co-authored-by: Dewi Roberts Co-authored-by: Tana M Berry --- website/docs/core/architecture.md | 2 +- website/docs/sys-mgmt/certificates.md | 132 +++++++++++++++++--------- 2 files changed, 86 insertions(+), 48 deletions(-) diff --git a/website/docs/core/architecture.md b/website/docs/core/architecture.md index 9c5dee901f..cbc4dd0a5a 100644 --- a/website/docs/core/architecture.md +++ b/website/docs/core/architecture.md @@ -37,7 +37,7 @@ This container executes background tasks, such as sending emails, the event noti #### Persistence -- `/certs` is used for authentik to import external certs, which in most cases shouldn't be used for SAML, but rather if you use authentik without a reverse proxy, this can be used for example for the [Let's Encrypt integration](../sys-mgmt/certificates.md#lets-encrypt) +- `/certs` is used for authentik to import external certs, which in most cases shouldn't be used for SAML, but rather if you use authentik without a reverse proxy, this can be used for example for the [Let's Encrypt integration](../sys-mgmt/certificates.md#lets-encrypt-integration) - `/templates` is used for [custom email templates](../add-secure-apps/flows-stages/stages/email/index.mdx#custom-templates), and as with the other ones fully optional ### PostgreSQL diff --git a/website/docs/sys-mgmt/certificates.md b/website/docs/sys-mgmt/certificates.md index ecafe7507b..8dadd664ee 100644 --- a/website/docs/sys-mgmt/certificates.md +++ b/website/docs/sys-mgmt/certificates.md @@ -2,85 +2,113 @@ title: Certificates --- -Certificates in authentik are used for the following use cases: +Certificates in authentik are used for: -- Signing and verifying SAML Requests and Responses -- Signing JSON Web Tokens for OAuth and OIDC -- Connecting to remote docker hosts using the Docker integration -- Verifying LDAP Servers' certificates +- Signing and verifying SAML requests and responses +- Signing JSON web tokens for OAuth and OIDC +- Connecting to remote Docker hosts using the Docker integration +- Verifying LDAP servers' certificates - Encrypting outposts' endpoints ## Default certificate -Every authentik install generates a self-signed certificate on the first start. The certificate is called _authentik Self-signed Certificate_ and is valid for 1 year. +Every authentik installation generates a self-signed certificate on first startup. The certificate is named `authentik Self-signed Certificate` and is valid for 1 year. -This certificate is generated to be used as a default for all OAuth2/OIDC providers, as these don't require the certificate to be configured on both sides (the signature of a JWT is validated using the [JWKS](https://auth0.com/docs/security/tokens/json-web-tokens/json-web-key-sets) URL). +This certificate serves as the default for all OAuth2/OIDC providers, as these don't require certificate configuration on both sides (JWT signatures are validated using the [JWKS](../users-sources/sources/protocols/oauth/#jwks) URL). -This certificate can also be used for SAML Providers/Sources, but keep in mind that the certificate is only valid for a year. Some SAML applications require the certificate to be valid, so they might need to be rotated regularly. +While this certificate can be used for SAML providers/sources, remember that it's only valid for a year. Since some SAML applications require valid certificates, you might need to rotate them regularly. -For SAML use-cases, you can generate a Certificate that's valid for longer than 1 year, at your own risk. +For SAML use-cases, you can generate a certificate with a longer validity period (at your own risk). + +## Downloading SAML certificates + +To download a certificate for SAML configuration: + +1. Log into authentik as an administrator, and open the authentik Admin interface. +2. Navigate to **Applications** > **Providers** and click on the name of the provider. +3. Click the **Download** button found under **Download signing certificate**. The contents of this certificate will be required when configuring the service provider. ## External certificates -To use externally managed certificates, for example generated with certbot or HashiCorp Vault, you can use the discovery feature. +To use externally managed certificates (e.g., from Certbot or HashiCorp Vault), you can use the discovery feature. -The Docker Compose installation maps a `certs` directory to `/certs`. You can simply use this as an output directory for certbot. +### Certificate discovery -For Kubernetes, you can map custom secrets/volumes under `/certs`. +authentik can automatically discover and import certificates from a designated directory. This allows you to use externally managed certificates with minimal configuration. -You can also bind mount single files into the folder, as long as they fall under this naming schema. +#### Mounted directories -- Files in the root directory will be imported based on their filename. +- **Docker Compose**: A `certs` directory is mapped to `/certs` within the container +- **Kubernetes**: You can map custom secrets/volumes under `/certs` - `/foo.pem` Will be imported as the keypair `foo`. Based on its content, the file is either imported as a certificate or a private key: +authentik checks for new or changed files every hour and automatically triggers an outpost refresh when changes are detected. - - Files containing `PRIVATE KEY` will imported as private keys. +### Manual imports - - Otherwise the file will be imported as a certificate. +Since authentik 2022.9, you can import certificates with any folder structure directly. Run commands within the worker container to import certificates in different ways: -- If the file is called `fullchain.pem` or `privkey.pem` (the output naming of certbot), it will get the name of the parent folder. -- Files can be in any arbitrary file structure, and can have any extension. -- If the path contains `archive`, the files will be ignored (to better support certbot setups). +#### Import certificate with private key + +Use this option when you need to import a complete certificate keypair that authentik can use for signing or encryption: ```shell +ak import_certificate --certificate /certs/mycert.pem --private-key /certs/private.pem --name mycert +``` + +#### Import certificate for trust only + +Use this option when you only need to establish trust with an external system and don't need the private key: + +```shell +ak import_certificate --certificate /certs/othercert.pem --name othercert +``` + +These commands import certificates under the specified names. They are safe to run as cron jobs, as authentik only re-imports certificates when they change. + +#### Naming conventions + +authentik uses the following rules to import certificates: + +- **Root directory files**: Files in the root directory are imported based on their filename + + - `/foo.pem` will be imported as the keypair `foo` + - Files are classified as private keys if they contain `PRIVATE KEY`, otherwise as certificates + +- **Certbot convention**: Files named `fullchain.pem` or `privkey.pem` will use their parent folder's name + + - Files in paths containing `archive` are ignored (to better support certbot setups) + +- **Flexible organization**: Files can use any directory structure and extension + +#### Directory structure example + +Below is an example of a valid certificate directory structure: + +```text certs/ ├── baz -│   └── bar.baz -│   ├── fullchain.pem -│   └── privkey.pem +│ └── bar.baz +│ ├── fullchain.pem +│ └── privkey.pem ├── foo.bar -│   ├── fullchain.pem -│   └── privkey.pem +│ ├── fullchain.pem +│ └── privkey.pem ├── foo.key └── foo.pem ``` -Files are checked every 5 minutes and will trigger an Outpost refresh if a file has changed. - -#### Manual imports - -Starting with authentik 2022.9, you can also import certificates with any folder structure directly. To do this, run the following command within the worker container: - -```shell -ak import_certificate --certificate /certs/mycert.pem --private-key /certs/something.pem --name test -# --private-key can be omitted to only import a certificate, i.e. to trust other connections -# ak import_certificate --certificate /certs/othercert.pem --name test2 -``` - -This will import the certificate into authentik under the given name. This command is safe to run as a cron job; authentik will only re-import the certificate if it changes. - ## Web certificates -Starting with authentik 2021.12.4, you can configure the certificate authentik uses for its core webserver. For most deployments this will not be relevant and reverse proxies are used, but this can be used to create a very compact and self-contained authentik install. +You can configure the certificate used by authentik's core webserver, which allows for compact and self-contained authentik installations, even though most deployments use reverse proxies. -#### Let's Encrypt +### Let's Encrypt integration -To use Let's Encrypt certificates with this setup, using certbot, you can use this compose override (create or edit a file called `docker-compose.override.yml` in the same folder as the authentik docker-compose file) +To use Let's Encrypt certificates with Certbot in Docker Compose deployments, create or edit the `docker-compose.override.yml` file in the same directory as your authentik Docker Compose file. The example below demonstrates the use of the AWS Route 53 DNS plugin: ```yaml services: certbot: - image: certbot/dns-route53:v1.22.0 + image: certbot/dns-route53:v4.0.0 volumes: - ./certs/:/etc/letsencrypt # Variables depending on DNS Plugin @@ -90,14 +118,24 @@ services: - certonly - --non-interactive - --agree-tos - - -m your.email@company + # Replace your@email.com with the email you wish to use + - -m your@email.com + # Replace authentik.company with your actual domain - -d authentik.company # Again, match with your provider - --dns-route53 ``` -Afterward, run `docker compose up -d`, which will start certbot and generate your certificate. Within a few minutes, you'll see the certificate in your authentik interface. (If the certificate does not appear, restart the worker container. This is caused by incompatible permissions set by certbot). +:::info +For other DNS providers and detailed setup instructions, see the official [Certbot Docker documentation](https://eff-certbot.readthedocs.io/en/latest/install.html#alternative-1-docker). Certbot provides Docker images for many popular DNS providers. +::: -Navigate to _System -> Brands_, edit any brand and select the certificate of your choice. +:::info +The Certbot container only runs once. You'll need to set up a separate mechanism for regular certificate renewals. +::: -Keep in mind this certbot container will only run once, but there are a variety of ways to schedule regular renewals. +Run `docker compose up -d` to create and start the Certbot container and generate your certificate. The certificate should appear in authentik within minutes. If it doesn't, restart the worker container (this can happen due to permission issues set by Certbot). + +For Kubernetes or AWS deployments, you can use similar approaches with appropriate certificate management tools for your platform. + +Navigate to **System** > **Brands**, edit any brand, and select your preferred certificate.