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

103
website/docs/sys-mgmt/certificates.md Normal file
View File

@ -0,0 +1,103 @@
---
title: Certificates
---
Certificates in authentik are used for the following use cases:
- 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.
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 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.
For SAML use-cases, you can generate a Certificate that's valid for longer than 1 year, at your own risk.
## External certificates
To use externally managed certificates, for example generated with 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.
For Kubernetes, you can map custom secrets/volumes under `/certs`.
You can also bind mount single files into the folder, as long as they fall under this naming schema.
- Files in the root directory will be imported based on their filename.
`/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:
- Files containing `PRIVATE KEY` will imported as private keys.
- Otherwise the file will be imported as a certificate.
- 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).
```shell
certs/
├── baz
│   └── bar.baz
│   ├── fullchain.pem
│   └── privkey.pem
├── foo.bar
│   ├── 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.
#### Let's Encrypt
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)
```yaml
services:
certbot:
image: certbot/dns-route53:v1.22.0
volumes:
- ./certs/:/etc/letsencrypt
# Variables depending on DNS Plugin
environment:
AWS_ACCESS_KEY_ID: ...
command:
- certonly
- --non-interactive
- --agree-tos
- -m your.email@company
- -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).
Navigate to _System -> Brands_, edit any brand and select the certificate of your choice.
Keep in mind this certbot container will only run once, but there are a variety of ways to schedule regular renewals.

BIN
website/docs/sys-mgmt/events/event_matcher.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

318
website/docs/sys-mgmt/events/index.md Normal file
View File

@ -0,0 +1,318 @@
---
title: Events
---
Events are authentik's built-in logging system. Whenever any of the following actions occur, an event is created:
Certain information is stripped from events, to ensure no passwords or other credentials are saved in the log.
## Event retention
The event retention is configured in the system settings interface, with the default being set to 365 days.
If you want to forward these events to another application, forward the log output of all authentik containers. Every event creation is logged with the log level "info". For this configuration, it is also recommended to set the internal retention pretty low (for example, `days=1`).
## Event actions
### `login`
A user logs in (including the source, if available)
<details>
<summary>Example</summary>
```json
{
"pk": "f00f54e7-2b38-421f-bc78-e61f950048d6",
"user": {
"pk": 1,
"email": "root@localhost",
"username": "akadmin"
},
"action": "login",
"app": "authentik.events.signals",
"context": {
"auth_method": "password",
"http_request": {
"args": {
"query": "next=%2F"
},
"path": "/api/v3/flows/executor/default-authentication-flow/",
"method": "GET"
},
"auth_method_args": {}
},
"client_ip": "::1",
"created": "2023-02-15T15:33:42.771091Z",
"expires": "2024-02-15T15:33:42.770425Z",
"brand": {
"pk": "fcba828076b94dedb2d5a6b4c5556fa1",
"app": "authentik_brands",
"name": "Default brand",
"model_name": "brand"
}
}
```
</details>
### `login_failed`
A failed login attempt
<details>
<summary>Example</summary>
```json
{
"pk": "2779b173-eb2a-4c2b-a1a4-8283eda308d7",
"user": {
"pk": 2,
"email": "",
"username": "AnonymousUser"
},
"action": "login_failed",
"app": "authentik.events.signals",
"context": {
"stage": {
"pk": "7e88f4a991c442c1a1335d80f0827d7f",
"app": "authentik_stages_password",
"name": "default-authentication-password",
"model_name": "passwordstage"
},
"password": "********************",
"username": "akadmin",
"http_request": {
"args": {
"query": "next=%2F"
},
"path": "/api/v3/flows/executor/default-authentication-flow/",
"method": "POST"
}
},
"client_ip": "::1",
"created": "2023-02-15T15:32:55.319608Z",
"expires": "2024-02-15T15:32:55.314581Z",
"brand": {
"pk": "fcba828076b94dedb2d5a6b4c5556fa1",
"app": "authentik_brands",
"name": "Default brand",
"model_name": "brand"
}
}
```
</details>
### `logout`
A user logs out.
<details>
<summary>Example</summary>
```json
{
"pk": "474ffb6b-77e3-401c-b681-7d618962440f",
"user": {
"pk": 1,
"email": "root@localhost",
"username": "akadmin"
},
"action": "logout",
"app": "authentik.events.signals",
"context": {
"http_request": {
"args": {
"query": ""
},
"path": "/api/v3/flows/executor/default-invalidation-flow/",
"method": "GET"
}
},
"client_ip": "::1",
"created": "2023-02-15T15:39:55.976243Z",
"expires": "2024-02-15T15:39:55.975535Z",
"brand": {
"pk": "fcba828076b94dedb2d5a6b4c5556fa1",
"app": "authentik_brands",
"name": "Default brand",
"model_name": "brand"
}
}
```
</details>
### `user_write`
A user is written to during a flow execution.
<details>
<summary>Example</summary>
```json
{
"pk": "d012e8af-cb94-4fa2-9e92-961e4eebc060",
"user": {
"pk": 1,
"email": "root@localhost",
"username": "akadmin"
},
"action": "user_write",
"app": "authentik.events.signals",
"context": {
"name": "authentik Default Admin",
"email": "root@localhost",
"created": false,
"username": "akadmin",
"attributes": {
"settings": {
"locale": ""
}
},
"http_request": {
"args": {
"query": ""
},
"path": "/api/v3/flows/executor/default-user-settings-flow/",
"method": "GET"
}
},
"client_ip": "::1",
"created": "2023-02-15T15:41:18.411017Z",
"expires": "2024-02-15T15:41:18.410276Z",
"brand": {
"pk": "fcba828076b94dedb2d5a6b4c5556fa1",
"app": "authentik_brands",
"name": "Default brand",
"model_name": "brand"
}
}
```
</details>
### `suspicious_request`
A suspicious request has been received (for example, a revoked token was used).
### `password_set`
A user sets their password.
### `secret_view`
A user views a token's/certificate's data.
### `secret_rotate`
A token was rotated automatically by authentik.
### `invitation_used`
An invitation is used.
### `authorize_application`
A user authorizes an application.
<details>
<summary>Example</summary>
```json
{
"pk": "f52f9eb9-dc2a-4f1e-afea-ad5af90bf680",
"user": {
"pk": 1,
"email": "root@localhost",
"username": "akadmin"
},
"action": "authorize_application",
"app": "authentik.providers.oauth2.views.authorize",
"context": {
"asn": {
"asn": 6805,
"as_org": "Telefonica Germany",
"network": "5.4.0.0/14"
},
"geo": {
"lat": 42.0,
"city": "placeholder",
"long": 42.0,
"country": "placeholder",
"continent": "placeholder"
},
"flow": "53287faa8a644b6cb124cb602a84282f",
"scopes": "ak_proxy profile openid email",
"http_request": {
"args": {
"query": "[...]"
},
"path": "/api/v3/flows/executor/default-provider-authorization-implicit-consent/",
"method": "GET"
},
"authorized_application": {
"pk": "bed6a2495fdc4b2e8c3f93cb2ed7e021",
"app": "authentik_core",
"name": "Alertmanager",
"model_name": "application"
}
},
"client_ip": "::1",
"created": "2023-02-15T10:02:48.615499Z",
"expires": "2023-04-26T10:02:48.612809Z",
"brand": {
"pk": "10800be643d44842ab9d97cb5f898ce9",
"app": "authentik_brands",
"name": "Default brand",
"model_name": "brand"
}
}
```
</details>
### `source_linked`
A user links a source to their account
### `impersonation_started` / `impersonation_ended`
A user starts/ends impersonation, including the user that was impersonated
### `policy_execution`
A policy is executed (when a policy has "Execution Logging" enabled).
### `policy_exception` / `property_mapping_exception`
A policy or property mapping causes an exception
### `system_task_exception`
An exception occurred in a system task.
### `system_exception`
A general exception in authentik occurred.
### `configuration_error`
A configuration error occurs, for example during the authorization of an application
### `model_created` / `model_updated` / `model_deleted`
Logged when any model is created/updated/deleted, including the user that sent the request.
:::info
Starting with authentik 2024.2, when a valid enterprise license is installed, these entries will contain additional audit data, including which fields were changed with this event, their previous values and their new values.
:::
### `email_sent`
An email has been sent. Included is the email that was sent.
### `update_available`
An update is available

41
website/docs/sys-mgmt/events/notifications.md Normal file
View File

@ -0,0 +1,41 @@
---
title: Notifications
---
:::note
To prevent infinite loops (events created by policies which are attached to a Notification rule), **any events created by a policy which is attached to any Notification Rules do not trigger notifications.**
:::
## Filtering Events
Starting with authentik 0.15, you can create notification rules, which can alert you based on the creation of certain events.
Filtering is done by using the Policy Engine. You can do simple filtering using the "Event Matcher Policy" type.
![](./event_matcher.png)
An event has to match all configured fields, otherwise the rule will not trigger.
To match events with an "Expression Policy", you can write code like so:
```python
if "event" not in request.context:
return False
return ip_address(request.context["event"].client_ip) in ip_network('192.0.2.0/24')
```
## Selecting who gets notified
After you've created the policies to match the events you want, create a "Notification Rule".
You have to select which group the generated notification should be sent to. If left empty, the rule will be disabled.
:::info
Before authentik 2023.5, when no group is selected, policies bound to the rule are not executed. Starting with authentik 2023.5, policies are executed even when no group is selected.
:::
You also have to select which transports should be used to send the notification.
A transport with the name "default-email-transport" is created by default. This transport will use the [global email configuration](../../install-config/install/docker-compose.mdx#email-configuration-optional-but-recommended).
Starting with authentik 2022.6, a new default transport will be created. This is because notifications are no longer created by default, they are now a transport method instead. This allows for better customization of the notification before it is created.

36
website/docs/sys-mgmt/events/transports.md Normal file
View File

@ -0,0 +1,36 @@
---
title: Transports
---
Notifications can be sent to users via multiple mediums. By default, the [global email configuration](../../install-config/install/docker-compose.mdx#email-configuration-optional-but-recommended) will be used.
## Generic Webhook
This will send a POST request to the given URL with the following contents:
```json
{
"body": "body of the notification message",
"severity": "severity level as configured in the trigger",
// User that the notification was created for, i.e. a member of the group selected in the rule
"user_email": "notification user's email",
"user_username": "notification user's username",
// User that created the event
"event_user_email": "event user's email",
"event_user_username": "event user's username"
}
```
The `Content-Type` header is set to `text/json`.
Starting in 2021.9, you can also select a Notification mapping. This allows you to freely configure the request's payload. For example:
```python
return {
"foo": request.context['notification'].body,
}
```
## Slack Webhook
This sends a request using the Slack-specific format. This is also compatible with Discord's webhooks by appending `/slack` to the Discord webhook URL.

29
website/docs/sys-mgmt/ops/monitoring.md Normal file
View File

@ -0,0 +1,29 @@
---
title: Monitoring
---
authentik can be easily monitored in multiple ways.
## Server monitoring
Configure your monitoring software to send requests to `/-/health/live/`, which will return a `HTTP 200` response as long as authentik is running. You can also send HTTP requests to `/-/health/ready/`, which will return `HTTP 200` if both PostgreSQL and Redis connections can be/have been established correctly.
## Worker monitoring
The worker container can be monitored by running `ak healthcheck` in the worker container. This will ping the worker and ensure it can communicate with redis as required.
## Outpost monitoring
Both kinds of outpost (proxy and LDAP) listen on a separate port (9300) and can be monitored by sending HTTP requests to `/outpost.goauthentik.io/ping`.
---
Both Docker Compose and Kubernetes deployments use these methods by default to determine when authentik is ready after starting, and to only route traffic to healthy instances; unhealthy instances are restarted.
## Metrics
Both the core authentik server and any outposts expose Prometheus metrics on a separate port (9300), which can be scraped to gather further insight into authentik's state. The metrics require no authentication, as they are hosted on a separate, non-exposed port by default.
You can find an example dashboard here: [grafana.com](https://grafana.com/grafana/dashboards/14837-authentik/)
![](../../install-config/dashboard.png)

70
website/docs/sys-mgmt/settings.md Normal file
View File

@ -0,0 +1,70 @@
---
title: System Settings
---
These settings are similar to the configuration options listed [here](../install-config/configuration/configuration.mdx), however they can only be adjusted through the authentik Admin interface or API.
### Avatars
Configure how authentik should show avatars for users. Following values can be set:
Default: `gravatar,initials`
- `none`: Disables per-user avatars and just shows a 1x1 pixel transparent picture
- `gravatar`: Uses gravatar with the user's email address
- `initials`: Generated avatars based on the user's name
- Any URL: If you want to use images hosted on another server, you can set any URL.
Additionally, these placeholders can be used:
- `%(username)s`: The user's username
- `%(mail_hash)s`: The email address, md5 hashed
- `%(upn)s`: The user's UPN, if set (otherwise an empty string)
You can also use an attribute path like `attributes.something.avatar`, which can be used in combination with the file field to allow users to upload custom avatars for themselves.
Multiple modes can be set, and authentik will fallback to the next mode when no avatar could be found. For example, setting this to `gravatar,initials` will attempt to get an avatar from Gravatar, and if the user has not configured on there, it will fallback to a generated avatar.
### Allow users to change name
Enable the ability for users to change their name, defaults to `true`.
### Allow users to change email
Enable the ability for users to change their Email address, defaults to `false`.
### Allow users to change username
Enable the ability for users to change their Usernames, defaults to `false`.
### Event retention
Configure how long [Events](./events/index.md) are retained for within authentik. Default value is `days=365`. When forwarding events to an external application, this value can be decreased. When changing this value, only new events are affected.
### Footer links
This option configures the footer links on the flow executor pages.
The setting can be used as follows:
```json
[{ "name": "Link Name", "href": "https://goauthentik.io" }]
```
Starting with authentik 2024.6.1, the `href` attribute is optional, and this option can be used to add additional text to the flow executor pages.
### GDPR compliance
When enabled, all the events caused by a user will be deleted upon the user's deletion. Defaults to `true`.
### Impersonation
Globally enable/disable impersonation. Defaults to `true`.
### Default token duration
Default duration for generated tokens. Defaults to `minutes=30`.
### Default token length
Default length of generated tokens. Defaults to 60.

77
website/docs/sys-mgmt/tenancy.md Normal file
View File

@ -0,0 +1,77 @@
---
title: Tenancy
---
<span class="badge badge--primary">Enterprise</span>
---
::::warning
This feature is in alpha. Use at your own risk.
::::
::::info
This feature is available from 2024.2 and is not to be confused with [brands](../customize/brands.md), which were previously called tenants.
::::
## About tenants
Starting with version 2024.2, authentik allows an administrator or operator to create multiple tenants. This means that an operator can manage several different and distinct authentik installations, each with it's own Install ID and license(s). The relationships between tenant and installation (Install ID) is a 1:1 relationship, so for each tenant, there is a unique Install ID.
::::danger
Expression policies currently have access to all tenants.
::::
The data for each tenant is stored in a separate PostgreSQL schema, providing full separation of user data. License data for the tenant is also stored in the schema.
Note that creating and managing multiple tenants is handled using authentik APIs, not in the Admin interface. For typical authentik installations in which only a single tenant is needed, the default tenant is automatically created by authentik, and does not need to be managed in the Admin interface.
### Licensing
For each additional tenant (beyond the default one), one or more licenses is required; a license key cannot be used for more than one tenant. Note that the license for the default tenant must be valid and up-to-date in order to create additional tenants.
A single tenant and its corresponding installation can have multiple license keys. For example, a company might purchase one license for 50 users, and then later in the same year need to buy another license for 50 more users, due to company growth. Both licenses are associated to the one installation, the one tenant.
Learn more in our documentation about [Enterprise licenses](../enterprise/manage-enterprise.md#license-management).
### Important considerations
- Upon creating another tenant, a new schema will be created by cloning the `template` schema. This special schema is like a tenant with no data created in it. Cloning an existing schema instead of creating a new one and running migrations on it is done for efficiency purposes.
- In a typical deployment, all data stored in Redis (such as tasks, locks, and cached objects) will have its keys prefixed by the `schema_name`.
- Files are isolated on a per-tenant basis, with each tenant folder named according to the schema_name. For example, `/media/t_example`. The same is true regardless of the storage backend.
- Using an [embedded outpost](../add-secure-apps/outposts/embedded/embedded.mdx) with multi-tenancy is not currently supported. Disable the embedded outpost with `AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true` configuration setting.
## Usage
To create one or more additional tenants (beyond the default tenant) use the following instructions.
### 1. Configure authentik to allow multiple tenants
First, enable the multi-tenancy feature with the `AUTHENTIK_TENANTS__ENABLED=true` [configuration setting](../install-config/configuration/configuration.mdx).
Next, set `AUTHENTIK_TENANTS__API_KEY` to a random string. This string will be used to authenticate to the tenancy API. This key allows the creation of recovery keys for every tenant hosted by authentik, so be sure to _store it securely_. Be aware that creating a recovery key allows access to all data stored inside a tenant.
Be sure to disable the embedded outpost with `AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true` because it is not supported with tenants.
### 2. Create a new tenant with authentik API endpoints
Tenants are created using the API routes associated. Search for `tenant` in the [API browser](../developer-docs/api/reference/authentik) for the available endpoints.
When creating a tenant you must specify a `name`, used for display purposes, and a `schema_name`, used to create the PostgreSQL schema associated with the tenant.
:::info
The `schema_name` must start with `t_` and not be more than 64 characters long.
:::
There is always at least one tenant, `public`. This is the default tenant and cannot be deleted. Despite its name, it is not freely available to the world. Instead, it is stored in the `public` schema of the PostgreSQL database.
### 3. Associate the new tenant with a domain
By default, all requests that do not explicitly belong to a tenant are redirected to the default tenant. Thus, after creating a tenant, you must associate a domain for which incoming requests will be redirected to said tenant.
You can do so with API endpoints. After creating a domain `example.org` that is associated to the tenant `t_example`, all requests made to `example.org` will use the `t_example` tenant. However, requests made to `authentik.tld`, `subdomain.example.org` and any other domain that is not associated with the `t_example` tenant will use the default tenant.
In summary, if you access a domain that is not explicitly associated with a specific tenant, it will be routed to the default tenant.