Revert "website: latest migration to new structure" (#11634)
Revert "website: latest migration to new structure (#11522)"
This reverts commit 9a89a5f94b.
This commit is contained in:
Tana M Berry
@ -1,27 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@ -1,15 +0,0 @@
|
||||
---
|
||||
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/ |
|
||||
@ -1,69 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@ -1,23 +0,0 @@
|
||||
---
|
||||
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.
|
||||
:::
|
||||
@ -1,47 +0,0 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user