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

website: Flesh out docs split.

Browse Source 
website: Copy files during build.

website: Allow for mixed env builds.

website: Reduce build size.

website: Expose build.

website: Add build memory debugging.

WIP: Disable broken links check to compare memory usage.

website: Update deps.

website: Clean up API paths.

website: Flesh out 3.8 fixes.

Format.

website: Update ignore paths.

Website: Clean up integrations build.

website: Fix paths.

website: Optimize remark.

website: Update deps.

website: Format.

website: Remove linking.

website: Fix paths.

wip: Attempt API only build.

Prep.

Migrate render to runtime. Tidy sidebar.

Clean up templates.

docs: Move directory. WIP

docs: Flesh out split.

website: Fix issue where routes have collisions.
This commit is contained in:
Teffen Ellis
2025-06-17 21:02:38 +02:00
parent b10c795a26
commit 582812b3ec
704 changed files with 5179 additions and 4670 deletions
Download Patch File Download Diff File Expand all files Collapse all files

431
docs/topics/developer-docs/docs/style-guide.mdx Normal file
View File

@ -0,0 +1,431 @@
---
title: Style Guide
---
This Style Guide provides guidelines to ensure that the authentik documentation is consistent, clear, and easy to follow. It standardizes aspects like phrasing, formatting, tone, and structure across all documentation.
We appreciate all contributions to our documentation — whether it's fixing a typo, adding new content, or writing an entirely new topic. To help us review and merge your contributions more efficiently, please follow our [writing documentation](./writing-documentation.md) guidelines. If you notice any inconsistencies, feel free to open an [Issue](https://github.com/goauthentik/authentik/issues) or submit a [Pull Request](https://github.com/goauthentik/authentik/pulls) to fix them.
- [General Style Guidelines](#general-style-guidelines)
- [Terminology](#terminology)
- [Writing Style](#writing-style)
- [Word Choices](#word-choices)
- [Formatting Guidelines](#formatting-guidelines)
- [Component-Based Formatting](#component-based-formatting)
- [Error Message Formatting and Troubleshooting](#error-message-formatting-and-troubleshooting)
- [Accessibility Best Practices](#accessibility-best-practices)
- [Notes and Warnings](#notes-and-warnings)
- [Inclusive Language](#inclusive-language)
- [Images and Media](#images-and-media)
- [Document Structure and Metadata](#document-structure-and-metadata)
---
## General style guidelines
### Logical order
- Documentation should be structured to follow the natural order of tasks, making it easier for users to follow. Organize sections in a manner that reflects the actual workflow used to complete tasks.
- When writing procedural documentation (How Tos) the steps should follow the workflow in the UI, specifying the exact pages to navigate and the precise fields, tabs, etc., to select or complete. Present the UI components in the document in the same order they appear in the UI.
### Headings
Use headings (sub-titles) to break up large blocks of text, making it easier for users to navigate the content and find specific sections quickly.
### Look and feel of the docs
In general, the visual, aesthetics of the technical documentation is intended to be lean and clean. Both the content (shorter sentences, concise instructions, etc) and the layout strive to have a clean, uncluttered look, with restrained use of colors and large callouts or announcements. Relatedly, the colors used for our Info and Warning callouts, light blue and light yellow respectively, are reserved for those purposes only.
### Cross-references
Always include cross-references to related content. If a concept is referenced elsewhere in the documentation, link to the relevant section to provide users with additional context or instructions.
### Relative vs. absolute paths
Use relative paths when linking to other documentation files. This will ensure links are automatically updated if file paths change in the future. If you are linking between another authentik resource that is not in the same repository and our regular technical docs, then use an absolute path.
### Markdown file type
The standard file type for documentation is `.md`. Use `.mdx` only if React components, such as interactive elements, are required.
### OS-agnostic, clarify where needed
Try to write procedural (How To) docs generically enough that it does not endorse or force a specific operating system. If it is necessary to specify a specific OS be sure to label it clearly. Consider using tabs (with MDX) to show the different OSes.
---
## Terminology
### authentik product name and terms
- The product name **authentik** should always be written with a lowercase "a" and a "k" at the end, even if it begins a sentence.
- The company name is **Authentik Security, Inc.**, but for non-legal documentation, you may shorten it to **Authentik Security**.
- When referring to the authentik Admin interface, capitalize "Admin" like it is in the UI, but do not bold the phrase "Admin interface" unless in a sentence that explicitly says "Click on **Admin interface**". However, if you are referring to a user or role that is an administrator, or has administrative rights, then do not capitalize it and spell out the full word "administrator" or "administrative".
### Industry terms and technology names
- When referring to external tools or industry terms, always use the exact capitalization and naming conventions that the product or company uses. Refer to their website or official documentation for the proper formatting. For example, use "OAuth", "SAML", or "Docker" as per the official conventions.
- Avoid abbreviations unless they are well-known and widely recognized (e.g., SSO, MFA, RBAC).
- If an acronym is used less frequently, spell out its full meaning when first mentioned on the page, followed by the acronym in parentheses. In some cases the acronym can come first, followed by the full term in parentheses.
### Trademarks and Legal Terms
- Respect third-party trademarks. Use the correct symbols (™, ®) where applicable (e.g., "GitHub®", "Okta™") in the _first_ instance of the name.
- When mentioning third-party products, follow their branding guidelines (e.g., "GitHub", not "Github").
- Where appropriate, include required legal disclaimers when referencing external services or integrations.
---
## Writing style
### Tone
The tone of the authentik documentation should be friendly but professional. It should be approachable, yet not overly casual. When appropriate, address the reader directly using second-person pronouns (e.g., "Next, you need to configure the login settings").
### Language
The documentation uses **American English** spelling conventions (e.g., "customize" instead of "customise").
### Voice
Use **active voice** and **present tense** for clear, direct communication.
- **DON'T:** "The Applications page will be loaded."
- **DO:** "The Applications page displays."
### User-friendly phrasing
Avoid phrasing that blames the user. Be subjective and polite when providing instructions.
- **DON'T:** "Never modify the default file."
- **DO:** "We recommend that you do not modify the default file, as doing so may result in unexpected issues."
### Punctuation
For Ken's sake, and many others, try to not use too many commas (avoid commaitis). Use a comma when needed to separate clauses, or for "slowing the pace" or clarity. Please **do** use the [Serial comma](https://en.wikipedia.org/wiki/Serial_comma) (also known as the Oxford comma).
In [lists](#lists), add a period at the end of a bulleted item if it is a complete sentence. Try not to mix incomplete and complete sentences in the same list.
### Capitalization
#### Titles and headers
Titles and headers (H1, H2, H3, etc.) should follow **sentence case capitalization**, meaning only the first word is capitalized, except for proper nouns or product names. For more information, see [below](#titles-and-headers).
#### Following a colon
Whether to capitalize after a colon depends on the context. Typically, we do not capitalize the first word after a colon _unless_ it's a proper noun or if it is the start of a complete sentence. If the colon introduces a list, do not capitalize the first word unless it's a proper noun. In headings and titles, capitalize the first word after the colon.
---
## Word choices
### "May" versus "Might" versus "Can"
- Typically, avoid using the word "may" in technical writing, as it implies permission rather than ability to perform an action. Instead, use **"can"** to suggest possibility.
- **"Might"** should be used to indicate that something could happen under certain conditions, but use it sparingly. It implies unpredictability, which can be undesirable in software documentation.
- **DON'T:** "You may use an Expression policy to enforce MFA adherence."
- **DO:** "You can use an Expression policy to enforce MFA adherence."
- **DO:** "Values might differ depending on the source of the property mappings."
### "Login", "Log in", and "Log in to"
- As a noun or descriptive term, use **login** (e.g., "The login panel").
- As a verb, use **"log in"** (e.g., "This stage prompts the user to log in").
- As a verb followed by the proposition **"to"**, use **"log in to"** (e.g., "Log in to the application").
### Use "that" as a conjunction
It's important to use "that" as a conjunction to introduce a dependent clause, or as a "connection" between a noun and a verb ("The provider that you created in Step 3."). Including "that" as a conjunction helps non-native English speakers more easily parse phrases, and improves output for translation tools.
- **DO:** "Ensure that the new user's password is valid."
- **DON'T:** "Ensure the new user's password is valid."
### "which" vs "that"
The easiest way to remember when to use "which" versus "that" is:
- If the second part (clause) of the sentence is required to understand the first part, use "that." If the second clause is only additional info, use "which".
For more information, see [this guide](https://www.grammarly.com/blog/which-vs-that/).
### "since" (time-based) vs "because" (causal)
When writing about a status or anything that is causal ("this happened because of that"), use the word "because". Use the word "since" for time-based topics (this will be rare in technical writing).
### Avoid using "once" (numeric) to mean "after" (time-based).
When writing out steps in a procedural topic, avoid starting with "Once...". Instead, you can say "After you have created the scope mapping...".
---
## Formatting guidelines
### Fonts and font styling
- When referring to internal components in authentik, like the policy engine, or blueprints, do not use any special formatting, and do not capitalize. Link to the relevant documentation when possible.
- When referring to authentik functionality and features, such as flows, stages, sources, or policies, do not capitalize and do not use bold or italic text. When possible link to the corresponding documentation.
- Use **bold** to highlight:
- UI elements such as field names, labels, buttons, or options (e.g., **Save** button, **Username** field).
- Key actions in instructions (e.g., **Click Next**).
- Use _italic_ for:
- Emphasis, but sparingly, to avoid overuse. For example, you can use italics for important terms or concepts on first mention in a section. Do not use italics to indicate a variable or placeholder; instead use angle brackets as described under [Variables](#variables).
- Use `code formatting` for:
- Commands (e.g., `kubectl get nodes`).
- File paths, file names, and directory names (e.g., `/usr/local/bin/`).
- Inline code snippets (e.g., `.env`).
### Lists
Add a period at the end of a bulleted item if it is a complete sentence. Try not to mix incomplete and complete sentences in the same list.
If there is a [colon](#following-a-colon) used in a bulleted list item, follow the capitalization rules.
### URLs
- When mentioning URLs in text or within procedural instructions, omit code formatting. For instance: "In your browser, go to https://example.com."
- For URLs entered as values or defined in fields, enclose any variables inside angle brackets (`< >`) and use underscores between words. See more about variables below (#variables).
### Variables
To clearly indicate terms or values that are placeholders and require user input, enclose any variables inside angle brackets (`< >`) and use underscores between words to clearly indicate that these are placeholders that require user input.
Examples:
`https://authentik.company/application/o/<slug>/.well-known/openid-configuration`
"Add the configuration setting: `<first_name>`."
### Titles and headers
- Titles and headers (H1, H2, H3) should follow **sentence case capitalization**, meaning only the first word is capitalized, except for proper nouns or product names.
- **DO:** "Configure the Google Workspace provider"
- **DON'T:** "CONFIGURE THE GOOGLE WORKSPACE PROVIDER"
- **DON'T:** "Configure The Google Workspace Provider"
- Ensure that titles and headers are descriptive and clearly convey the purpose of the section. Avoid vague titles like "Overview." Instead, opt for something more specific, like "About authentik policies."
- Use the **imperative verb form** in procedural topics, not gerunds. For example, use "Configure your instance" instead of "Configuring your instance."
### Examples
When you want to show an example (say, a code snippet), start on a new line, use bold text for the word "Example", and a colon, like this:
**Example**:
This expression policy uses an expression based on the user's name:
```python
if request.context["pending_user"].username == "marie":
return True
return False
```
### Code blocks
When you want to show sections of code use **Code blocks** to provide syntax highlighting, a copy button, line numbering and line highlighting:
```text
` ` ` yaml showLineNumbers {5} title="/etc/wazuh-indexer/opensearch-security/roles_mapping.yml"
all_access:
reserved: true
hidden: false
backend_roles:
- "wazuh-admin"
- "admin"
hosts: []
users: []
and_backend_roles: []
description: "Maps admin to all_access"
` ` `
```
Which is rendered as:
```yaml showLineNumbers {5} title="/etc/wazuh-indexer/opensearch-security/roles_mapping.yml"
all_access:
reserved: true
hidden: false
backend_roles:
- "wazuh-admin"
- "admin"
hosts: []
users: []
and_backend_roles: []
description: "Maps admin to all_access"
```
- ` ` ` `yaml `defines the language used for syntax highlighting. Other languages can be used such as`jsx`, `python`, `bash`, and `text`.
Optional configurations:
- `showLineNumbers`: enables line numbering.
- `title=" "`: defines the title displayed at the top (e.g., filenames).
- `{5}`: highlights specific lines. Ranges and lists are allowed (e.g., `{5, 7, 9-11}`).
- `// highlight-next-line`: highlights the next line within a code block.
- `// highlight-start` and `// highlight-end`: highlight multiple lines.
For more details, see the [Docusaurus code block documentation](https://docusaurus.io/docs/markdown-features/code-blocks).
### Tables
Use tables to compare options, list parameters, or summarize information. Ensure tables are concise and avoid nesting complex content. Only use a table when there are 4 or more items. For only 2 or 3 items, use a bullet list.
### Lists
- Use bullet points for unordered lists.
- Use numbered lists for sequential steps.
- Keep list items parallel in structure.
---
## Component-based formatting
### Tabs for multiple configurations
Use **Tabs** to display different configurations (e.g., setting up authentication with OIDC vs. SAML) to help users navigate between options. Default to the easier or more common option. For example:
```jsx
import TabItem from "@theme/TabItem";
import Tabs from "@theme/Tabs";
<Tabs
defaultValue="oidc"
values={[
{ label: "OIDC", value: "oidc" },
{ label: "SAML", value: "saml" },
]}
>
<TabItem value="oidc">OIDC configuration details go here.</TabItem>
<TabItem value="saml">SAML configuration details go here.</TabItem>
</Tabs>;
```
---
## Error message formatting and troubleshooting
When documenting errors, follow this structure:
1. **Error Message**: Display the error in a code block.
2. **Possible Causes**: List common reasons for the error.
3. **Solutions**: Provide step-by-step fixes or a work-around if there is one.
**Example**:
- **Error message**:
```sh
Error: Authentication failed. Invalid credentials.
```
- **Possible causes**:
- Incorrect username or password.
- Account locked due to multiple failed attempts.
- **Solutions**:
- Verify your credentials.
- Reset your password using the **Forgot Password** link.
- Contact your administrator if the account is locked.
---
## Accessibility best practices
- **Alt text for images**: Describe the purpose of the image, not just its appearance. For example, use "Screenshot of the login form" instead of "Image of a form."
- **Heading hierarchy**: Use headings in order (H1 → H2 → H3) to support screen readers.
- **Color usage**: Avoid using color as the sole method of conveying information (e.g., "Click the red button"). Instead, use descriptive labels to ensure accessibility.
- **Descriptive link text**: Provide descriptive link text. Avoid using generic terms like "Click here". Be specific about where the link will take the user.
- **DON'T:** "Click here."
- **DO:** "See the [Authentication Settings](/) for more details."
---
## Notes and warnings
Use the following components to highlight important information:
**Info notes**:
```md
:::info
This is a tip or general note.
:::
```
**Warnings**:
```md
:::warning
This level is for more serious situations: an action cannot be undone, a process might be canceled, etc..
:::
```
**Critical warnings** (for irreversible actions):
```md
:::danger
This level is for extremely serious situations, such as an action permanently removing data.
:::
```
---
## Inclusive Language
- Use **gender-neutral pronouns** like "they/them" instead of "he/she" (e.g., "The user should check their settings").
- Avoid **ableist terms** such as "dumb" or "lame"; use "non-functional" or "unavailable" instead.
- **Avoid idioms** that may not translate well (e.g., instead of "hit a home run" use "achieve success").
---
## Images and Media
- **Screenshots**:
- Use screenshots very sparingly, only for very complex UIs. If there are screenshots, update any existing ones if the UI changes.
- Crop to focus on relevant elements, use red arrows or circles to call out the important element.
- Add descriptive alt text (e.g., "Screenshot of the Provider configuration page").
- **Diagrams**:
- Use [Mermaid](https://mermaid.js.org/) for creating diagrams directly in markdown. Mermaid is our preferred tool for documentation diagrams as it allows for version control and easy updates.
- For more complex diagrams, you can use tools like [Draw.io](https://draw.io). Ensure high contrast and text descriptions.
---
## Document Structure and Metadata
- **Front matter**: Include a title and optional summary. You can also add badge metadata in the front matter:
```md
---
title: Getting Started
description: Install and configure authentik in 5 minutes.
authentik_version: "2025.4" # Semantic version when feature was introduced (Optional)
authentik_preview: true # For preview features (Optional)
authentik_enterprise: true # For enterprise features (Optional)
support_level: "authentik" # For integrations: Support level: "authentik" (tested by team) or "community" (community maintained)
---
```
Note: Badges should be defined in the front matter, not in the markdown content. The system will automatically display the appropriate badges based on the front matter metadata.
- **Directives**: You can also use directives in your markdown content to add badges inline:
- `:ak-version[2025.4]` - Shows when a feature was introduced (requires semantic version)
- `:ak-preview` - Indicates preview features
- `:ak-enterprise` - Indicates features in our Enterprise offering
Example usage in a heading:
```md
# New Feature :ak-version[2025.4] :ak-preview
```
Note: When using directives, they should be placed at the end of the heading or paragraph where they apply.
- **SEO**: Use keywords in titles and headings to improve searchability. Include relevant terms that users might search for, but avoid keyword stuffing. Focus on natural, descriptive language that accurately represents the content.

55
docs/topics/developer-docs/docs/templates/combo.md vendored Normal file
View File

@ -0,0 +1,55 @@
---
title: "Combination topic"
---
:::info
**How to use this template**: start with the markdown version of the template, either by copying the [`combo.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/docs/developer-docs/docs/templates) file from our GitHub repo or downloading the template file using the following command:
```
wget https://raw.githubusercontent.com/goauthentik/authentik/main/docs/developer-docs/docs/templates/combo.tmpl.md
```
Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
:::
For a combo topic, the title is typically the name of the feature ("Branding" or "Remote Access Control").
In this first section, right after the title but with no header, write one or two sentences about the task. Keep it brief, just an overview.
## About feature XYZ
In this section, go into a deeper explanation of the feature, provide typical use cases, etc.
### More info about the feature, a sub-category of info
Use this section if there are several big topics or categories of info that the reader needs to know about the feature or task. Add as many of these sections as needed.
## Prerequisites (optional section)
In this section, inform the reader of anything they need to do, or have configured or installed, before they start following the procedural instructions below.
## Overview of steps/workflow (optional section)
If the task is quite long or complex, it might be good to add a bullet list of the main steps, or even a diagram of the workflow, just so that the reader can first familiarize themselves with the 50,000 meter view before they dive into the detailed steps.
## First several group steps
If the task involves a lot of steps, try to group them into similar steps and have a Head3 or Head4 title for each group.
In this section, help the reader get oriented... where do they need to be (i.e. in the GUI, on a CLI, etc).
Have a separate paragraph for each step.
_Start instructions with the desired goal_, followed by the instructions. For example, in this sentence: "To define a new port number, navigate to the Admin interface, and then to the **Settings** tab." we first read the goal (to define a new port) and then we see the instructions.
## Next step of grouped steps (if a second group is needed)
Continue with the steps...
Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words.
Provide as many code snippets and examples as needed.
## Verify the steps
Use a heading such as "Verify your installation" or "Verify successful configuration". Whenever possible, it is useful to add verification steps at the end of a procedural topic. For example, if the procedural was about installing a product, use this section to tell them how they can verify that the install was successful.

43
docs/topics/developer-docs/docs/templates/combo.tmpl.md vendored Normal file
View File

@ -0,0 +1,43 @@
---
title: "Markdown template: combo"
---
add brief description of the feature/functionality
## About feature XYZ
In this section, go into a deeper explanation of the feature, provide typical use cases, etc.
:::info
if needed, use this syntax to add a note (info) or warning (warning).
:::
### More info about the feature, a sub-category of info
Use this section if there are several big topics or categories of info that the reader needs to know about the feature or task. Add as many of these sections as needed.
## Prerequisites
bullet list of pre-reqs
## Overview of steps/workflow (Optional, only if there are a lot of steps)
describe the 50,000 meter view before they dive into the detailed steps, using a bullet list of the main steps, or even a diagram of the workflow.
## first several group steps
1. first step
2. second step
3. third step
if you need a tabbed section to represent diff processes or code snippets for diff install environments, use an MDX tabbed component.
## next step of grouped steps, if needed
Continue with the steps...
## verify the steps
add verification steps

35
docs/topics/developer-docs/docs/templates/conceptual.md vendored Normal file
View File

@ -0,0 +1,35 @@
---
title: "Conceptual topic"
---
:::info
**How to use this template**: start with the markdown version of the template, either by copying the [`conceptual.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/docs/topics/developer-docs/docs/templates) file from our GitHub repo or downloading the template file using the following command:
```
wget https://raw.githubusercontent.com/goauthentik/authentik/main/docs/topics/developer-docs/docs/templates/conceptual.tmpl.md
```
Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
:::
Use a title that focuses on the feature, component, or technology you are writing about... for example, "About authentik polices" or "Understanding outposts". For conceptual docs, the verb in the title should indicate a concept, such as "About" or "Overview" or "Understanding", followed by the noun (the component or object you are writing about).
In this first section, immediately after the title, write one or two sentences about the feature, component, or technology. The following sections can help break up the content.
## Common use cases (optional section)
In this optional section, provide some example use cases for the feature. Who would use it, WHY? If you mention HOW to use the feature, be sure to link off to the related procedural doc. Also share situations where users might NOT want to use the feature; for example, if the feature is intended for a specific environment.
## Overview of feature/component
Dive deeper into explaining the concepts behind the feature/component.
Write about the feature/functionality from the user's perspective. What is this feature used for, why should they use it, are there situations where they should **_not_** use it?
> Pro Tip: If you were writing the related procedural topic, and you found that you had a lot to say about the topic, this is exactly where that info would go (not crowded up at the top of the procedural topic!).
Cover anything the user needs to know about the feature. If there are Reference docs or a related procedural doc for this feature or component, be sure to link to them from this page.
## Important considerations
List anything that might be critical for user to know, such as situations where this feature might not be ideal, or pre-configs that need to be set, etc.

21
docs/topics/developer-docs/docs/templates/conceptual.tmpl.md vendored Normal file
View File

@ -0,0 +1,21 @@
---
title: "Markdown template: conceptual"
---
Write a few sentences introducing the feature/component/technology.
:::info
if needed, use this syntax to add a note (info) or warning (warning)
:::
## Common use cases
Provide a few use cases, with examples/scenarios when possible.
## About feature x
Provide more conceptual details.
##Important considerations
List anything users should know before implementing the feature/technology.

23
docs/topics/developer-docs/docs/templates/index.md vendored Normal file
View File

@ -0,0 +1,23 @@
---
title: "Templates"
---
In technical documentation, there are document "types" (similar to how there are data types). We have templates for the different types, to make it super-easy for whomever wants to contribute some documentation!
The most common types are:
- [**Combo**](./combo.md): For most topics (unless they are very large and complex), we can combine the procedural and conceptual information into a single document. A handy guideline to follow is: "If the actual 1., 2., 3. steps are buried at the bottom, and a reader has to scroll multiple times to find them, then the combo approach is _not_ the right one".
- [**Procedural**](./procedural.md): these are How To docs, the HOW information, with step-by-step instructions for accomplishing a task. This is what most people are looking for when they open the docs... and best practice is to separate the procedural docs from long, lengthy conceptual or reference docs.
- [**Conceptual**](./conceptual.md): these docs provide the WHY information, and explain when to use a feature (or when not to!), and general concepts behind the feature or functionality.
- [**Reference**](./reference.md): this is typically tables or lists of reference information, such as configuration values, or functions, or most commmonly APIs.
### Add a new integration
To add documentation for a new integration (with support level Community or Vendor), please use the integration templates [`service.md`](https://github.com/goauthentik/authentik/blob/main/docs/topics/integrations/template/service.md) from our GitHub repo. You can download the template using the following command:
```shell
wget https://raw.githubusercontent.com/goauthentik/authentik/main/docs/topics/integrations/template/service.md
```

47
docs/topics/developer-docs/docs/templates/procedural.md vendored Normal file
View File

@ -0,0 +1,47 @@
---
title: "Procedural topic"
---
:::info
**How to use this template**: start with the markdown version of the template, either by copying the [`procedural.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/docs/topics/developer-docs/docs/templates) file from our GitHub repo or downloading the template file using the following command:
```
wget https://raw.githubusercontent.com/goauthentik/authentik/main/docs/topics/developer-docs/docs/templates/procedural.tmpl.md
```
Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
:::
For a procedural topic, use a title that focuses on the task you are writing about. For example, "Add a new Group" or "Edit user profiles". For procedural docs, there should be a verb in the title, and usually the noun (the component or object you are working on). For the title (and all headings) use the infinitive form of the verb (i.e. "add") not the gerund form (i.e. "adding").
In this first section, right after the title, write one or two sentences about the task. Keep it brief; if it goes on too long, then create a separate conceptual topic, in a separate `.md` file. We don't want readers to have to scroll through paragraphs of conceptual info before they get to Step 1.
## Prerequisites (optional section)
In this section, inform the reader of anything they need to do, or have configured or installed, before they start following the procedural instructions below.
## Overview of steps/workflow (optional section)
If the task is quite long or complex, it might be good to add a bullet list of the main steps, or even a diagram of the workflow, just so that the reader can first familiarize themselves with the 50,000 meter view before they dive into the detailed steps.
## First several group steps
If the task involves a lot of steps, try to group them into similar steps and have a Head3 or Head4 title for each group.
In this section, help the reader get oriented... where do they need to be (i.e. in the GUI, on a CLI, etc).
Have a separate paragraph for each step.
Start instructions with the desired goal, followed by the instructions. For example, in this sentence we first read the goal (to define a new port) and then we see the instructions: "To define a new port number, navigate to the Admin interface, and then to the **Settings** tab."
## Next step of grouped steps (if a second group is needed)
Continue with the steps...
Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words.
Provide as many code snippets and examples as needed.
## Verify the steps
Use a heading such as "Verify your installation" or "Verify successful configuration". Whenever possible, it is useful to add verification steps at the end of a procedural topic. For example, if the procedural was about installing a product, use this section to tell them how they can verify that the install was successful.

35
docs/topics/developer-docs/docs/templates/procedural.tmpl.md vendored Normal file
View File

@ -0,0 +1,35 @@
---
title: "Markdown template: procedural"
---
add brief description of the feature/functionality
:::info
if needed, use this syntax to add a note (info) or warning (warning)
:::
## Prerequisites
bullet list of pre-reqs
## Overview of steps/workflow
describe the 50,000 meter view before they dive into the detailed steps, using a bullet list of the main steps, or even a diagram of the workflow.
## first several group steps
1. first step
2. second step
3. third step
if you need a tabbed section to represent diff processes or code snippets for diff install environments, use an MDX tabbed component.
## next step of grouped steps, if needed
Continue with the steps...
## verify the steps
add verification steps

39
docs/topics/developer-docs/docs/templates/reference.md vendored Normal file
View File

@ -0,0 +1,39 @@
---
title: "Reference topic"
---
:::info
**How to use this template**: start with the markdown version of the template, either by copying the [`reference.tmpl.md`](https://github.com/goauthentik/authentik/tree/main/docs/topics/developer-docs/docs/templates) file from our GitHub repo or downloading the template file using the following command:
```
wget https://raw.githubusercontent.com/goauthentik/authentik/main/docs/topics/developer-docs/docs/templates/reference.tmpl.md
```
Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
:::
Create a title that specifies the component you are documenting. For example, "Group attributes".
Provide a sentence or two about the topic.
Reference documentation provides details, values, syntax, etc., about specific programming elements.
The most common type of reference documentation is for REST APIs; the request syntax, a successful response, any parameters such as query, header, or request body parameters, and possible http status codes.
Other types of reference content include lists of functions, parameters, object properties, event actions, and attributes.
## Head 2
Use a title that is descriptive, such as "User object attributes" or "Expression policy functions".
Use tables, bullet lists, Head3s... whatever you need to clearly present the values.
Be sure to use a sentence after every heading, to explain what the section is about, how the values are used, etc.
### Head 3 (optional, if needed)
Add a sentence explaining the following grouping.
### Head 3 (optional, if needed)
Add a sentence explaining the following grouping.

19
docs/topics/developer-docs/docs/templates/reference.tmpl.md vendored Normal file
View File

@ -0,0 +1,19 @@
---
title: "Markdown template: reference"
---
Write a few sentences introducing the feature/component/technology, and state that this page contains refeerence materials.
:::info
if needed, use this syntax to add a note (info) or warning (warning)
:::
## Head 2
After a brief description of this section, list the reference values.
Consider using a table if that is cleaner looking.
### Head 3 (optional, if needed)
After a brief description of this section, list the reference values.

59
docs/topics/developer-docs/docs/writing-documentation.md Normal file
View File

@ -0,0 +1,59 @@
---
title: Writing documentation
---
Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. We appreciate contributions to our documentation; everything from fixing a typo to adding additional content to writing a completely new topic.
Adhering to the following guidelines will help us get your PRs merged much easier and faster, with fewer edits needed.
- Ideally, when you are making contributions to the documentation, you should fork and clone our repo, then [build it locally](#set-up-your-local-build), so that you can test the docs and run the required linting and spell checkers before pushing your PR. While you can do much of the writing and editing within the GitHub UI, you cannot run the required linters from the GitHub UI.
- Please refer to our [Style Guide](./style-guide.mdx) for authentik documentation. Here you will learn important guidelines about not capitalizing authentik, how we format our titles and headers, and much more.
- Remember to use our [docs templates](./templates/index.md) when possible; they are already set up to follow our style guidelines, they make it a lot easier for you (no blank page frights!), and keeps the documentation structure and headings consistent.
- To test how the documentation renders you can build locally and then use the Netlify Deploy Preview, especially when using Docusaurus-specific features. You can also run the `make docs-watch` command on your local build, to see the rendered pages as you make changes.
- Be sure to run the `make docs` command on your local branch, before pushing the PR to the authentik repo. This command does important linting, and the build check in our repo will fail if the linting has not been done.
- For new entries, make sure to add any new pages to the appropriate `sidebar.js` file. Otherwise, the new page will not appear in the table of contents to the left.
## Set up your local build
Requirements:
- Node.js 20 (or greater, we use Node.js 24)
The docs and the code are in the same Github repo, at https://github.com/goauthentik/authentik, so if you have cloned the repo, you already have the docs.
You can do local builds of the documentation to test your changes or review your new content, and to run the required `make docs` command (which runs `prettier` and other linters) before pushing your PR.
The documentation site is situated in the `/docs` folder of the repo.
The site is built using npm, below are some useful make commands:
- **Installation**: `make docs-install`
This command is required before running any of the following commands, and after upgrading any dependencies.
- **Formatting**: `make docs`, `make docs-lint-fix`, or `npm run prettier`
Run the appropriate formatting command for your set up before committing, to ensure consistent syntax, clean formatting, and verify links. Note that if the formatting command is not run, the build will fail with an error about linting.
- **Live editing**: `make docs-watch`
For real-time viewing of changes, as you make them.
:::info
Be sure to run a formatting command before committing changes.
:::
## Documentation for Integrations
In addition to following the [Style Guide](./style-guide.mdx) please review the following guidelines.
For new integration documentation, please use the Integrations template in our [Github repo](https://github.com/goauthentik/authentik) at `/docs/integrations/template/service.md`.
- For placeholder domains, use `authentik.company` and `app-name.company`, where `app-name` is the name of the application that you are writing documentation for.
- Try to order the documentation sections in an order that makes it easiest for the user to configure.

BIN
docs/topics/developer-docs/hackathon/horizontal-brandon-frie-rdHeGGn7rwQ-unsplash.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 380 KiB

63
docs/topics/developer-docs/hackathon/index.md Normal file
View File

@ -0,0 +1,63 @@
---
title: Hackathon 2023
---
![hackathon-image](./horizontal-brandon-frie-rdHeGGn7rwQ-unsplash.jpg)
**REGISTRATION NOW CLOSED. PLEASE JOIN US FOR A FUTURE AUTHENTIK HACKATHON.**
^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^
## Join us for our first authentik hackathon!
Everyone welcome; we will work on code, docs, and anything else that looks interesting and challenging.
Moderators will be available for most US and European hours, so if during the multi-day event, participants have questions or a PR needs a technical review, we are here for you.
Prizes? Why, Yes! We've got a total prize pool of $5000 and a bunch of cool authentik-branded socks and, indubitably, GitHub fame.
## When
July 26-30, 2023
- Kickoff meeting is on Wednesday, July 26th, at 8:00am Pacific USA (UTC -7), 5:00pm in Central Europe (UTC +2), and 8:30pm in Mumbai (UTC +5.30)
- Check-in calls on Thursday and Friday, for one hour, at the same times as above.
- Wrap-up and first demos on Saturday, starting at same times as above.
- Final demos, voting, and awards on Sunday! Yep, same times as above.
## Where
Online, in our [GitHub repo](https://github.com/goauthentik/authentik), and on Discord in our [#hackathon23 channel](https://discord.com/channels/809154715984199690/1110948434552299673) for our Kickoff call, checkins, and the wrap-up and awards events. We will also use the #hackathon23 channel throughout the entire five days, for questions and general chatting. Be sure to first visit our [welcome-info-rules channel](https://discord.com/channels/809154715984199690/813452440660606986), to review our code of conduct and see the latest posts about the hackathon.
## Take a look on GitHub
If you already know what you and/or your team want to work on, you can open an [Issue](https://github.com/goauthentik/authentik/issues) using our template for all hackathon Issues at any time (why not now?) and add the `hackathon` label. Then, when you register, enter the Issue number that you opened on your registration form. This way, on Kickoff Day we can easily match participants with their Issue of interest.
During the Kickoff call, there will be time to peruse existing Issues and add emotes to indicate your interest in working on it (or having it worked on!)
- 🚀 I want to work on this
- ❤️ I want to see this worked on
## Agenda
- **Wednesday, July 26th**: Kickoff, voting for topics to work on, teams formed, participants select the Issue/team they are going to work on, and get their environment set up. After the online kickoff, you can start your work at any time.
- **Thursday July 27th**: HackDay #1: participants working on their PRs, a one-hour Check-in call
- **Friday, July 28th**: HackDay #2: participants working on their PRs, a one-hour Check-in call
- **Saturday, July 29th**: an online “meeting” to do wrap-up, participants sign-up for demo slots (Saturday and Sunday slots available), then some demos
- **Sunday, July 30th**: rest of the demos, votes, and awards
## About that money...
Be aware that all prize money distributions will follow local/state/country laws regarding taxation, not providing funds to citizens of countries prohibited by US law, and all other legal requirements.
## Questions?
Chat with us on [Discord](https://discord.com/channels/809154715984199690/1110948434552299673) and email us at hackathon@goauthentik.io!
## Spread the word!
We would be grateful if you help us get the word out. Share this page and information wherever you hang out. Bring 'em all!

183
docs/topics/developer-docs/index.md Normal file
View File

@ -0,0 +1,183 @@
---
title: Contributing to authentik
---
:+1::tada: Thanks for taking the time to contribute! :tada::+1:
The following is a set of guidelines for contributing to authentik and its components, which are hosted in the [goauthentik Organization](https://github.com/goauthentik) on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
We appreciate contributions of code, documentation, enhancements, and bug fixes. Read more [below](#how-can-i-contribute) about the many ways to contribute.
## Code of Conduct
We expect all contributors to act professionally and respectfully in all interactions. If there's something you dislike or think can be done better, tell us! We'd love to hear any suggestions for improvement.
## I don't want to read this whole thing I just have a question!!!
Either [create a question on GitHub](https://github.com/goauthentik/authentik/issues/new?assignees=&labels=question&template=question.md&title=) or join [the Discord server](https://goauthentik.io/discord)
## What should I know before I get started?
### The components
authentik consists of a few larger components:
- _authentik_ the actual application server, is described below.
- _outpost-proxy_ is a Go application based on a forked version of oauth2_proxy, which does identity-aware reverse proxying.
- _outpost-ldap_ is a Go LDAP server that uses the _authentik_ application server as its backend
- _outpost-radius_ is a Go RADIUS server that uses the _authentik_ application server as its backend
- _web_ is the web frontend, both for administrating and using authentik. It is written in TypeScript using lit-html and the PatternFly CSS Library.
- _docs_ is the documentation, which uses docusaurus.
### authentik's structure
authentik is at it's very core a Django project. It consists of many individual django applications. These applications are intended to separate concerns, and they may share code between each other.
These are the current packages:
```
authentik
├── admin - Administrative tasks and APIs, no models (Version updates, Metrics, system tasks)
├── api - General API Configuration (Routes, Schema and general API utilities)
├── blueprints - Handle managed models and their state.
├── core - Core authentik functionality, central routes, core Models
├── crypto - Cryptography, currently used to generate and hold Certificates and Private Keys
├── enterprise - Enterprise features, which are source available but not open source
├── events - Event Log, middleware and signals to generate signals
├── flows - Flows, the FlowPlanner and the FlowExecutor, used for all flows for authentication, authorization, etc
├── lib - Generic library of functions, few dependencies on other packages.
├── outposts - Configure and deploy outposts on kubernetes and docker.
├── policies - General PolicyEngine
│   ├── dummy - A Dummy policy used for testing
│   ├── event_matcher - Match events based on different criteria
│   ├── expiry - Check when a user's password was last set
│   ├── expression - Execute any arbitrary python code
│   ├── password - Check a password against several rules
│   └── reputation - Check the user's/client's reputation
├── providers
│   ├── ldap - Provide LDAP access to authentik users/groups using an outpost
│   ├── oauth2 - OIDC-compliant OAuth2 provider
│   ├── proxy - Provides an identity-aware proxy using an outpost
│   ├── radius - Provides a RADIUS server that authenticates using flows
│   ├── saml - SAML2 Provider
│   └── scim - SCIM Provider
├── recovery - Generate keys to use in case you lock yourself out
├── root - Root django application, contains global settings and routes
├── sources
│   ├── ldap - Sync LDAP users from OpenLDAP or Active Directory into authentik
│   ├── oauth - OAuth1 and OAuth2 Source
│   ├── plex - Plex source
│   └── saml - SAML2 Source
├── stages
│   ├── authenticator_duo - Configure a DUO authenticator
│   ├── authenticator_static - Configure TOTP backup keys
│   ├── authenticator_totp - Configure a TOTP authenticator
│   ├── authenticator_validate - Validate any authenticator
│   ├── authenticator_webauthn - Configure a WebAuthn / Passkeys authenticator
│   ├── captcha - Make the user pass a captcha
│   ├── consent - Let the user decide if they want to consent to an action
│   ├── deny - Static deny, can be used with policies
│   ├── dummy - Dummy stage to test
│   ├── email - Send the user an email and block execution until they click the link
│   ├── identification - Identify a user with any combination of fields
│   ├── invitation - Invitation system to limit flows to certain users
│   ├── password - Password authentication
│   ├── prompt - Arbitrary prompts
│   ├── user_delete - Delete the currently pending user
│   ├── user_login - Login the currently pending user
│   ├── user_logout - Logout the currently pending user
│   └── user_write - Write any currently pending data to the user.
└── tenants - Soft tennancy, configure defaults and branding per domain
```
This Django project is running in gunicorn, which spawns multiple workers and threads. Gunicorn is run from a lightweight Go application which reverse-proxies it, handles static files and will eventually gain more functionality as more code is migrated to go.
There are also several background tasks which run in Celery, the root celery application is defined in `authentik.root.celery`.
## How Can I Contribute?
### Reporting Bugs
This section guides you through submitting a bug report for authentik. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
Whenever authentik encounters an error, it will be logged as an Event with the type `system_exception`. This event type has a button to directly open a pre-filled GitHub issue form.
This form will have the full stack trace of the error that occurred and shouldn't contain any sensitive data.
### Suggesting Enhancements
This section guides you through submitting an enhancement suggestion for authentik, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
When you are creating an enhancement suggestion, please fill in [the template](https://github.com/goauthentik/authentik/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=), including the steps that you imagine you would take if the feature you're requesting existed.
### Your First Code Contribution
#### Local development
authentik can be run locally, although depending on which part you want to work on, different pre-requisites are required.
This is documented in the [developer docs](./setup/frontend-dev-environment.md).
### Help with the Docs
Contributions to the technical documentation are greatly appreciated. Open a PR if you have improvements to make or new content to add. If you have questions or suggestions about the documentation, open an Issue. No contribution is too small.
Please be sure to refer to our [Style Guide](../developer-docs/docs/style-guide.mdx) for the docs, and use a [template](./docs/templates/index.md) to make it easier for you. The style guidelines are also used for any Integrations documentation, and we have a template for Integrations as well, in our [Github repo](https://github.com/goauthentik/authentik) at `/docs/integrations/template/service.md`.
### Pull Requests
The process described here has several goals:
- Maintain authentik's quality
- Fix problems that are important to users
- Engage the community in working toward the best possible authentik
- Enable a sustainable system for authentik's maintainers to review contributions
Please follow these steps to have your contribution considered by the maintainers:
1. Follow the [styleguides](#style-guides)
2. After you submit your pull request, verify that all [status checks](https://help.github.com/topics/about-status-checks/) are passing <details><summary>What if the status checks are failing?</summary>If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.</details>
3. Ensure your Code has tests. While it is not always possible to test every single case, the majority of the code should be tested.
While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
## Style guides
### PR naming
- Use the format of `<package>: <verb> <description>`
- See [here](#authentiks-structure) for `package`
- Examples:
`providers/saml2: fix parsing of requests`
`docs: add config info for GWS`
### Git Commit Messages
- Use the format of `<package>: <verb> <description>`
- See [here](#authentiks-structure) for `package`
- Example: `providers/saml2: fix parsing of requests`
- Reference issues and pull requests liberally after the first line
- Naming of commits within a PR does not need to adhere to the guidelines as we squash merge PRs
### Python Style Guide
All Python code is linted with [black](https://black.readthedocs.io/en/stable/) and [Ruff](https://docs.astral.sh/ruff).
authentik runs on Python 3.13 at the time of writing this.
- Use native type-annotations wherever possible.
- Add meaningful docstrings when possible.
- Ensure any database migrations work properly from the last stable version (this is checked via CI)
- If your code changes central functions, make sure nothing else is broken.
### Documentation Style Guide
Refer to the full [Style Guide](../developer-docs/docs/style-guide.mdx) for details, but here are some important highlights:
- Our product name is authentik, with a lower-case "a" and a "k" on the end. Our company name is Authentik Security.
- We use sentence style case in our titles and headings.
- We use **bold** text to name UI components, and _italic_ text for variables.
- Use [MDX](https://mdxjs.com/) whenever appropriate. MDX, which uses React components, is useful for creating tabs, action buttons, and advanced content formatting.

183
docs/topics/developer-docs/releases/index.md Normal file
View File

@ -0,0 +1,183 @@
# Releasing authentik
### Creating a standard release
- Ensure a branch exists for the version family (for 2022.12.2 the branch would be `version-2022.12`)
- Merge all the commits that should be released on the version branch
If backporting commits to a non-current version branch, cherry-pick the commits.
- Check if any of the changes merged to the branch make changes to the API schema, and if so update the package `@goauthentik/api` in `/web`
- Push the branch, which will run the CI pipeline to make sure all tests pass
- Create the version subdomain for the version branch ([see](https://github.com/goauthentik/terraform/commit/87792678ed525711be9c8c15dd4b931077dbaac2)) and add the subdomain in Netlify ([here](https://app.netlify.com/sites/authentik/settings/domain))
- Create/update the release notes
#### For initial releases:
- Copy `docs/topics/releases/_template.md` to `docs/topics/releases/v2022.12.md` and replace `xxxx.x` with the version that is being released
- Fill in the section of `Breaking changes` and `New features`, or remove the headers if there's nothing applicable
- Run `git log --pretty=format:'- %s' version/2022.11.3...version-2022.12`, where `version/2022.11.3` is the tag of the previous stable release. This will output a list of all commits since the previous release.
- Paste the list of commits since the previous release under the `Minor changes/fixes` section.
Run `make gen-changelog` and use the contents of `changelog.md`. Remove merged PRs from bumped dependencies unless they fix security issues or are otherwise notable. Remove merged PRs with the `docs/` prefix.
- Sort the list of commits alphabetically and remove all commits that have little importance, like dependency updates and linting fixes
- Run `make gen-diff` and copy the contents of `diff.md` under `API Changes`
- Run `make docs`
#### For subsequent releases:
- Paste the list of commits since the previous release into `docs/releases/v2022.12.md`, creating a new section called `## Fixed in 2022.12.2` underneath the `Minor changes/fixes` section
- Run `make gen-changelog` and use the contents of `changelog.md`. Remove merged PRs from bumped dependencies unless they fix security issues or are otherwise notable. Remove merged PRs with the `docs/` prefix.
- Run `make gen-diff` and copy the contents of `diff.md` under `API Changes`, replacing the previous changes
- Run `make docs`
- Run `bumpversion` on the version branch with the new version (i.e. `bumpversion --new-version 2022.12.2 minor --verbose`)
- Push the tag and commit
- A GitHub actions workflow will start to run a last test in container images and create a draft release on GitHub
- Edit the draft GitHub release
- Make sure the title is formatted `Release 2022.12.0`
- Add the following to the release notes
```
See https://goauthentik.io/docs/releases/2022.12
```
Or if creating a subsequent release
```
See https://goauthentik.io/docs/releases/2022.12#fixed-in-2022121
```
- Auto-generate the full release notes using the GitHub _Generate Release Notes_ feature
### Preparing a security release
- Create a draft GitHub Security advisory
<details>
<summary>Template</summary>
```markdown
### Summary
Short summary of the issue
### Patches
authentik x, y and z fix this issue, for other versions the workaround below can be used.
### Impact
Describe the impact that this issue has
### Details
Further explain how the issue works
### Workarounds
Describe a workaround if possible
### For more information
If you have any questions or comments about this advisory:
- Email us at [security@goauthentik.io](mailto:security@goauthentik.io).
```
</details>
- Request a CVE via the draft advisory
- If possible, add the original reporter in the advisory
- Implement a fix on a local branch `security/CVE-...`
The fix must include unit tests to ensure the issue can't happen again in the future
Update the release notes as specified above, making sure to address the CVE being fixed
Create a new file `/docs/topics/security/CVE-....md` with the same structure as the GitHub advisory
Include the new file in the `/docs/topics/sidebars.js`
Push the branch to https://github.com/goauthentik/authentik-internal for CI to run and for reviews
An image with the fix is built under `ghcr.io/goauthentik/internal-server` which can be made accessible to the reporter for testing
- Check with the original reporter that the fix works as intended
- Wait for GitHub to assign a CVE
- Announce the release of the vulnerability via Mailing list and discord
<details>
<summary>Mailing list template</summary>
Subject: `Notice of upcoming authentik Security releases 2022.10.3 and 2022.11.3`
```markdown
We'll be publishing a security Issue (CVE-2022-xxxxx) and accompanying fix on _date_, 13:00 UTC with the Severity level High. Fixed versions x, y and z will be released alongside a workaround for previous versions. For more info, see the authentik Security policy here: https://goauthentik.io/docs/security/policy.
```
</details>
<details>
<summary>Discord template</summary>
```markdown
@everyone We'll be publishing a security Issue (CVE-2022-xxxxx) and accompanying fix on _date_, 13:00 UTC with the Severity level High. Fixed versions x, y and z will be released alongside a workaround for previous versions. For more info, see the authentik Security policy here: https://goauthentik.io/docs/security/policy.
```
</details>
### Creating a security release
- On the date specified in the announcement, retag the image from `authentik-internal` to the main image:
```
docker buildx imagetools create -t ghcr.io/goauthentik/server:xxxx.x ghcr.io/goauthentik/internal-server:gh-cve-2022-xxx
docker buildx imagetools create -t ghcr.io/goauthentik/server:xxxx.x.x ghcr.io/goauthentik/internal-server:gh-cve-2022-xxx
```
Where xxxx.x is the version family and xxxx.x.x is the full version.
This will make the fixed container image available instantly, while the full release is running on the main repository.
- Push the local `security/CVE-2022-xxxxx` branch into a PR, and squash merge it if the pipeline passes
- If the fix made any changes to the API schema, merge the PR to update the web API client
- Cherry-pick the merge commit onto the version branch
- If the fix made any changes to the API schema, manually install the latest version of the API client in `/web`
- Resume the instructions above, starting with the `bumpversion` step
- After the release has been published, update the Discord announcement and send another mail to the mailing list to point to the new releases
<details>
<summary>Mailing list template</summary>
Subject: `Release of authentik Security releases 2022.10.3 and 2022.11.3`
```markdown
The security advisory for CVE-2022-xxxxx has been published: https://github.com/goauthentik/authentik/security/advisories/GHSA-mjfw-54m5-fvjf
Releases 2022.10.3 and 2022.11.3 with fixes included are available here: https://github.com/goauthentik/authentik/releases
```
</details>
<details>
<summary>Discord template</summary>
```markdown
[...existing announcement...]
Edit:
Advisory for for CVE-2022-xxxxx has been published here https://github.com/goauthentik/authentik/security/advisories/GHSA-mjfw-54m5-fvjf
The fixed versions 2022.10.3 and 2022.11.3 are available here: https://github.com/goauthentik/authentik/releases
```
</details>

BIN
docs/topics/developer-docs/setup/debug_vscode.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 805 KiB

53
docs/topics/developer-docs/setup/debugging.md Normal file
View File

@ -0,0 +1,53 @@
---
title: Debugging authentik
---
This page describes how to debug different components of an authentik instance, running either in production or in a development setup. To learn more about the structure of authentik, refer to our [architecture documentation](../../core/architecture.md).
## authentik Server & Worker (Python)
The majority of the authentik codebase is in Python, running in Gunicorn for the server and Celery for the worker. These instructions show how this code can be debugged/inspected. The local debugging setup requires a setup as described in [Full development environment](./full-dev-environment.mdx)
Note that authentik uses [debugpy](https://github.com/microsoft/debugpy), which relies on the "Debug Adapter Protocol" (DAP). These instructions demonstrate debugging using [Visual Studio Code](https://code.visualstudio.com/), however they should be adaptable to other editors that support DAP.
To enable the debugging server, set the environment variable `AUTHENTIK_DEBUGGER` to `true`. This will launch the debugging server (by default on port _9901_).
With this setup in place, you can set Breakpoints in VS Code. To connect to the debugging server, run the command `> Debug: Start Debugging" in VS Code.
![](./debug_vscode.png)
:::info
Note that due to the Python debugger for VS Code, when a Python file in authentik is saved and the Django process restarts, you must manually reconnect the Debug session. Automatic re-connection is not supported for the Python debugger (see [here](https://github.com/microsoft/vscode-python/issues/19998) and [here](https://github.com/microsoft/vscode-python/issues/1182)).
:::
#### Debugging in containers
When debugging an authentik instance running in containers, there are some additional steps that need to be taken in addition to the steps above.
A local clone of the authentik repository is required to be able to set breakpoints in the code. The locally checked out repository must be on the same version/commit as the authentik version running in the containers. To checkout version 2024.12.3 for example, you can run `git checkout version/2024.12.3`.
The debug port needs to be accessible on the local machine. By default, this is port 9901. Additionally, the container being debugged must be started as `root`, because additional dependencies need to be installed on startup.
When running in Docker Compose, a file `docker-compose.override.yml` can be created next to the authentik docker-compose.yml file to expose the port, change the user, and enable debug mode.
```yaml
services:
# Replace `server` with `worker` to debug the worker container.
server:
user: root
healthcheck:
disable: true
environment:
AUTHENTIK_DEBUGGER: "true"
AUTHENTIK_LOG_LEVEL: "debug"
ports:
- 9901:9901
```
After re-creating the containers with `AUTHENTIK_DEBUGGER` set to `true` and the port mapped, the steps are identical to the steps above.
If the authentik instance is running on a remote server, the `.vscode/launch.json` file needs to be adjusted to point to the IP of the remote server. Alternatively, it is also possible to forward the debug port via an SSH tunnel, using `-L 9901:127.0.0.1:9901`.
## authentik Server / Outposts (Golang)
Outposts, as well as some auxiliary code of the authentik server, are written in Go. These components can be debugged using standard Golang tooling, such as [Delve](https://github.com/go-delve/delve).

83
docs/topics/developer-docs/setup/frontend-dev-environment.md Normal file
View File

@ -0,0 +1,83 @@
---
title: Frontend development environment
sidebar_label: Frontend development
tags:
- development
- contributor
- frontend
- docker
---
If you're focusing solely on frontend development, you can create a minimal development environment using Docker and Node.js. This setup allows you to make and preview changes to the frontend in real-time, without needing to interact with the backend.
### Prerequisites
- [Node.js](https://nodejs.org/en) (24 or later)
- [Docker](https://www.docker.com/) (Latest Community Edition or Docker Desktop)
- [Docker Compose](https://docs.docker.com/compose/) (Compose v2)
- [Make](https://www.gnu.org/software/make/) (3 or later)
:::info
Depending on platform, some native dependencies might be required. On macOS, run `brew install node@24`, and for Docker `brew install --cask docker`
:::
### Instructions
1. Clone the Git repo to your development machine and navigate to the authentik directory.
```shell
git clone https://github.com/goauthentik/authentik
cd authentik
```
:::info Beta images
By default, authentik will use the latest stable Docker images.
You can opt into using beta images during development by creating a `.env` file in the root of the repository with the following variables:
```shell
AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-next
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-next
AUTHENTIK_LOG_LEVEL=debug
```
:::
2. From the cloned repository, follow the Docker Compose [installation instructions](../../install-config/install/docker-compose.mdx).
3. Create a Docker Compose override to mount the local configuration file (`local.env.yml`) and ESBuild's output directory (`web`).
```yaml title="docker-compose.override.yml"
services:
server:
volumes:
- ./web:/web
- ./local.env.yml:/local.env.yml
```
By creating this file in the root of the repository, Docker will automatically mount the web files generated by the build process. The `local.env.yml` mount is optional, but allows you to override the default configuration.
4. From the cloned repository root, install the front-end dependencies using NPM.
```shell
cd web
npm ci
```
5. From the cloned repository root, run the front-end build script.
```shell
make web-watch
```
6. In a new terminal, navigate to the cloned repository root and start the backend containers with Docker Compose.
```shell
docker compose up
```
You can now access authentik on http://localhost:9000 (or https://localhost:9443).
You might also want to complete the initial setup under `/if/flow/initial-setup/`.

158
docs/topics/developer-docs/setup/full-dev-environment.mdx Normal file
View File

@ -0,0 +1,158 @@
---
title: Full development environment
sidebar_label: Full development
tags:
- development
- contributor
- backend
- frontend
- docker
---
import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
import TabItem from "@theme/TabItem";
import Tabs from "@theme/Tabs";
## Requirements
- [Python](https://www.python.org/) (3.13 or later)
- [uv](https://docs.astral.sh/uv/getting-started/installation/), (Latest stable release)
- [Go](https://go.dev/) (1.24 or later)
- [Node.js](https://nodejs.org/en) (24 or later)
- [PostgreSQL](https://www.postgresql.org/) (16 or later)
- [Redis](https://redis.io/) (7 or later)
- [Docker](https://www.docker.com/) (Latest Community Edition or Docker Desktop)
- [Docker Compose](https://docs.docker.com/compose/) (Compose v2)
## Services Setup
For PostgreSQL and Redis, you can use the `docker-compose.yml` file in `/scripts`.To use these pre-configured database instances, navigate to the `/scripts` directory in your local copy of the authentik git repo, and run `docker compose up -d`.
You can also use a native install, if you prefer.
:::info
If you use locally installed databases, the PostgreSQL credentials given to authentik should have permissions for `CREATE DATABASE` and `DROP DATABASE`, because authentik creates a temporary database for tests.
:::
## Backend Setup
:::info
Depending on your platform, some native dependencies might be required.
<Tabs
defaultValue={ (ExecutionEnvironment.canUseDOM) ? (() => {
const ua = window.navigator.userAgent.toLowerCase();
return ["linux", "windows", "mac"].find((p) => ua.includes(p)) || "mac";
})() : "mac" }
values={[
{label: "macOS", value: "mac"},
{label: "Linux", value: "linux"},
{label: "Windows", value: "windows"},
]}>
<TabItem value="mac">
To install the native dependencies on macOS, run:
```sh
$ brew install libxmlsec1 libpq krb5 pkg-config # Required development libraries,
$ brew install uv postgresql redis node@24 golangci-lint # Required CLI tools
```
</TabItem>
<TabItem value="linux">
To install native dependencies on Debian or Ubuntu, run:
```sh
$ pip install uv
$ sudo apt-get install libgss-dev krb5-config libkrb5-dev postgresql-server-dev-all
$ sudo apt-get install postresql redis
```
Adjust your needs as required for other distributions such as Red Hat, SUSE, or Arch.
Install golangci-lint locally [from the site instructions](https://golangci-lint.run/welcome/install/#other-ci).
</TabItem>
<TabItem value="windows">
[We request community input on running the full dev environment on Windows]
</TabItem>
</Tabs>
:::
1. Create an isolated Python environment. To create the environment and install dependencies, run the following commands in the same directory as your local authentik git repository:
```shell
make install # Installs all required dependencies for Python and Javascript, including development dependencies
```
2. Configure authentik to use the local databases using a local config file. To generate this file, run the following command in the same directory as your local authentik git repository:
```shell
make gen-dev-config # Generates a local config file
```
Generally speaking, authentik is a Django application, ran by gunicorn, proxied by a Go application. The Go application serves static files.
Most functions and classes have type-hints and docstrings, so it is recommended to install a Python Type-checking Extension in your IDE to navigate around the code.
## Frontend Setup
By default, no compiled bundle of the frontend is included so this step is required even if you're not developing for the UI.
The UI requires the authentik API files for Typescript be built and installed:
```
$ make migrate # On a fresh install, ensures the API schema file is available
$ make gen # Generates the API based on the schema file
```
If you make changes to the authentik API, you must re-run `make gen` so that the corresponding
changes are made to the API library that is used by the UI.
To build the UI once, run the following command in the same directory as your local authentik git repository:
```shell
make web-build # Builds the UI once
```
If you want to live-edit the UI, you can run the following command in the same directory as your local authentik git repository instead, which will immediately update the UI with any changes you make so you can see the results in real time without needing to rebuild:
```shell
make web-watch # Updates the UI with any changes you make
```
To format the frontend code, run the following command in the same directory as your authentik git repository:
```shell
make web # Formats the frontend code
```
## Running authentik
Now that the backend and frontend have been setup and built, you can start authentik by running the following command in the same directory as your local authentik git repository:
```shell
make run # Starts authentik server
```
And now, authentik should now be accessible at `http://localhost:9000`.
:::info
To define a password for the default admin (called **akadmin**), you can manually enter the `/if/flow/initial-setup/` path in the browser address bar to launch the initial flow. Example: http://localhost:9000/if/flow/initial-setup/.
In case of issues in this process, feel free to use `make dev-reset` which drops and restores the authentik PostgreSQL instance to a "fresh install" state.
:::
## Submitting Pull Requests
Before submitting a pull request, run the following commands in the same directory as your local authentik git repository:
```shell
make lint # Ensures your code is well-formatted
make gen # Generates an updated OpenAPI Docs for any changes you make
make web # Formats the front-end code
```

27
docs/topics/developer-docs/setup/website-dev-environment.md Normal file
View File

@ -0,0 +1,27 @@
---
title: Docs development environment
sidebar_label: Docs development
tags:
- development
- contributor
- docs
- docusaurus
---
If you want to only make changes to the documentation, you only need Node.js.
### Prerequisites
- Node.js (any recent version should work; we use 24.x to build)
- Make (again, any recent version should work)
:::info
Depending on platform, some native dependencies might be required. On macOS, run `brew install node@24`
:::
### Instructions
1. Clone the git repo from https://github.com/goauthentik/authentik
2. Run `make docs-install` to install the docs development dependencies
3. Run `make docs-watch` to start a development server to see and preview your changes
4. Finally when you're about to commit your changes, run `make docs` to run the linter and auto-formatter.

44
docs/topics/developer-docs/translation.md Normal file
View File

@ -0,0 +1,44 @@
---
title: Translations
---
Translation in authentik is done in two places. Most of the text is defined in the frontend in `web/`, and a subset of messages is defined in the backend.
The frontend uses [@lit/localize](https://lit.dev/docs/localization/overview/), and the backend uses the built-in django translation tools.
:::info
Please review the [Writing documentation](./docs/writing-documentation.md) guidelines as they apply to documentation too.
:::
## Online translation
To simplify translation you can use https://www.transifex.com/authentik/authentik, which has no local requirements.
## Local translation
### Prerequisites
- Node (any recent version should work, we use 16.x to build)
- Make (again, any recent version should work)
- Docker
Run `npm i` in the `/web` folder to install all dependencies.
Ensure the language code is in the `lit-localize.json` file in `web/`:
```json
// [...]
"targetLocales": [
"en",
"pseudo-LOCALE",
"a-new-locale"
// [...]
],
// [...]
```
Afterwards, run `make web-i18n-extract` to generate a base .xlf file.
The .xlf files can be edited by any text editor, or using a tool such as [POEdit](https://poedit.net/).
To see the change, run `make web-watch` in the root directory of the repository.