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

website: latest PR for new Docs structure (#11639)

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

* Spelled out Documentation in menu bar

* remove image redirects...

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

* remove explicit index.md

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

* remove mdx first

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

* then remove .md

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

* add missing prefix

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

---------

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-09 09:33:40 -05:00
committed by GitHub
parent 6b2fced1b9
commit 6d5172d18a
336 changed files with 2138 additions and 872 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
website/docs/core/architecture.md
View File

@ -25,7 +25,7 @@ The core sub-component handles most of authentik's logic, such as API requests,
#### Embedded outpost
Similar to [other outposts](../outposts/index.mdx), this outpost allows using [Proxy providers](../providers/proxy/index.md) without deploying a separate outpost.
Similar to [other outposts](../add-secure-apps/outposts/index.mdx), this outpost allows using [Proxy providers](../add-secure-apps/providers/proxy/index.md) without deploying a separate outpost.
#### Persistence
@ -37,8 +37,8 @@ This container executes background tasks, such as sending emails, the event noti
#### Persistence
- `/certs` is used for authentik to import external certs, which in most cases shouldn't be used for SAML, but rather if you use authentik without a reverse proxy, this can be used for example for the [Let's Encrypt integration](../core/certificates.md#lets-encrypt)
- `/templates` is used for [custom email templates](../flow/stages/email/index.mdx#custom-templates), and as with the other ones fully optional
- `/certs` is used for authentik to import external certs, which in most cases shouldn't be used for SAML, but rather if you use authentik without a reverse proxy, this can be used for example for the [Let's Encrypt integration](../sys-mgmt/certificates.md#lets-encrypt)
- `/templates` is used for [custom email templates](../add-secure-apps/flows-stages/stages/email/index.mdx#custom-templates), and as with the other ones fully optional
### PostgreSQL

30
website/docs/core/brands.md
View File

@ -1,30 +0,0 @@
---
title: Brands
slug: /brands
---
You can configure several differently "branded" options depending on the associated domain, even though objects such as applications, providers, etc, are still global. This can be handy to use the same authentik instance, but branded differently for different domains.
The main settings that brands influence are flows and branding.
## Flows
authentik picks a default flow by selecting the flow that is configured in the current brand, otherwise any flow that:
- matches the required designation
- comes first sorted by slug
- is allowed by policies
This means that if you want to select a default flow based on policy, you can leave the brand default empty.
## Branding
The brand configuration controls the branding title (shown in website document title and several other places), the sidebar/header logo that appears in the upper left of the product interface, and the favicon on a browser tab.
:::info
Starting with authentik 2024.6.2, the placeholder `%(theme)s` can be used in the logo configuration option, which will be replaced with the active theme.
:::
## External user settings
You can use the **Default application** configuration on the **System -> Brands** page of the Admin interface to redirect external users to a default application when they successfully authenticate without being sent from a specific application.

103
website/docs/core/certificates.md
View File

@ -1,103 +0,0 @@
---
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.

107
website/docs/core/geoip.mdx
View File

@ -1,107 +0,0 @@
# GeoIP
authentik supports GeoIP to add additional information to login/authorization/enrollment requests. Additionally, a [GeoIP policy](../policies/#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>

70
website/docs/core/settings.md
View File

@ -1,70 +0,0 @@
---
title: System Settings
---
These settings are similar to the configuration options listed [here](../installation/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.

8
website/docs/core/terminology.md
View File

@ -45,7 +45,7 @@ A Provider is a way for other applications to authenticate against authentik. Co
At a base level a policy is a yes/no gate. It will either evaluate to True or False depending on the Policy Kind and settings. For example, a "Group Membership Policy" evaluates to True if the user is member of the specified Group and False if not. This can be used to conditionally apply Stages, grant/deny access to various objects, and for other custom logic.
See [Policies](../policies/index.md)
See [Policies](../customize/policies/index.md)
### Flows & Stages
@ -57,19 +57,19 @@ A stage represents a single verification or logic step. They are used to authent
Certain use cases within authentik add steps that are run as part of a flow. These steps are a special type of stage called the "Dynamic in-memory" stage, as they are added to flows dynamically when required, only exist in memory, and are thus not configurable by administrators.
See [Flows](../flow/index.md)
See [Flows](../add-secure-apps/flows-stages/flow/index.md)
### Property Mappings
Property Mappings allow you to make information available for external applications, and to modify how information from sources are stored in authentik. For example, if you want to log in to AWS with authentik, you'd use property mappings to set the user's roles in AWS based on their group memberships in authentik.
See [Providers Property Mappings](../providers/property-mappings/index.md) and [Source Property Mappings](../sources/property-mappings/index.md).
See [Providers Property Mappings](../add-secure-apps/providers/property-mappings/index.md) and [Source Property Mappings](../users-sources/sources/property-mappings/index.md).
### Outpost
An outpost is a separate component of authentik, which can be deployed anywhere, regardless of the authentik deployment. The outpost offers services that aren't implemented directly into the authentik core, e.g. Reverse Proxying.
See [Outposts](../outposts/index.mdx)
See [Outposts](../add-secure-apps/outposts/index.mdx)
### System tasks