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

68
website/docs/install-config/air-gapped.mdx Normal file
View File

@ -0,0 +1,68 @@
---
title: Air-gapped environments
---
## Outbound connections
By default, authentik creates outbound connections to the following URLs:
- https://version.goauthentik.io: Periodic update check
- https://goauthentik.io: Anonymous analytics on startup
- https://secure.gravatar.com: Avatars for users
- https://authentik.error-reporting.a7k.io: Error reporting
To disable these outbound connections, adjust the settings as follows:
## Configuration options
To view a list of all configuration options, refer to the [Configuration](./configuration/configuration.mdx) documentation.
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<Tabs
defaultValue="docker-compose"
values={[
{label: 'docker-compose', value: 'docker-compose'},
{label: 'Kubernetes', value: 'kubernetes'},
]}>
<TabItem value="docker-compose">
Add the following block to your `.env` file:
```shell
AUTHENTIK_DISABLE_STARTUP_ANALYTICS=true
AUTHENTIK_DISABLE_UPDATE_CHECK=true
AUTHENTIK_ERROR_REPORTING__ENABLED=false
```
Afterwards, run the upgrade commands from the latest release notes.
</TabItem>
<TabItem value="kubernetes">
Add the following block to your `values.yml` file:
```yaml
authentik:
error_reporting:
enabled: false
disable_update_check: true
disable_startup_analytics: true
```
Afterwards, run the upgrade commands from the latest release notes.
</TabItem>
</Tabs>
## Settings
In addition to the configuration options above, the following [System settings](../sys-mgmt/settings.md) need to also be adjusted:
- **Avatars**: By default this setting uses [Gravatar](https://secure.gravatar.com/). The option can be set to a combination of any of the other options, for example `initials`
## Container images
Container images can be pulled from the following URLs:
- ghcr.io/goauthentik/server (https://ghcr.io)
- beryju/authentik (https://index.docker.io)

37
website/docs/install-config/automated-install.md Normal file
View File

@ -0,0 +1,37 @@
---
title: Automated install
---
To install authentik automatically (skipping the Out-of-box experience), you can use the following environment variables on the worker container:
### `AUTHENTIK_BOOTSTRAP_PASSWORD`
Configure the default password for the `akadmin` user. Only read on the first startup. Can be used for any flow executor.
### `AUTHENTIK_BOOTSTRAP_TOKEN` <span class="badge badge--version">authentik 2021.8+</span>
Create a token for the default `akadmin` user. Only read on the first startup. The string you specify for this variable is the token key you can use to authenticate yourself to the API.
### `AUTHENTIK_BOOTSTRAP_EMAIL` <span class="badge badge--version">authentik 2023.3+</span>
Set the email address for the default `akadmin` user.
## Kubernetes
In the Helm values, set the `akadmin`user password and token:
```text
authentik:
bootstrap_token: test
bootstrap_password: test
```
To store the password and token in a secret, use:
```text
envFrom:
- secretRef:
name: _some-secret_
```
where _some-secret_ contains the environment variables as in the documentation above.

88
website/docs/install-config/beta.mdx Normal file
View File

@ -0,0 +1,88 @@
---
title: Beta versions
---
You can test upcoming authentik versions, including major new features that are in "Beta release", by switching to the _next_ images. It is recommended to upgrade to the latest stable release before upgrading to Beta images. It is always possible to upgrade from the Beta to the next stable release.
:::warning
Downgrading from the Beta is not supported. It is recommended to take a backup before upgrading, or test Beta versions on a separate install. Upgrading from Beta versions to the next release is usually possible, however also not supported.
:::
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<Tabs
defaultValue="docker-compose"
values={[
{label: 'Docker Compose', value: 'docker-compose'},
{label: 'Kubernetes', value: 'kubernetes'},
]}
groupId="platform">
<TabItem value="docker-compose">
Add the following block to your `.env` file:
```shell
AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-next
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
```
The Beta image is amd64 only. For arm64 platforms, append `-arm64` to the tag name (no spaces).
Next, run the upgrade commands below.
</TabItem>
<TabItem value="kubernetes">
Add the following block to your `values.yml` file:
```yaml
authentik:
outposts:
container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
image:
repository: ghcr.io/goauthentik/dev-server
tag: gh-next
# pullPolicy: Always to ensure you always get the latest version
pullPolicy: Always
```
The Beta image is amd64 only. For arm64 platforms, append `-arm64` to the tag name (no spaces).
Next, run the upgrade commands below.
</TabItem>
</Tabs>
<Tabs
defaultValue="docker-compose"
values={[
{label: 'Docker Compose', value: 'docker-compose'},
{label: 'Kubernetes', value: 'kubernetes'},
]}
groupId="platform">
<TabItem value="docker-compose">
```shell
docker compose pull
docker compose up -d
```
</TabItem>
<TabItem value="kubernetes">
```shell
helm repo update
helm upgrade authentik authentik/authentik -f values.yaml
```
</TabItem>
</Tabs>
:::info
If you are upgrading from an older Beta release to the most recent Beta release, you might need to run `kubectl rollout restart deployment`, because Helm needs to recreate the pods in order to pick up the new image (the tag doesn't change).
:::
To verify whether the upgrade was successful, go to your Admin panel and navigate to the Overview dashboard. There, you can check the version number to ensure that you are using the Beta version you intended.

358
website/docs/install-config/configuration/configuration.mdx Normal file
View File

@ -0,0 +1,358 @@
---
title: Configuration
---
This page details all the authentik configuration options that you can set via environment variables.
## About authentik configurations
:::info
The double-underscores are intentional, as all these settings are translated to YAML internally, and a double-underscore indicates the next level (a subsetting).
:::
All of these variables can be set to values, but you can also use a URI-like format to load values from other places:
- `env://<name>` Loads the value from the environment variable `<name>`. Fallback can be optionally set like `env://<name>?<default>`
- `file://<name>` Loads the value from the file `<name>`. Fallback can be optionally set like `file://<name>?<default>`
## Set your environment variables
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<Tabs groupId="platform">
<TabItem value="docker-compose" label="Docker Compose" default>
If you are using Docker Compose, edit your <code>.env</code> file to append any keys that you want to add, and then run the following command to apply them:
```
docker compose up -d
```
</TabItem>
<TabItem value="kubernetes" label="Kubernetes">
If you are running in Kubernetes, edit your <code>values.yaml</code> file to append any keys that you want to add, and then run the following commands to apply:
```
helm repo update
helm upgrade --install authentik authentik/authentik -f values.yaml
```
</TabItem>
</Tabs>
## Verify your configuration settings
To check if your config has been applied correctly, you can run the following command to output the full config:
<Tabs groupId="platform">
<TabItem value="docker-compose" label="Docker Compose" default>
```
docker compose run --rm worker dump_config
```
</TabItem>
<TabItem value="kubernetes" label="Kubernetes">
```
kubectl exec -it deployment/authentik-worker -c worker -- ak dump_config
```
</TabItem>
</Tabs>
## PostgreSQL Settings
- `AUTHENTIK_POSTGRESQL__HOST`: Hostname of your PostgreSQL Server
- `AUTHENTIK_POSTGRESQL__NAME`: Database name
- `AUTHENTIK_POSTGRESQL__USER`: Database user
- `AUTHENTIK_POSTGRESQL__PORT`: Database port, defaults to 5432
- `AUTHENTIK_POSTGRESQL__PASSWORD`: Database password, defaults to the environment variable `POSTGRES_PASSWORD`
- `AUTHENTIK_POSTGRESQL__USE_PGBOUNCER`: Adjust configuration to support connection to PgBouncer
- `AUTHENTIK_POSTGRESQL__USE_PGPOOL`: Adjust configuration to support connection to Pgpool
- `AUTHENTIK_POSTGRESQL__SSLMODE`: Strictness of ssl verification. Defaults to `"verify-ca"`
- `AUTHENTIK_POSTGRESQL__SSLROOTCERT`: CA root for server ssl verification
- `AUTHENTIK_POSTGRESQL__SSLCERT`: Path to x509 client certificate to authenticate to server
- `AUTHENTIK_POSTGRESQL__SSLKEY`: Path to private key of `SSLCERT` certificate
All PostgreSQL settings, apart from `USE_PGBOUNCER` and `USE_PGPOOL`, support hot-reloading. Adding and removing read replicas doesn't support hot-reloading.
### Read replicas
You can configure additional read replica databases that are used only for read operations. To configure authentik to use replicas, add the settings below to your [configuration file](./configuration.mdx#set-your-environment-variables). If you have multiple replicas, add additional settings for each replica, replacing the default `0` with a unique value for each additional replica.
If read replicas are configured, the main database is not used for reads. If you'd like the main database to be included for reads, add it as a read replica.
The same PostgreSQL settings as described above are used for each read replica.
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__HOST`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__NAME`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__USER`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__PORT`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__PASSWORD`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLMODE`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLROOTCERT`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLCERT`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLKEY`
Note that `USE_PGBOUNCER` and `USE_PGPOOL` are inherited from the main database configuration and are _not_ overridable on read replicas.
## Redis Settings
- `AUTHENTIK_REDIS__HOST`: Redis server host when not using configuration URL
- `AUTHENTIK_REDIS__PORT`: Redis server port when not using configuration URL
- `AUTHENTIK_REDIS__DB`: Redis server database when not using configuration URL
- `AUTHENTIK_REDIS__USERNAME`: Redis server username when not using configuration URL
- `AUTHENTIK_REDIS__PASSWORD`: Redis server password when not using configuration URL
- `AUTHENTIK_REDIS__TLS`: Redis server connection using TLS when not using configuration URL
- `AUTHENTIK_REDIS__TLS_REQS`: Redis server TLS connection requirements when not using configuration URL. Defaults to `"none"`. Allowed values are `"none"` and `"required"`.
- `AUTHENTIK_REDIS__TLS_CA_CERT`: Path to the Redis server TLS CA root when not using configuration URL. Defaults to `null`.
## Result Backend Settings
- `AUTHENTIK_RESULT_BACKEND__URL`: Result backend configuration URL, uses [the Redis Settings](#redis-settings) by default
## Cache Settings
- `AUTHENTIK_CACHE__URL`: Cache configuration URL, uses [the Redis Settings](#redis-settings) by default
- `AUTHENTIK_CACHE__TIMEOUT`: Timeout for cached data until it expires in seconds, defaults to 300
- `AUTHENTIK_CACHE__TIMEOUT_FLOWS`: Timeout for cached flow plans until they expire in seconds, defaults to 300
- `AUTHENTIK_CACHE__TIMEOUT_POLICIES`: Timeout for cached policies until they expire in seconds, defaults to 300
- `AUTHENTIK_CACHE__TIMEOUT_REPUTATION`: Timeout for cached reputation until they expire in seconds, defaults to 300
:::info
`AUTHENTIK_CACHE__TIMEOUT_REPUTATION` only applies to the cache expiry, see [`AUTHENTIK_REPUTATION__EXPIRY`](#authentik_reputation__expiry-authentik-202382) to control how long reputation is persisted for.
:::
## Channel Layer Settings (inter-instance communication)
- `AUTHENTIK_CHANNEL__URL`: Channel layers configuration URL, uses [the Redis Settings](#redis-settings) by default
## Broker Settings
- `AUTHENTIK_BROKER__URL`: Broker configuration URL, defaults to Redis using [the respective settings](#redis-settings)
- `AUTHENTIK_BROKER__TRANSPORT_OPTIONS`: Base64-encoded broker transport options
:::info
`AUTHENTIK_REDIS__CACHE_TIMEOUT_REPUTATION` only applies to the cache expiry, see [`AUTHENTIK_REPUTATION__EXPIRY`](#authentik_reputation__expiry-authentik-202382) to control how long reputation is persisted for.
:::
## Listen Settings
- `AUTHENTIK_LISTEN__HTTP`: Listening address:port (e.g. `0.0.0.0:9000`) for HTTP (Applies to Server and Proxy outpost)
- `AUTHENTIK_LISTEN__HTTPS`: Listening address:port (e.g. `0.0.0.0:9443`) for HTTPS (Applies to Server and Proxy outpost)
- `AUTHENTIK_LISTEN__LDAP`: Listening address:port (e.g. `0.0.0.0:3389`) for LDAP (Applies to LDAP outpost)
- `AUTHENTIK_LISTEN__LDAPS`: Listening address:port (e.g. `0.0.0.0:6636`) for LDAPS (Applies to LDAP outpost)
- `AUTHENTIK_LISTEN__METRICS`: Listening address:port (e.g. `0.0.0.0:9300`) for Prometheus metrics (Applies to All)
- `AUTHENTIK_LISTEN__DEBUG`: Listening address:port (e.g. `0.0.0.0:9900`) for Go Debugging metrics (Applies to All)
- `AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS`: List of comma-separated CIDRs that proxy headers should be accepted from (Applies to Server)
Defaults to `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fe80::/10`, `::1/128`.
Requests directly coming from one an address within a CIDR specified here are able to set proxy headers, such as `X-Forwarded-For`. Requests coming from other addresses will not be able to set these headers.
## Media Storage Settings
These settings affect where media files are stored. Those files include applications and sources icons. By default, they are stored on disk in the `/media` directory of the authentik container. S3 storage is also supported.
- `AUTHENTIK_STORAGE__MEDIA__BACKEND`: Where to store files. Valid values are `file` and `s3`. For `file` storage, files are stored in a `/media` directory in the container. For `s3`, see below.
- `AUTHENTIK_STORAGE__MEDIA__S3__REGION`: S3 region where the bucket has been created. May be omitted depending on which S3 provider you use. No default.
- `AUTHENTIK_STORAGE__MEDIA__S3__USE_SSL`: Whether to use HTTPS when talking to the S3 storage providers. Defaults to `true`.
- `AUTHENTIK_STORAGE__MEDIA__S3__ENDPOINT`: Endpoint to use to talk to the S3 storage provider. Override the previous region and use_ssl settings. Must be a valid URL in the form of `https://s3.provider`. No default.
- `AUTHENTIK_STORAGE__MEDIA__S3__SESSION_PROFILE`: Profile to use when using AWS SDK authentication. No default. Supports hot-reloading.
- `AUTHENTIK_STORAGE__MEDIA__S3__ACCESS_KEY`: Access key to authenticate to S3. May be omitted if using AWS SDK authentication. Supports hot-reloading.
- `AUTHENTIK_STORAGE__MEDIA__S3__SECRET_KEY`: Secret key to authenticate to S3. May be omitted if using AWS SDK authentication. Supports hot-reloading.
- `AUTHENTIK_STORAGE__MEDIA__S3__SECURITY_TOKEN`: Security token to authenticate to S3. May be omitted. Supports hot-reloading.
- `AUTHENTIK_STORAGE__MEDIA__S3__BUCKET_NAME`: Name of the bucket to use to store files.
- `AUTHENTIK_STORAGE__MEDIA__S3__CUSTOM_DOMAIN`: Domain to use to create URLs for users. Mainly useful for non-AWS providers. May include a port. Must include the bucket. Example: `s3.company:8080/authentik-media`.
- `AUTHENTIK_STORAGE__MEDIA__S3__SECURE_URLS`: Whether URLs created use HTTPS (set to `true` by default) or HTTP.
## authentik Settings
### `AUTHENTIK_SECRET_KEY`
Secret key used for cookie signing. Changing this will invalidate active sessions.
:::caution
Prior to 2023.6.0 the secret key was also used for unique user IDs. When running a pre-2023.6.0 version of authentik the key should _not_ be changed after the first install.
:::
### `AUTHENTIK_LOG_LEVEL`
Log level for the server and worker containers. Possible values: `debug`, `info`, `warning`, `error`.
Starting with 2021.12.3, you can also set the log level to `trace`. This has no effect on the core authentik server, but shows additional messages for the embedded outpost.
:::danger
Setting the log level to `trace` will include sensitive details in logs, so it shouldn't be used in most cases.
Logs generated with `trace` should be treated with care as they can give others access to your instance, and can potentially include things like session cookies to authentik **and other pages**.
:::
Defaults to `info`.
### `AUTHENTIK_COOKIE_DOMAIN`
Which domain the session cookie should be set to. By default, the cookie is set to the domain authentik is accessed under.
### `AUTHENTIK_EVENTS__CONTEXT_PROCESSORS__GEOIP`
Path to the GeoIP City database. Defaults to `/geoip/GeoLite2-City.mmdb`. If the file is not found, authentik will skip GeoIP support.
### `AUTHENTIK_EVENTS__CONTEXT_PROCESSORS__ASN`
Path to the GeoIP ASN database. Defaults to `/geoip/GeoLite2-ASN.mmdb`. If the file is not found, authentik will skip GeoIP support.
### `AUTHENTIK_DISABLE_UPDATE_CHECK`
Disable the inbuilt update-checker. Defaults to `false`.
### `AUTHENTIK_ERROR_REPORTING`
- `AUTHENTIK_ERROR_REPORTING__ENABLED`
Enable error reporting. Defaults to `false`.
Error reports are sent to https://sentry.io and are used for debugging and general feedback. Anonymous performance data is also sent.
- `AUTHENTIK_ERROR_REPORTING__SENTRY_DSN`
Sets the DSN for the Sentry API endpoint.
When error reporting is enabled, the default Sentry DSN will allow the authentik developers to receive error reports and anonymous performance data, which is used for general feedback about authentik, and in some cases, may be used for debugging purposes.
Users can create their own hosted Sentry account (or self-host Sentry) and opt to collect this data themselves.
- `AUTHENTIK_ERROR_REPORTING__ENVIRONMENT`
The environment tag associated with all data sent to Sentry. Defaults to `customer`.
When error reporting has been enabled to aid in debugging issues, this should be set to a unique value, such as an email address.
- `AUTHENTIK_ERROR_REPORTING__SEND_PII`
Whether or not to send personal data, like usernames. Defaults to `false`.
- `AUTHENTIK_ERROR_REPORTING__EXTRA_ARGS`
Base64-encoded sentry_init arguments. See [Sentry's documentation](https://docs.sentry.io/platforms/python/configuration/options/) for available options.
### `AUTHENTIK_EMAIL`
- `AUTHENTIK_EMAIL__HOST`
Default: `localhost`
- `AUTHENTIK_EMAIL__PORT`
Default: `25`
- `AUTHENTIK_EMAIL__USERNAME`
Default: `` (Don't add quotation marks)
- `AUTHENTIK_EMAIL__PASSWORD`
Default: `` (Don't add quotation marks)
- `AUTHENTIK_EMAIL__USE_TLS`
Default: `false`
- `AUTHENTIK_EMAIL__USE_SSL`
Default: `false`
- `AUTHENTIK_EMAIL__TIMEOUT`
Default: `10`
- `AUTHENTIK_EMAIL__FROM`
Default: `authentik@localhost`
Email address authentik will send from, should have a correct @domain
To change the sender's display name, use a format like `Name <account@domain>`.
### `AUTHENTIK_OUTPOSTS`
- `AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE`
Placeholders:
- `%(type)s`: Outpost type; proxy, ldap, etc
- `%(version)s`: Current version; 2021.4.1
- `%(build_hash)s`: Build hash if you're running a beta version
Placeholder for outpost docker images. Default: `ghcr.io/goauthentik/%(type)s:%(version)s`.
- `AUTHENTIK_OUTPOSTS__DISCOVER`
Configure the automatic discovery of integrations. Defaults to `true`.
By default, the following is discovered:
- Kubernetes in-cluster config
- Kubeconfig
- Existence of a docker socket
### `AUTHENTIK_LDAP__TASK_TIMEOUT_HOURS` <span class="badge badge--version">authentik 2023.1+</span>
Timeout in hours for LDAP synchronization tasks.
Defaults to `2`.
### `AUTHENTIK_LDAP__PAGE_SIZE` <span class="badge badge--version">authentik 2023.6.1+</span>
Page size for LDAP synchronization. Controls the number of objects created in a single task.
Defaults to `50`.
### `AUTHENTIK_LDAP__TLS__CIPHERS` <span class="badge badge--version">authentik 2022.7+</span>
Allows configuration of TLS Cliphers for LDAP connections used by LDAP sources. Setting applies to all sources.
Defaults to `null`.
### `AUTHENTIK_REPUTATION__EXPIRY` <span class="badge badge--version">authentik 2023.8.2+</span>
Configure how long reputation scores should be saved for in seconds. Note that this is different than [`AUTHENTIK_REDIS__CACHE_TIMEOUT_REPUTATION`](#redis-settings), as reputation is saved to the database every 5 minutes.
Defaults to `86400`.
### `AUTHENTIK_SESSION_STORAGE` <span class="badge badge--version">authentik 2024.4+</span>
Configure if the sessions are stored in the cache or the database. Defaults to `cache`. Allowed values are `cache` and `db`. Note that changing this value will invalidate all previous sessions.
### `AUTHENTIK_WEB__WORKERS` <span class="badge badge--version">authentik 2022.9+</span>
Configure how many gunicorn worker processes should be started (see https://docs.gunicorn.org/en/stable/design.html).
Defaults to 2. A value below 2 workers is not recommended. In environments where scaling with multiple replicas of the authentik server is not possible, this number can be increased to handle higher loads.
### `AUTHENTIK_WEB__THREADS` <span class="badge badge--version">authentik 2022.9+</span>
Configure how many gunicorn threads a worker processes should have (see https://docs.gunicorn.org/en/stable/design.html).
Defaults to 4.
### `AUTHENTIK_WORKER__CONCURRENCY` <span class="badge badge--version">authentik 2023.9+</span>
Configure Celery worker concurrency for authentik worker (see https://docs.celeryq.dev/en/latest/userguide/configuration.html#worker-concurrency). This essentially defines the number of worker processes spawned for a single worker.
Defaults to 2.
## System settings <span class="badge badge--version">authentik 2024.2+</span>
Additional settings are configurable using the Admin interface, under **System** -> **Settings** or using the API.
## Custom python settings
To modify additional settings further than the options above allow, you can create a custom Python file and mount it to `/data/user_settings.py`. This file will be loaded on startup by both the server and the worker. All default settings are [here](https://github.com/goauthentik/authentik/blob/main/authentik/root/settings.py)
:::caution
Using these custom settings is not supported and can prevent your authentik instance from starting. Use with caution.
:::

BIN
website/docs/install-config/dashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 284 KiB

107
website/docs/install-config/geoip.mdx Normal file
View File

@ -0,0 +1,107 @@
# GeoIP
authentik supports GeoIP to add additional information to login/authorization/enrollment requests. Additionally, a [GeoIP policy](../customize/policies/index.md#geoip-policy) can be used to make policy decisions based on the lookup result.
### Configuration
:::info
Starting with authentik 2022.12, GeoIP is bundled and does not require any additional setup.
:::
By default, the GeoIP database is loaded from `/geoip/GeoLite2-City.mmdb`. If more frequent database updates are desired, a volume can be mounted to `/geoip` to update this file externally. authentik will automatically re-load the file when it changes.
### Deactivating GeoIP
If you want to disable GeoIP, you can set the path to a non-existent path and authentik will skip the GeoIP.
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<Tabs
defaultValue="docker-compose"
values={[
{label: 'docker-compose', value: 'docker-compose'},
{label: 'Kubernetes', value: 'kubernetes'},
]}>
<TabItem value="docker-compose">
Add the following block to your `.env` file:
```shell
AUTHENTIK_EVENTS__CONTEXT_PROCESSORS__GEOIP=/tmp/non-existent-file
AUTHENTIK_EVENTS__CONTEXT_PROCESSORS__ASN=/tmp/non-existent-file
```
Afterwards, run the upgrade commands from the latest release notes.
</TabItem>
<TabItem value="kubernetes">
Add the following block to your `values.yml` file:
```yaml
authentik:
events:
context_processors:
geoip: "/tmp/non-existent-file"
asn: "/tmp/non-existent-file"
```
Afterwards, run the upgrade commands from the latest release notes.
</TabItem>
</Tabs>
### External updates
Sign up for a free MaxMind account [here](https://www.maxmind.com/en/geolite2/signup).
<Tabs
defaultValue="docker-compose"
values={[
{label: 'docker-compose', value: 'docker-compose'},
{label: 'Kubernetes', value: 'kubernetes'},
]}>
<TabItem value="docker-compose">
Add the following block to a `docker-compose.override.yml` file in the same folder as the authentik docker-compose file:
```yaml
services:
server:
volumes:
- geoip:/geoip
worker:
volumes:
- geoip:/geoip
geoipupdate:
image: "maxmindinc/geoipupdate:latest"
volumes:
- "geoip:/usr/share/GeoIP"
environment:
GEOIPUPDATE_EDITION_IDS: "GeoLite2-City GeoLite2-ASN"
GEOIPUPDATE_FREQUENCY: "8"
GEOIPUPDATE_ACCOUNT_ID: "*your account ID*"
GEOIPUPDATE_LICENSE_KEY: "*your license key*"
volumes:
geoip:
driver: local
```
Afterwards, run the upgrade commands from the latest release notes.
</TabItem>
<TabItem value="kubernetes">
Add the following block to your `values.yml` file:
```yaml
geoip:
enabled: true
accountId: "*your account ID*"
licenseKey: "*your license key*"
editionIds: "GeoLite2-City GeoLite2-ASN"
image: maxmindinc/geoipupdate:v4.8
updateInterval: 8
```
Afterwards, run the upgrade commands from the latest release notes.
</TabItem>
</Tabs>

13
website/docs/install-config/index.mdx Normal file
View File

@ -0,0 +1,13 @@
---
title: Installation
---
Everything you need to get authentik up and running!
For information about upgrading to a new version, refer to the <b>Upgrade</b> section in the relevant [Release Notes](../releases) and to our [Upgrade authentik](./upgrade.mdx) documentation.
The installation process for our free open source version and our [Enterprise](../enterprise/index.md) version are exactly the same. For information about obtaining an Enterprise license, refer to [License management](../enterprise/manage-enterprise.md#license-management) documentation.
import DocCardList from "@theme/DocCardList";
<DocCardList />

122
website/docs/install-config/install/docker-compose.mdx Normal file
View File

@ -0,0 +1,122 @@
---
title: Docker Compose installation
---
This installation method is for test setups and small-scale production setups.
## Requirements
- A host with at least 2 CPU cores and 2 GB of RAM
- Docker
- Docker Compose (Compose v2 is recommended, see [here](https://docs.docker.com/compose/migrate/) for instructions on how to upgrade)
## Video
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/O1qUbrk4Yc8?si=HiSBjmJYhE_oJhB1&amp;start=22"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowfullscreen
></iframe>
## Preparation
To download the latest `docker-compose.yml` open your terminal and navigate to the directory of your choice.
Run the following command:
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
{/* prettier-ignore */}
<Tabs groupId="OS">
<TabItem value="Linux" label="Linux" default>
```shell
wget https://goauthentik.io/docker-compose.yml
```
</TabItem>
<TabItem value="macOS" label="macOS">
```shell
curl -O https://goauthentik.io/docker-compose.yml
```
</TabItem>
</Tabs>
If this is a fresh authentik installation, you need to generate a password and a secret key. Use a secure password generator of your choice such as pwgen, or you can use `openssl` as below.
Run the following commands to generate a password and secret key and write them to your `.env` file:
{/* prettier-ignore */}
```shell
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
```
:::info
Because of a PostgreSQL limitation, only passwords up to 99 chars are supported. See: https://www.postgresql.org/message-id/09512C4F-8CB9-4021-B455-EF4C4F0D55A0@amazon.com
:::
To enable error reporting, run the following command:
```shell
echo "AUTHENTIK_ERROR_REPORTING__ENABLED=true" >> .env
```
## Email configuration (optional but recommended)
It is also recommended to configure global email credentials. These are used by authentik to notify you about alerts and configuration issues. They can also be used by [Email stages](../../add-secure-apps/flows-stages/stages/email/index.mdx) to send verification/recovery emails.
To configure email credentials, append this block to your `.env` file
```shell
# 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
```
## Configure for port 80/443
By default, authentik listens internally on port 9000 for HTTP and 9443 for HTTPS. To change the exposed ports to 80 and 443, you can set the following variables in `.env`:
```shell
COMPOSE_PORT_HTTP=80
COMPOSE_PORT_HTTPS=443
```
See [Configuration](../configuration/configuration.mdx) to change the internal ports. Be sure to run `docker compose up -d` to rebuild with the new port numbers.
## Startup
:::warning
The server assumes to have local timezone as UTC.
All internals are handled in UTC; whenever a time is displayed to the user in UI, the time shown is localized.
Do not update or mount `/etc/timezone` or `/etc/localtime` in the authentik containers.
This will not give any advantages. It will cause problems with OAuth and SAML authentication, e.g. [see this GitHub issue](https://github.com/goauthentik/authentik/issues/3005).
:::
Afterward, run these commands to finish:
```shell
docker compose pull
docker compose up -d
```
The `docker-compose.yml` file statically references the latest version available at the time of downloading the compose file. Each time you upgrade to a newer version of authentik, you download a new `docker-compose.yml` file, which points to the latest available version. For more information, refer to the **Upgrading** section in the [Release Notes](../../releases/).
To start the initial setup, navigate to `http://<your server's IP or hostname>:9000/if/flow/initial-setup/`.
There you are prompted to set a password for the `akadmin` user (the default user).
For an explanation about what each service in the docker compose file does, see [Architecture](../../core/architecture.md).

104
website/docs/install-config/install/kubernetes.md Normal file
View File

@ -0,0 +1,104 @@
---
title: Kubernetes installation
---
You can install authentik to run on Kubernetes using Helm Chart.
:::info
You can also [view a video walk-through](https://www.youtube.com/watch?v=O1qUbrk4Yc8) of the installation process on Kubernetes (with bonus details about email configuration and other important options).
:::
### Requirements
- Kubernetes
- Helm
## Video
<iframe width="560" height="315" src="https://www.youtube.com/embed/O1qUbrk4Yc8?si=hs-ZhbVk4Y-TW_Vw&amp;start=562" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
### Generate Passwords
Start by generating passwords for the database and cache. You can use either of the following commands:
```shell
pwgen -s 50 1
openssl rand 60 | base64 -w 0
```
### Set Values
Create a `values.yaml` file with a minimum of these settings:
```yaml
authentik:
secret_key: "PleaseGenerateASecureKey"
# This sends anonymous usage-data, stack traces on errors and
# performance data to sentry.io, and is fully opt-in
error_reporting:
enabled: true
postgresql:
password: "ThisIsNotASecurePassword"
server:
ingress:
# Specify kubernetes ingress controller class name
ingressClassName: nginx | traefik | kong
enabled: true
hosts:
- authentik.domain.tld
postgresql:
enabled: true
auth:
password: "ThisIsNotASecurePassword"
redis:
enabled: true
```
See all configurable values on [ArtifactHub](https://artifacthub.io/packages/helm/goauthentik/authentik).
### Install authentik Helm Chart
Now, execute the following commands to install authentik:
```shell
helm repo add authentik https://charts.goauthentik.io
helm repo update
helm upgrade --install authentik authentik/authentik -f values.yaml
```
During the installation process, the database migrations will be applied automatically on startup.
### Accessing authentik
After the installation is complete, access authentik at `https://<ingress-host-name>/if/flow/initial-setup/`. Here, you can set a password for the default `akadmin` user.
### Optional step: Configure global email credentials
It is recommended to configure global email credentials as well. These are used by authentik to notify you about alerts and configuration issues. Additionally, they can be utilized by [Email stages](../../add-secure-apps/flows-stages/stages/email/index.mdx) to send verification and recovery emails.
To configure this, append this block to your `values.yaml` file:
```yaml
# add this block under the `authentik:` block in your values.yaml file
# authentik:
email:
# -- SMTP Server emails are sent from, fully optional
host: ""
port: 587
# -- SMTP credentials. When left empty, no authentication will be done.
username: ""
# -- SMTP credentials. When left empty, no authentication will be done.
password: ""
# -- Enable either use_tls or use_ssl. They can't be enabled at the same time.
use_tls: false
# -- Enable either use_tls or use_ssl. They can't be enabled at the same time.
use_ssl: false
# -- Connection timeout in seconds
timeout: 30
# -- Email 'from' address can either be in the format "foo@bar.baz" or "authentik <foo@bar.baz>"
from: ""
```
By following these steps, you will successfully install and set up authentik on Kubernetes using Helm.

64
website/docs/install-config/reverse-proxy.md Normal file
View File

@ -0,0 +1,64 @@
---
title: Reverse-proxy
---
:::info
Since authentik uses WebSockets to communicate with Outposts, it does not support HTTP/1.0 reverse-proxies. The HTTP/1.0 specification does not officially support WebSockets or protocol upgrades, though some clients may allow it.
:::
If you want to access authentik behind a reverse proxy, there are a few headers that must be passed upstream:
- `X-Forwarded-Proto`: Tells authentik and Proxy Providers if they are being served over an HTTPS connection.
- `X-Forwarded-For`: Without this, authentik will not know the IP addresses of clients.
- `Host`: Required for various security checks, WebSocket handshake, and Outpost and Proxy Provider communication.
- `Connection: Upgrade` and `Upgrade: WebSocket`: Required to upgrade protocols for requests to the WebSocket endpoints under HTTP/1.1.
It is also recommended to use a [modern TLS configuration](https://ssl-config.mozilla.org/) and disable SSL/TLS protocols older than TLS 1.3.
The following nginx configuration can be used as a starting point for your own configuration.
```
# Upstream where your authentik server is hosted.
upstream authentik {
server <hostname of your authentik server>:9443;
# Improve performance by keeping some connections alive.
keepalive 10;
}
# Upgrade WebSocket if requested, otherwise use keepalive
map $http_upgrade $connection_upgrade_keepalive {
default upgrade;
'' '';
}
server {
# HTTP server config
listen 80;
listen [::]:80;
server_name sso.domain.tld;
# 301 redirect to HTTPS
return 301 https://$host$request_uri;
}
server {
# HTTPS server config
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name sso.domain.tld;
# TLS certificates
ssl_certificate /etc/letsencrypt/live/domain.tld/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/domain.tld/privkey.pem;
add_header Strict-Transport-Security "max-age=63072000" always;
# Proxy site
location / {
proxy_pass https://authentik;
proxy_http_version 1.1;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade_keepalive;
}
}
```

104
website/docs/install-config/storage-s3.md Normal file
View File

@ -0,0 +1,104 @@
---
title: S3 storage setup
---
### Preparation
First, create a user on your S3 storage provider and get access credentials for S3, hereafter referred as `access_key` and `secret_key`.
You will also need to know which endpoint authentik is going to use to access the S3 API, hereafter referred as `https://s3.provider`.
The bucket in which authentik is going to store files is going to be called `authentik-media`. You may need to change this name depending on your S3 provider limitations. Also, we are suffixing the bucket name with `-media` as authentik currently only stores media files, but may use other buckets in the future.
The domain used to access authentik is going to be referred to as `authentik.company`.
You will also need the AWS CLI.
### S3 configuration
#### Bucket creation
Create the bucket in which authentik is going to store files:
```bash
AWS_ACCESS_KEY_ID=access_key AWS_SECRET_ACCESS_KEY=secret_key aws s3api --endpoint-url=https://s3.provider create-bucket --bucket=authentik-media --acl=private
```
If using AWS S3, you can omit the `--endpoint-url` option, but may need to specify the `--region` option. If using Google Cloud Storage, refer to its documentation on how to create buckets.
The bucket ACL is set to private, although that is not strictly necessary, as an ACL associated with each object stored in the bucket will be private as well.
#### CORS policy
Next, associate a CORS policy to the bucket to allow the authentik web interface to show images stored in the bucket.
First, save the following file locally as `cors.json`:
```json
{
"CORSRules": [
{
"AllowedOrigins": ["authentik.company"],
"AllowedHeaders": ["Authorization"],
"AllowedMethods": ["GET"],
"MaxAgeSeconds": 3000
}
]
}
```
If authentik is accessed from multiple domains, you can add them to the `AllowedOrigins` list.
Apply that policy to the bucket:
```bash
AWS_ACCESS_KEY_ID=access_key AWS_SECRET_ACCESS_KEY=secret_key aws s3api --endpoint-url=https://s3.provider put-bucket-cors --bucket=authentik-media --cors-configuration=file://cors.json
```
### Configuring authentik
Add the following to your `.env` file:
```env
AUTHENTIK_STORAGE__MEDIA__BACKEND=s3
AUTHENTIK_STORAGE__MEDIA__S3__ACCESS_KEY=access_key
AUTHENTIK_STORAGE__MEDIA__S3__SECRET_KEY=secret_key
AUTHENTIK_STORAGE__MEDIA__S3__BUCKET_NAME=authentik-media
```
If you are using AWS S3 as your S3 provider, add the following:
```env
AUTHENTIK_STORAGE__MEDIA__S3__REGION=us-east-1 # Use the region of the bucket
```
If you are not using AWS S3 as your S3 provider, add the following:
```env
AUTHENTIK_STORAGE__MEDIA__S3__ENDPOINT=https://s3.provider
AUTHENTIK_STORAGE__MEDIA__S3__CUSTOM_DOMAIN=s3.provider/authentik-media
```
The `ENDPOINT` setting specifies how authentik talks to the S3 provider.
The `CUSTOM_DOMAIN` setting specifies how URLs are constructed to be shown on the web interface. For example, an object stored at `application-icons/application.png` with a `CUSTOM__DOMAIN` setting of `s3.provider/authentik-media` will result in a URL of `https://s3.provider/authentik-media/application-icons/application.png`. You can also use subdomains for your buckets depending on what your S3 provider offers: `authentik-media.s3.provider`. Whether HTTPS is used is controlled by `AUTHENTIK_STORAGE__MEDIA__S3__SECURE_URLS`, which defaults to true.
For more control over settings, refer to the [configuration reference](./configuration/configuration.mdx#media-storage-settings)
### Migrating between storage backends
The following section assumes that the local storage path is `/media` and the bucket name is `authentik-media`. It also assumes you have a working `aws` CLI that can interact with the bucket.
#### From file to s3
Follow the setup steps above, and then migrate the files from your local directory to s3:
```bash
aws s3 sync /media s3://authentik-media/media
```
#### From s3 to file
```bash
aws s3 sync s3://authentik-media/media /media
```

61
website/docs/install-config/upgrade.mdx Normal file
View File

@ -0,0 +1,61 @@
---
title: Upgrade authentik
---
Upgrading to the latest version of authentik, whether a new major release or a patch, involves running a few commands to pull down the latest images and then restarting the servers and databases.
## Important considerations
- Be sure to carefully read the [Release Notes](../releases/) for the specific version to which you plan to upgrade. The release might have special requirements or actions or contain breaking changes.
- Make a backup of your PostgreSQL database before upgrading. You can dump your existing database to get a backup file. For more information about dumping and backing up your database, refer to [Upgrade PostgreSQL on Docker Compose](../troubleshooting/postgres/upgrade_docker.md) or [Upgrade PostgreSQL on Kubernetes](../troubleshooting/postgres/upgrade_kubernetes.md).
- You need to upgrade in sequence of the major releases; do not skip directly from an older major version to the most recent version. For example, if you are currently running 2023.10.3, you will need to first upgrade to 2024.2.x, then 2024.4.x, and then 2024.6.x, in sequence.
- The version of the authentik instance and any outposts must be the same. We recommended that you always upgrade any outposts at the same time you upgrade your authentik instance.
## Upgrade authentik
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
<Tabs groupId="platform">
<TabItem value="docker-compose" label="Docker Compose" default>
In your terminal, navigate to your installation directory and follow these steps:
#### 1. Retrieve latest `docker-compose.yml` file
Download the `docker-compose.yml` file using either `wget -O docker-compose.yml https://goauthentik.io/docker-compose.yml` or `curl -O https://goauthentik.io/docker-compose.yml` or a similar process.
**2. Run upgrade commands**
```shell
docker compose pull
docker compose up -d
```
</TabItem>
<TabItem value="kubernetes" label="Kubernetes">
In your terminal, navigate to your installation directory and run the following commands:
```
helm repo update
helm upgrade --install authentik authentik/authentik -f values.yaml
```
</TabItem>
</Tabs>
## Verify your upgrade
You can view the current version of your authentik instance by logging in to the Admin interface, and then navigating to **Dashboards -> Overview**.
![](./version1.png)
## Troubleshooting your upgrade
If you run the upgrade commands but your version on the Dashboard doesn’t change, follow this steps:
1. Look at the server logs and search for an entry of `migration inconsistency`.
2. If you see this entry, revert to your database backup.
3. Now, upgrade to each subsequent higher version. That is, upgrade in sequence, do not skip directly to the most recent version.

BIN
website/docs/install-config/version1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB