habsi/authentik
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

website: latest migration to new structure (#11522)

Browse Source 
* first pass

* dependency shenanigans

* move blueprints

* few broken links

* change config the throw errors

* internal file edits

* fighting links

* remove sidebarDev

* fix subdomain

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* fix relative URL

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* fix mismatched package versions

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* fix api reference build

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* test tweak

* links hell

* more links hell

* links hell2

* yep last of the links

* last broken link fixed

* re-add cves

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* add devdocs redirects

* add dir

* tweak netlify.toml

* move latest 2 CVES into dir

* fix links to moved cves

* typoed title fix

* fix link

* remove banner

* remove committed api docs

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* integrations: remove version dropdown

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update Makefile

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* change doc links in web as well

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix some more docs paths

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix more docs paths

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* ci: require ci-web.build for merging

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Revert "ci: require ci-web.build for merging"

This reverts commit b99a4842a9.

* remove sluf for Application

* put slug back in

* minor fix to trigger deploy

---------

Signed-off-by: Jens Langhammer <jens@goauthentik.io>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
Co-authored-by: Tana M Berry <tana@goauthentik.com>
Co-authored-by: Jens Langhammer <jens@goauthentik.io>
Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
This commit is contained in:
Tana M Berry
2024-10-08 14:07:19 -05:00
committed by GitHub
parent 9200a598ec
commit 9a89a5f94b
336 changed files with 2624 additions and 871 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
website/docs/add-secure-apps/outposts/_config.md Normal file
View File

@ -0,0 +1,94 @@
```yaml
# Log level that the outpost will set
# Allowed levels: trace, debug, info, warning, error
# Applies to: non-embedded
log_level: debug
# Interval at which the outpost will refresh the providers
# from authentik. For caching outposts (such as LDAP), the
# cache will also be invalidated at that interval.
# (Format: hours=1;minutes=2;seconds=3).
refresh_interval: minutes=5
########################################
# The settings below are only relevant when using a managed outpost
########################################
# URL that the outpost uses to connect back to authentik
authentik_host: https://authentik.tld/
# Disable SSL Validation for the authentik connection
authentik_host_insecure: false
# Optionally specify a different URL used for user-facing interactions
# Applies to: proxy outposts
authentik_host_browser:
# Template used for objects created (deployments/containers, services, secrets, etc)
object_naming_template: ak-outpost-%(name)s
# Use a specific docker image for this outpost rather than the default. This also applies to Kubernetes
# outposts.
# Applies to: non-embedded
container_image:
########################################
# Docker outpost specific settings
########################################
# Network the outpost container should be connected to
# Applies to: non-embedded
docker_network: null
# Optionally disable mapping of ports to outpost container, may be useful when using docker networks
# (Available with 2021.9.4+)
# Applies to: non-embedded
docker_map_ports: true
# Optionally additional labels for docker containers
# (Available with 2022.1.2)
# Applies to: non-embedded
docker_labels: null
########################################
# Kubernetes outpost specific settings
########################################
# Replica count for the deployment of the outpost
# Applies to: non-embedded
kubernetes_replicas: 1
# Namespace to deploy in, defaults to the same namespace authentik is deployed in (if available)
kubernetes_namespace: authentik
# Any additional annotations to add to the ingress object, for example cert-manager
kubernetes_ingress_annotations: {}
# Name of the secret that is used for TLS connections, leave empty to disable TLS
kubernetes_ingress_secret_name: authentik-outpost-tls
# Service kind created, can be set to LoadBalancer for LDAP outposts for example
kubernetes_service_type: ClusterIP
# Disable any components of the kubernetes integration, can be any of
# - 'secret'
# - 'deployment'
# - 'service'
# - 'prometheus servicemonitor'
# - 'ingress'
# - 'traefik middleware'
kubernetes_disabled_components: []
# If the above docker image is in a private repository, use these secrets to pull.
# NOTE: The secret must be created manually in the namespace first.
# Applies to: non-embedded
kubernetes_image_pull_secrets: []
# Optionally configure an ingress class name. If not set, the ingress will use the cluster's
# default ingress class
# (Available with 2022.11.0+)
# Applies to: proxy outposts
kubernetes_ingress_class_name: null
# Optionally apply an RFC 6902 compliant patch to the Kubernetes objects.
# For an understanding of how this works, refer to the link below:
# https://github.com/kubernetes-sigs/kustomize/blob/master/examples/jsonpatch.md
#
# This value expects a mapping where the key represents
# the Kubernetes component that shall be patched.
# It can be any of the same values supported by `kubernetes_disabled_components`.
#
# For example use this patch to add custom resource requests and limits
# to the outpost deployment:
#
# deployment:
# - op: add
# path: "/spec/template/spec/containers/0/resources"
# value:
# requests:
# cpu: 2000m
# memory: 2000Mi
# limits:
# cpu: 4000m
# memory: 8000Mi
kubernetes_json_patches: null
```

47
website/docs/add-secure-apps/outposts/embedded/embedded.mdx Normal file
View File

@ -0,0 +1,47 @@
---
title: Embedded Outpost
---
Starting with 2021.8.1, authentik comes with an embedded outpost. This has been added to simplify deployment for users using the Proxy provider.
The embedded outpost runs in the main `server` container, and is managed by authentik itself. The embedded outpost authenticates itself via the secret key.
You can access the embedded outpost on the same ports as authentik itself, 9000 and 9443.
If the embedded outpost doesn't make sense for your deployment, you can simply ignore it.
### Configuration
Since authentik doesn't know it's own "primary" URL, there might be some configuration required.
By default, when opening the admin dashboard on a fresh install, authentik will automatically configure the outpost to use the same URL as was used to access authentik.
If this isn't correct, or needs to be changed, click the edit button on the right of the outpost, and set the value of `authentik_host` to the URL you want to login with.
Make sure to set it to full URL, only configuring a hostname or FQDN will not work.
Additionally, most of the other configuration options can be used as with any other outpost, except from items which are marked as "non-embedded"
import Configuration from "../_config.md";
<Configuration />
### Routing
Routing is handled like this:
1. Paths starting with `/static`, `/media` and `/help` return packaged CSS/JS files, and user-uploaded media files.
2. Paths starting with `/outpost.goauthentik.io` are sent to the embedded outpost.
3. Any hosts configured in the providers assigned to the embedded outpost are sent to the outpost.
4. Everything remaining is sent to the authentik backend server.
### Differences
There are a few more differences between managed outposts and the embedded outpost, mainly due to the fact that authentik can't fully manage the containers.
1. (Docker-only) No automatic traefik labels are added to the server container.
When you deploy a managed outpost on docker, the container has several labels to automatically configure traefik. This is not done for the embedded outpost.
2. (Kubernetes-only) An additional service is created.
Since authentik does not know what the normal authentik Service is called, another one is created with a common set of labels that is always set.

68
website/docs/add-secure-apps/outposts/index.mdx Normal file
View File

@ -0,0 +1,68 @@
---
title: Outposts
---
An outpost is a single deployment of an authentik component, essentially a service, that can be deployed anywhere that allows for a connection to the authentik API.
An outpost is required if you use any of the following types of providers with your application:
- [LDAP Provider](../providers/ldap/index.md)
- [Proxy Provider](../providers/proxy/index.md)
- [RADIUS Provider](../providers/radius/index.mdx)
- [RAC Provider](../providers/rac/index.md)
These types of providers use an outpost for increased flexibility and speed. Instead of the provider logic being implemented in authentik Core, these providers use an outpost to handle the logic, which provides improved performance.
An additional advantage of using an outpost is that outposts, like authentik itself, do not require access to the wider internet. Transactions between the application, the provider, and the outpost occur via the authentik API, and support single sign-on operations in firewalled or airgapped deployments and offline connections to remote machines that are not on the internet.
An outpost is given permissions to access the authentik API using a service account and token, both of which are auto-generated when you create a new outpost. The outpost is granted rights to only the application/provider pairs configured (and other necessary related objects such as certificates).
Any change made to the outpost's associated app or provider immediately triggers an event to update the configuration data stored on the outpost, via websockets. Websockets are used also by the outpost to send healthchecks to the authentik Core.
## Create and configure an outpost
1. To create a new outpost, log in to authentik as an administrator, and open to the Admin interface.
2. Navigate to **Applications --> Outposts** and then click **Create**.
![](./outpost-create.png)
3. Define the following values:
- **Name**: a name for the new outpost
- **Type**: select the provider type (Proxy, LDAP, Radius, RAC)
- **Integration** (_optional_): select either your [Docker or Kubernetes connection](#more-about-outpost-integrations)
- **Applications**: select the applications that you want the outpost to serve
- **Advanced settings** (*optional*): For further optional configuration settings, refer to [Configuration](#configuration) below.
4. Click **Create** to save your new outpost settings and close the modal.
Upon creation, a service account and a token is generated. The service account only has permissions to read the outpost and provider configuration. This token is used by the outpost to connect to authentik.
### More about outpost integrations
authentik can manage the deployment, updating, and general lifecycle of an outpost. To communicate with the underlying platforms on which the outpost is deployed, authentik has several built-in integrations.
- If you've deployed authentik on Docker Compose, authentik automatically creates an integration for the local docker socket (See [Docker](./integrations/docker.md)).
- If you've deployed authentik on Kubernetes, with `kubernetesIntegration` set to true (default), authentik automatically creates an integrations for the local Kubernetes Cluster (see [Kubernetes](./integrations/kubernetes.md)).
To deploy an outpost with these integrations, select them during the creation of an outpost. A background task is started, which creates the container/deployment. The outpost deployment can be monitored from the **Dashboards -> System Tasks** page in the Admin interface.
To deploy an outpost manually, see:
- [Kubernetes](./manual-deploy-kubernetes.md)
- [Docker Compose](./manual-deploy-docker-compose.md)
### Configuration
Outposts fetch their configuration from authentik. Below are all the options you can set, and how they influence the outpost.
import Configuration from "./_config.md";
<Configuration />
## Prometheus Metrics
Each authentik outpost has a Prometheus metrics endpoint accessible under port `:9300/metrics`. This endpoint is not mapped via Docker, as the endpoint doesn't have any authentication.
For the embedded outpost, the metrics of the outpost and the metrics of the core authentik server are both returned under the same endpoint.

80
website/docs/add-secure-apps/outposts/integrations/docker.md Normal file
View File

@ -0,0 +1,80 @@
---
title: Docker
---
The Docker integration automatically deploys and manages outpost containers using the Docker HTTP API.
This integration has the advantage over manual deployments of automatic updates (whenever authentik is updated, it updates the outposts), and authentik can (in a future version) automatically rotate the token that the outpost uses to communicate with the core authentik server.
The following outpost settings are used:
- `object_naming_template`: Configures how the container is called
- `container_image`: Optionally overwrites the standard container image (see [Configuration](../../../install-config/configuration/configuration.mdx#authentik_outposts) to configure the global default)
- `docker_network`: The Docker network the container should be added to. This needs to be modified if you plan to connect to authentik using the internal hostname.
- `docker_map_ports`: Enable/disable the mapping of ports. When using a proxy outpost with Traefik for example, you might not want to bind ports as they are routed through Traefik.
- `docker_labels`: Optional additional labels that can be applied to the container.
The container is created with the following hardcoded properties:
- Labels
- `io.goauthentik.outpost-uuid`: Used by authentik to identify the container, and to allow for name changes.
Additionally, the proxy outposts have the following extra labels to add themselves into Traefik automatically.
- `traefik.enable`: "true"
- `traefik.http.routers.ak-outpost-<outpost-name>-router.rule`: `Host(...)`
- `traefik.http.routers.ak-outpost-<outpost-name>-router.service`: `ak-outpost-<outpost-name>-service`
- `traefik.http.routers.ak-outpost-<outpost-name>-router.tls`: "true"
- `traefik.http.services.ak-outpost-<outpost-name>-service.loadbalancer.healthcheck.path`: "/outpost.goauthentik.io/ping"
- `traefik.http.services.ak-outpost-<outpost-name>-service.loadbalancer.healthcheck.port`: "9300"
- `traefik.http.services.ak-outpost-<outpost-name>-service.loadbalancer.server.port`: "9000"
## Permissions
To minimise the potential risks of mapping the Docker socket into a container/giving an application access to the Docker API, many people use Projects like [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy). authentik requires these permissions from the Docker API:
- Images/Pull: authentik tries to pre-pull the custom image if one is configured, otherwise falling back to the default image.
- Containers/Read: Gather infos about currently running container
- Containers/Create: Create new containers
- Containers/Kill: Cleanup during upgrades
- Containers/Remove: Removal of outposts
## Remote hosts (TLS)
To connect remote hosts, follow this guide from Docker [Use TLS (HTTPS) to protect the Docker daemon socket](https://docs.docker.com/engine/security/protect-access/#use-tls-https-to-protect-the-docker-daemon-socket) to configure Docker.
Afterwards, create two certificate-keypairs in authentik:
- `Docker CA`, with the contents of `~/.docker/ca.pem` as Certificate
- `Docker Cert`, with the contents of `~/.docker/cert.pem` as the certificate and `~/.docker/key.pem` as the private key.
Create an integration with `Docker CA` as _TLS Verification Certificate_ and `Docker Cert` as _TLS Authentication Certificate_.
## Remote hosts (SSH)
Starting with authentik 2021.12.5, you can connect to remote Docker hosts using SSH. To configure this, create a new SSH keypair using these commands:
```
# Generate the keypair itself, using RSA keys in the PEM format
ssh-keygen -t rsa -f authentik -N "" -m pem
# Generate a certificate from the private key, required by authentik.
# The values that openssl prompts you for are not relevant
openssl req -x509 -sha256 -nodes -days 365 -out certificate.pem -key authentik
```
You'll end up with three files:
- `authentik.pub` is the public key, this should be added to the `~/.ssh/authorized_keys` file on the target host and user.
- `authentik` is the private key, which should be imported into a Keypair in authentik.
- `certificate.pem` is the matching certificate for the keypair above.
Modify/create a new Docker integration, and set your _Docker URL_ to `ssh://hostname`, and select the keypair you created above as _TLS Authentication Certificate/SSH Keypair_.
The _Docker URL_ field include a user, if none is specified authentik connects with the user `authentik`.
#### Advanced SSH config
With the above configuration, authentik will create and manage an `~/.ssh/config` file. If you need advanced configuration, for example SSH Certificates, you can mount a custom SSH Config file.
Mount the config file into `/authentik/.ssh/config`, and mount any other relevant files into a directory under `/opt`. Afterwards, create an integration using `ssh://hostname`, and don't select a keypair.

46
website/docs/add-secure-apps/outposts/integrations/kubernetes.md Normal file
View File

@ -0,0 +1,46 @@
---
title: Kubernetes
---
The kubernetes integration will automatically deploy outposts on any Kubernetes Cluster.
This integration has the advantage over manual deployments of automatic updates (whenever authentik is updated, it updates the outposts), and authentik can (in a future version) automatically rotate the token that the outpost uses to communicate with the core authentik server.
This integration creates the following objects:
- Deployment for the outpost container
- Service
- Secret to store the token
- Prometheus ServiceMonitor (if the Prometheus Operator is installed in the target cluster)
- Ingress (only Proxy outposts)
- Traefik Middleware (only Proxy outposts with forward auth enabled)
The following outpost settings are used:
- `object_naming_template`: Configures how the container is called
- `container_image`: Optionally overwrites the standard container image (see [Configuration](../../../install-config/configuration/configuration.mdx) to configure the global default)
- `kubernetes_replicas`: Replica count for the deployment of the outpost
- `kubernetes_namespace`: Namespace to deploy in, defaults to the same namespace authentik is deployed in (if available)
- `kubernetes_ingress_annotations`: Any additional annotations to add to the ingress object, for example cert-manager
- `kubernetes_ingress_secret_name`: Name of the secret that is used for TLS connections, can be empty to disable TLS config
- `kubernetes_ingress_class_name`: Optionally set the ingress class used for the generated ingress, requires authentik 2022.11.0
- `kubernetes_service_type`: Service kind created, can be set to LoadBalancer for LDAP outposts for example
- `kubernetes_disabled_components`: Disable any components of the kubernetes integration, can be any of
- 'secret'
- 'deployment'
- 'service'
- 'prometheus servicemonitor'
- 'ingress'
- 'traefik middleware'
- `kubernetes_image_pull_secrets`: If the above docker image is in a private repository, use these secrets to pull. (NOTE: The secret must be created manually in the namespace first.)
- `kubernetes_json_patches`: Applies an RFC 6902 compliant JSON patch to the Kubernetes objects.
## Permissions
The permissions required for this integration are documented in the helm chart. See [Cluster-level](https://github.com/goauthentik/helm/blob/main/charts/authentik-remote-cluster/templates/clusterrolebinding.yaml) and [Namespace-level](https://github.com/goauthentik/helm/blob/main/charts/authentik-remote-cluster/templates/rolebinding.yaml).
## Remote clusters
To add a remote cluster, you can simply install this helm chart in the target cluster and namespace: https://artifacthub.io/packages/helm/goauthentik/authentik-remote-cluster
After installation, the helm chart outputs an example kubeconfig file, that you can enter in authentik to connect to the cluster.

66
website/docs/add-secure-apps/outposts/manual-deploy-docker-compose.md Normal file
View File

@ -0,0 +1,66 @@
---
title: Manual Outpost deployment in docker-compose
---
To deploy an outpost with docker-compose, use this snippet in your docker-compose file.
You can also run the outpost in a separate docker-compose project, you just have to ensure that the outpost container can reach your application container.
### Proxy outpost
```yaml
services:
authentik_proxy:
image: ghcr.io/goauthentik/proxy
# Optionally specify which networks the container should be
# might be needed to reach the core authentik server
# networks:
# - foo
ports:
- 9000:9000
- 9443:9443
environment:
AUTHENTIK_HOST: https://your-authentik.tld
AUTHENTIK_INSECURE: "false"
AUTHENTIK_TOKEN: token-generated-by-authentik
# Starting with 2021.9, you can optionally set this too
# when authentik_host for internal communication doesn't match the public URL
# AUTHENTIK_HOST_BROWSER: https://external-domain.tld
```
### LDAP outpost
```yaml
services:
authentik_ldap:
image: ghcr.io/goauthentik/ldap
# Optionally specify which networks the container should be
# might be needed to reach the core authentik server
# networks:
# - foo
ports:
- 389:3389
- 636:6636
environment:
AUTHENTIK_HOST: https://your-authentik.tld
AUTHENTIK_INSECURE: "false"
AUTHENTIK_TOKEN: token-generated-by-authentik
```
### RADIUS outpost
```yaml
services:
radius_outpost:
image: ghcr.io/goauthentik/radius
# Optionally specify which networks the container should be
# might be needed to reach the core authentik server
# networks:
# - foo
ports:
- 1812:1812/udp
environment:
AUTHENTIK_HOST: https://your-authentik.tld
AUTHENTIK_INSECURE: "false"
AUTHENTIK_TOKEN: token-generated-by-authentik
```

126
website/docs/add-secure-apps/outposts/manual-deploy-kubernetes.md Normal file
View File

@ -0,0 +1,126 @@
---
title: Manual Outpost deployment on Kubernetes
---
Use the following manifest, replacing all values surrounded with `__`.
Afterwards, configure the proxy provider to connect to `<service name>.<namespace>.svc.cluster.local`, and update your Ingress to connect to the `authentik-outpost` service.
```yaml
apiVersion: v1
kind: Secret
metadata:
labels:
app.kubernetes.io/instance: __OUTPOST_NAME__
app.kubernetes.io/managed-by: goauthentik.io
app.kubernetes.io/name: authentik-proxy
app.kubernetes.io/version: 2021.12.3
name: authentik-outpost-api
stringData:
authentik_host: "__AUTHENTIK_URL__"
authentik_host_insecure: "true"
token: "__AUTHENTIK_TOKEN__"
type: Opaque
---
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/instance: __OUTPOST_NAME__
app.kubernetes.io/managed-by: goauthentik.io
app.kubernetes.io/name: authentik-proxy
app.kubernetes.io/version: 2021.12.3
name: authentik-outpost
spec:
ports:
- name: http
port: 9000
protocol: TCP
targetPort: http
- name: https
port: 9443
protocol: TCP
targetPort: https
type: ClusterIP
selector:
app.kubernetes.io/managed-by: goauthentik.io
app.kubernetes.io/name: authentik-outpost
app.kubernetes.io/instance: __OUTPOST_NAME__
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/instance: __OUTPOST_NAME__
app.kubernetes.io/managed-by: goauthentik.io
app.kubernetes.io/name: authentik-proxy
app.kubernetes.io/version: 2021.12.3
name: authentik-outpost
spec:
selector:
matchLabels:
app.kubernetes.io/instance: __OUTPOST_NAME__
app.kubernetes.io/managed-by: goauthentik.io
app.kubernetes.io/name: authentik-proxy
app.kubernetes.io/version: 2021.12.3
template:
metadata:
labels:
app.kubernetes.io/instance: __OUTPOST_NAME__
app.kubernetes.io/managed-by: goauthentik.io
app.kubernetes.io/name: authentik-proxy
app.kubernetes.io/version: 2021.12.3
spec:
containers:
- env:
- name: AUTHENTIK_HOST
valueFrom:
secretKeyRef:
key: authentik_host
name: authentik-outpost-api
- name: AUTHENTIK_TOKEN
valueFrom:
secretKeyRef:
key: token
name: authentik-outpost-api
- name: AUTHENTIK_INSECURE
valueFrom:
secretKeyRef:
key: authentik_host_insecure
name: authentik-outpost-api
image: ghcr.io/goauthentik/proxy
name: proxy
ports:
- containerPort: 9000
name: http
protocol: TCP
- containerPort: 9443
name: https
protocol: TCP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
nginx.ingress.kubernetes.io/affinity: cookie
nginx.ingress.kubernetes.io/proxy-buffer-size: 16k
nginx.ingress.kubernetes.io/proxy-buffers-number: "4"
traefik.ingress.kubernetes.io/affinity: "true"
labels:
app.kubernetes.io/instance: __OUTPOST_NAME__
app.kubernetes.io/managed-by: goauthentik.io
app.kubernetes.io/name: authentik-proxy
app.kubernetes.io/version: 2021.12.3
name: authentik-outpost
spec:
rules:
- host: __EXTERNAL_HOSTNAME__
http:
paths:
- backend:
service:
name: authentik-outpost
port:
name: http
path: /
```

BIN
website/docs/add-secure-apps/outposts/outpost-create.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 131 KiB

11
website/docs/add-secure-apps/outposts/upgrading.md Normal file
View File

@ -0,0 +1,11 @@
---
title: Upgrading an Outpost
---
In the Outpost Overview list, you'll see if any deployed outposts are out of date.
![](./upgrading_outdated.png)
To upgrade the Outpost to the latest version, simply adjust the docker tag of the outpost to the new version.
Since the configuration is managed by authentik, that's all you have to do.

BIN
website/docs/add-secure-apps/outposts/upgrading_outdated.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB