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

27
website/docs/developer-docs/api/api.md Normal file
View File

@ -0,0 +1,27 @@
---
title: API
---
Our API reference documentation is generated, and is included [here](../api/reference/authentik.info.mdx) in our regular documentation Table of Contents, under **API -> Reference**.
You can also access your installation's own, instance-specific API Browser. Starting with 2021.3.5, every authentik instance has a built-in API browser, which can be accessed at <code>https://<em>authentik.company</em>/api/v3/</code>.
To generate an API client you can use the OpenAPI v3 schema at <code>https://<em>authentik.company</em>/api/v3/schema/</code>.
While testing, the API requests are authenticated by your browser session.
## Authentication
For any of the token-based methods, set the `Authorization` header to `Bearer <token>`.
### Session
When authenticating with a flow, you'll get an authenticated Session cookie, that can be used for authentication. Keep in mind that in this context, a CSRF header is also required.
### API Token
Users can create tokens to authenticate as any user with a static key, which can optionally be expiring and auto-rotate.
### JWT Token
OAuth2 clients can request the scope `goauthentik.io/api`, which allows their OAuth Access token to be used to authenticate to the API.

15
website/docs/developer-docs/api/clients.md Normal file
View File

@ -0,0 +1,15 @@
---
title: API Clients
---
These API clients are officially supported and maintained.
:::info
These API clients are primarily built around creating/updating/deleting configuration objects in authentik, and in most cases can **not** be used to implemented SSO into your application.
:::
| Language | Package name | URL |
| --------------------- | ----------------------- | ---------------------------------------------- |
| JavaScript/Typescript | `@goauthentik/api` | https://www.npmjs.com/package/@goauthentik/api |
| Go | `goauthentik.io/api/v3` | https://pkg.go.dev/goauthentik.io/api/v3 |
| Python | `authentik_client` | https://pypi.org/project/authentik-client/ |

69
website/docs/developer-docs/api/flow-executor.md Normal file
View File

@ -0,0 +1,69 @@
---
title: Flow executor (backend)
---
A big focus of authentik is the flows system, which allows you to combine and build complex conditional processes using stages and policies. Normally, these flows are automatically executed in the browser using authentik's [standard browser-based flow executor (/if/flows)](../../add-secure-apps/flows-stages/flow/executors/if-flow.md).
However, any flow can be executed via an API from anywhere, in fact that is what every flow executor does. With a few requests you can execute flows from anywhere, and integrate authentik even better.
:::info
Because the flow executor stores its state in the HTTP Session, so you need to ensure that cookies between flow executor requests are persisted.
:::
The main endpoint for flow execution is `/api/v3/flows/executor/:slug`.
This endpoint accepts a query parameter called `query`, in which the flow executor sends the full query-string.
To initiate a new flow, execute a GET request.
## `GET /api/v3/flows/executor/test-flow/`
Below is the response, for example for an Identification stage.
```json
{
"type": "native", // Stage type, can be "native", "shell" or "redirect"
"flow_info": {
// Related flow information, mostly used for UI and surrounding elements
"title": "Welcome to authentik",
"background": "/static/dist/assets/images/flow_background.jpg",
"cancel_url": "/flows/-/cancel/"
},
// Main component to distinguish which stage is currently active
"component": "ak-stage-identification",
// Stage-specific fields
"user_fields": ["username", "email"],
"password_fields": false,
"primary_action": "Log in",
"sources": []
}
```
To respond to this challenge, send a response:
## `POST /api/v3/flows/executor/test-flow/`
With this body
```json
{
// Component is required to determine how to parse the response
"component": "ak-stage-identification",
// Stage-specific fields
"uid_field": "jens"
}
```
Depending on the flow, you'll either get a 200 Response with another challenge, or a 302 redirect, which should be followed.
Depending also on the stage, a response might take longer to be returned (especially with the Duo Authenticator validation).
To see the data layout for every stage possible, see the [API Browser](./reference/flows-executor-get)
## Result
If a stage with the component `ak-stage-access-denied` is returned, the flow has been denied.
If a stage with the component `xak-flow-redirect` is returned, the flow has been executed successfully.

23
website/docs/developer-docs/api/making-schema-changes.md Normal file
View File

@ -0,0 +1,23 @@
---
title: Making schema changes
---
Some backend changes might require new/different fields or remove other fields. To create a new schema after changing a Serializer, run `make gen-build`.
This will update the `schema.yml` file in the root of the repository.
## Building the Go Client
The Go client is used by the Outpost to communicate with the backend authentik server. To build the go client, run `make gen-client-go`.
The generated files are stored in `/gen-go-api` in the root of the repository.
## Building the Web Client
The web client is used by the web-interface and web-FlowExecutor to communicate with authentik. To build the client, run `make gen-client-ts`.
Since the client is normally distributed as an npm package, running `make gen-client-ts` will overwrite the locally installed client with the newly built one.
:::caution
Running `npm i` in the `/web` folder after using `make gen-client-ts` will overwrite the custom client and revert to the upstream client.
:::

47
website/docs/developer-docs/api/websocket.md Normal file
View File

@ -0,0 +1,47 @@
---
title: Websocket API
---
authentik has two different WebSocket endpoints, one is used for web-based clients to get real-time updates, and the other is used for outposts to report their healthiness.
### Web `/ws/client/`
:::info
Authentication is done using the session, so make sure to send the `Cookie` header.
:::
All messages have a common field called `message_type` to discern the type of message.
#### `message` type:
This type is used when the backend has a notice to show to the user. A full payload looks like:
```json
{
"message_type": "message",
"level": "error" | "warning" | "success" | "info",
"tags": "",
"message": "a message",
}
```
### Outpost `/ws/outpost/<outpost-uuid>/`
:::info
Authentication is done via the `Authorization` header, same as the regular API. You must send a valid token with a `Bearer ` prefix.
:::
All messages have two fields, `instruction` and `args`. Instruction is any number from this list:
- `0`: ACK, simply acknowledges the previous message
- `1`: HELLO, used for monitoring and regularly sent by outposts
- `2`: TRIGGER_UPDATE, sent by authentik to trigger a reload of the configuration
Arguments for these messages vary, all though these common args are always sent:
- `args['uuid']`: A unique UUID generated on startup of an outpost, used to uniquely identify it.
These fields are only sent for HELLO instructions:
- `args['version']`: Version of the outpost
- `args['buildHash']`: Build hash of the outpost, when available

149
website/docs/developer-docs/docs/style-guide.mdx Normal file
View File

@ -0,0 +1,149 @@
---
title: Style Guide
---
The Style Guide provides guidelines to ensure that the authentik documentation is easy to read and uses similar phrasing, formatting, and tone.
We appreciate contributions to our documentation; everything from fixing a typo to adding additional content to writing a completely new topic. To make the review and merging of your contributions faster and easier, please follow the [writing documentation](./writing-documentation.md) guidelines.
If you find any documentation that doesn't match these guidelines, feel free to either open an [Issue](https://github.com/goauthentik/authentik/issues) or a [PR](https://github.com/goauthentik/authentik/pulls) so they can be fixed.
## General style guidelines
- Try to order the documentation sections in the order that makes it easiest for the user to follow. That is, order the sections in the same order as the actual workflow used to accomplish the task.
- Use headings (sub-titles) to break up long documents, and make it easier to find a specific section.
- Add cross-reference links to related content whenever possible.
- You can use standard [Docusaurus-specific features](https://docusaurus.io/docs/next/markdown-features), which include MDX elements such as tabs and admonitions.
## Terminology
### authentik names
- The product name authentik should always start with a lower-case "a" and end with a "k". Even if it is the first word in a sentence. :-)
- Our company name is Authentik Security, Inc. but in non-legal documentation you can shorten it to Authentik Security.
### Industry terms, technology, and other tools
- When referring to external tools, or an industry term or technology, always follow the exact capitalization that the product or company itself uses on their website, in their official documentation, or what the industry uses in consensus.
- Try to avoid using abbreviations if possible.
- Use acronyms where it makes sense (for commonly used terms like SAML or RBAC). If an acronym is less-known, spell it out in parentheses after the first use.
## Writing style
- authentik documentation strives for a friendly, but not overly so, tone. It's ok to be a little bit conversational, and to address the reader in second person: "Next, you need to configure the log in settings."
- Our documentation uses American English ("z" not "s").
- Use the present tense and active voice in almost all cases:
- DON'T: "The Applications page will be loaded."
- DO: "The Applications page displays."
- Phrasing should never blame the user, and should be subjective:
- DON'T: "Never modify the default file."
- DO: "We recommend that you do not modify the default file, because this can result in unexpected issues."
## Formatting
Formatting in documentation is important; it improves comprehension and readability, and allows the brain to more quickly determine what is a command or a configuration setting, what is a field name, or what is a variable.
### Fonts and font styling
- When referring to UI elements or components in the authentik UI, such as field names, labels, etc., use **bold** text.
- When referring to internal components in authentik, like the policy engine, or blueprints, do not use any special formatting. Link to the relevant documentation when possible.
- Use `code` format when referring to:
- commands
- file paths
- file names
- directory names
- code snippets (single line or a block of code)
- For variables or placeholders use _italic_ font for the variable, and use place-holder names that makes it obvious that the user needs to replace it.
Example: <kbd>https://<em>company-domain</em>/source/oauth/callback/<em>source-slug</em></kbd>
When using variables in code snippets, make sure to specify if the value is something the user needs to define, is system-defined or generated.
- 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.
### Titles and headers
- Both titles and headers (H1, H2, H3) use sentence style capitalization, meaning that only the first word is capitalized. However, if the title or header includes a proper noun (name of a product, etc) then capitalize those words.
Examples:
- Configure your provider
- Configure the Google Workspace provider
- Make sure the title/header is descriptive, and tells the reader what that section is about. Try to avoid titles or headers like "Overview". Instead say "About authentik policies".
- Use the imperative verb form (not the gerund form) for procedural topics. For example, use "Configure your instance" instead of "Configuring your instance".
### Examples
When you want to show an example (say, a code snippet), use a new line, bold text, and a semi-colon, like this:
**Example**:
This expression policy uses an expression based on the user's name.
```
if request.context["pending_user"].username == "marie":
return True
return False
```
### Notes and warnings
Use the following convention for a note:
```
:::info
Write your note here.
:::
```
:::info
Write your note here.
:::
For a warning, use this:
```
:::warning
Write your note here.
:::
```
:::warning
Write your warning here.
:::
```
```
## Word choices
- **May** versus **might** versus **can**
Typically, the word "may" is not used in technical writing, because it implies permission (rather than ability) to do something. Instead use the word "can". Use "might" when the scenario could be different in certain environments. Be sparing with your use of "might"; this word implies unpredictability, not our favorite thing with software.
- 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 descriptive term, use one word: "login". (The login panel.)
As a verb, use "log in", with two words. (This stage prompts the user to log in.)
As a verb with the proposition "to", use "log in to". (Log in to the application.)

