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

website: latest migration to new structure (#11522)

Browse Source 
* first pass

* dependency shenanigans

* move blueprints

* few broken links

* change config the throw errors

* internal file edits

* fighting links

* remove sidebarDev

* fix subdomain

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

* fix relative URL

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

* fix mismatched package versions

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

* fix api reference build

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

* test tweak

* links hell

* more links hell

* links hell2

* yep last of the links

* last broken link fixed

* re-add cves

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

* add devdocs redirects

* add dir

* tweak netlify.toml

* move latest 2 CVES into dir

* fix links to moved cves

* typoed title fix

* fix link

* remove banner

* remove committed api docs

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* integrations: remove version dropdown

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Update Makefile

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* change doc links in web as well

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix some more docs paths

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* fix more docs paths

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* ci: require ci-web.build for merging

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

* Revert "ci: require ci-web.build for merging"

This reverts commit b99a4842a9.

* remove sluf for Application

* put slug back in

* minor fix to trigger deploy

---------

Signed-off-by: Jens Langhammer <jens@goauthentik.io>
Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
Co-authored-by: Tana M Berry <tana@goauthentik.com>
Co-authored-by: Jens Langhammer <jens@goauthentik.io>
Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>
This commit is contained in:
Tana M Berry
2024-10-08 14:07:19 -05:00
committed by GitHub
parent 9200a598ec
commit 9a89a5f94b
336 changed files with 2624 additions and 871 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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