55
website/docs/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/website/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/website/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 familairize 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
website/docs/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
website/docs/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/website/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/website/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/functionalilty 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
website/docs/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
website/docs/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/website/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/website/integrations/template/service.md
```

47
website/docs/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/website/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/website/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 familairize 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
website/docs/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
website/docs/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/website/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/website/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
website/docs/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.

61
website/docs/developer-docs/docs/writing-documentation.md Normal file
View File

@ -0,0 +1,61 @@
---
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 website-watch` command on your local build, to see the rendered pages as you make changes.
- Be sure to run the `make website` 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 22)
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 website` command (which runs `prettier` and other linters) before pushing your PR.
The documentation site is situated in the `/website` folder of the repo.
The site is built using npm, below are some useful make commands:
- **Installation**: `make website-install`
This command is required before running any of the following commands, and after upgrading any dependencies.
- **Formatting**: `make website`, `make website-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 website-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 `/website/integrations/template/service.md`.
- Make sure to add the service to a fitting category in `/website/sidebarsIntegrations.js`. If this is not done the service will not appear in the table of contents to the left.
- 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
website/docs/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
website/docs/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
website/docs/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.
- _website_ is the Website/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 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, all though 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 `/website/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/articles/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`
`website/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.12 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.

179
website/docs/developer-docs/releases/index.md Normal file
View File

@ -0,0 +1,179 @@
# 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 `website/docs/releases/_template.md` to `website/docs/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 `website/` 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`
- Update `website/sidebars.js` to include the new release notes, and move the oldest release into the `Previous versions` category.
If the release notes are created in advance without a fixed date for the release, only add them to the sidebar once the release is published.
- Run `make website`
#### For subsequent releases:
- Paste the list of commits since the previous release into `website/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 `website/` prefix.
- Run `make gen-diff` and copy the contents of `diff.md` under `API Changes`, replacing the previous changes
- Run `make website`
- 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 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 `/website/docs/security/CVE-....md` with the same structure as the GitHub advisory
Include the new file in the `/website/sidebars.js`
- 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, 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>
<p>
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
```
</p>
</details>
<details>
<summary>Discord template</summary>
<p>
```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
```
</p>
</details>

52
website/docs/developer-docs/setup/frontend-dev-environment.md Normal file
View File

@ -0,0 +1,52 @@
---
title: Frontend-only development environment
---
If you want to only make changes on the UI, you don't need a backend running from source. You can user the docker-compose install with a few customizations.
### Prerequisites
- Node.js (any recent version should work; we use 20.x to build)
- Make (again, any recent version should work)
- Docker and Docker Compose
:::info
Depending on platform, some native dependencies might be required. On macOS, run `brew install node@20`, and for Docker `brew install --cask docker`
:::
### Instructions
1. Clone the git repo from https://github.com/goauthentik/authentik.
2. In the cloned repository, follow the docker-compose installation instructions [here](../../install-config/install/docker-compose).
3. Add the following entry to your `.env` file:
```
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
```
This will cause authentik to use the beta images.
4. Add this volume mapping to your compose file.
```yaml
services:
# [...]
server:
# [...]
volumes:
- ./web:/web
- ./local.env.yml:/local.env.yml
```
This makes the local web files and the config file available to the authentik server.
5. Run `docker compose up -d` to apply those changes to your containers.
6. `cd web`
7. Run `npm i` and then `npm run watch` to start the build process.
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/`.

89
website/docs/developer-docs/setup/full-dev-environment.md Normal file
View File

@ -0,0 +1,89 @@
---
title: Full development environment
---
## Requirements
- Python 3.12
- Poetry, which is used to manage dependencies
- Go 1.23 or newer
- Node.js 21 or newer
- PostgreSQL 14 or newer
- Redis (any recent version will do)
## 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. On macOS, run `brew install libxmlsec1 libpq`, and for the CLI tools `brew install postgresql redis node@20`
:::
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
poetry shell # Creates a python virtualenv, and activates it in a new 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.
Before committing code, 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
```
## 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.
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
ak server # 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.
:::

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

@ -0,0 +1,21 @@
---
title: Website development environment
---
If you want to only make changes to the website, you only need node.
### Prerequisites
- Node.js (any recent version should work; we use 20.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@20`
:::
### Instructions
1. Clone the git repo from https://github.com/goauthentik/authentik
2. Run `make website-install` to install the website development dependencies
3. Run `make website-watch` to start a development server to see and preview your changes
4. Finally when you're about to commit your changes, run `make website` to run the linter and auto-formatter.

44
website/docs/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) 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.