From 53f8699deb229574286ca5a521de5e2b4881e640 Mon Sep 17 00:00:00 2001 From: Jens L Date: Fri, 19 Apr 2024 15:32:48 +0200 Subject: [PATCH] website/docs: 2024.4 release notes (#9267) * website/docs: 2024.4 release notes WIP Signed-off-by: Jens Langhammer * fix .next Signed-off-by: Jens Langhammer * reword Signed-off-by: Jens Langhammer * add python api client Signed-off-by: Jens Langhammer * fix consistency Signed-off-by: Jens Langhammer * expand scim docs Signed-off-by: Jens Langhammer * add release notes to sidebar Signed-off-by: Jens Langhammer * update release notes and add disclaimer Signed-off-by: Jens Langhammer * add disclaimer to template Signed-off-by: Jens Langhammer * add list of API Clients to developer docs Signed-off-by: Jens Langhammer * add performance improvements Signed-off-by: Jens Langhammer * fix build Signed-off-by: Jens Langhammer --------- Signed-off-by: Jens Langhammer --- website/developer-docs/api/clients.md | 15 +++ website/docs/flow/stages/source/index.md | 8 ++ .../providers/oauth2/client_credentials.md | 4 +- website/docs/releases/2024/next.md | 60 ---------- website/docs/releases/2024/v2024.4.md | 104 ++++++++++++++++++ website/docs/releases/_template.md | 6 + website/integrations/sources/ldap/index.md | 4 +- website/integrations/sources/oauth/index.md | 2 +- website/integrations/sources/scim/index.md | 12 +- website/sidebars.js | 3 +- website/sidebarsDev.js | 1 + 11 files changed, 149 insertions(+), 70 deletions(-) create mode 100644 website/developer-docs/api/clients.md delete mode 100644 website/docs/releases/2024/next.md create mode 100644 website/docs/releases/2024/v2024.4.md diff --git a/website/developer-docs/api/clients.md b/website/developer-docs/api/clients.md new file mode 100644 index 0000000000..5b483336a6 --- /dev/null +++ b/website/developer-docs/api/clients.md @@ -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/ | diff --git a/website/docs/flow/stages/source/index.md b/website/docs/flow/stages/source/index.md index ce703868fc..0a7bfbf21c 100644 --- a/website/docs/flow/stages/source/index.md +++ b/website/docs/flow/stages/source/index.md @@ -38,6 +38,14 @@ It is very important that the configured source's authentication and enrollment This is because the Source stage works by appending a [dynamic in-memory](../../../core/terminology.md#dynamic-in-memory-stage) stage to the source's flow, so having a [User login stage](../user_login/index.md) bound will cause the source's flow to not resume the original flow it was started from, and instead directly authenticating the pending user. +### Example use case + +This stage can be used to leverage an external OAuth/SAML identity provider. + +For example, you can authenticate users by routing them through a custom device-health solution. + +Another use case is to route users to authenticate with your legacy (Okta, etc) IdP and then use the returned identity and attributes within authentik as part of an authorization flow, for example as part of an IdP migration. For authentication/enrollment this is also possible with an [OAuth](../../../../integrations/sources/oauth/)/[SAML](../../../../integrations/sources/saml/) source by itself. + ### Options #### Source diff --git a/website/docs/providers/oauth2/client_credentials.md b/website/docs/providers/oauth2/client_credentials.md index 4a1c7b178a..95ca1c5695 100644 --- a/website/docs/providers/oauth2/client_credentials.md +++ b/website/docs/providers/oauth2/client_credentials.md @@ -23,9 +23,9 @@ password=my-token This will return a JSON response with an `access_token`, which is a signed JWT token. This token can be sent along requests to other hosts, which can then validate the JWT based on the signing key configured in authentik. -Starting with authentik 2024.next, it is also possible to encode the username and token of the user to authenticate with, separated with a colon, into a base64 string and pass it as `client_secret` value. +Starting with authentik 2024.4, it is also possible to encode the username and token of the user to authenticate with, separated with a colon, into a base64 string and pass it as `client_secret` value. -In addition to that, with authentik 2024.next it is also possible to pass the configured `client_secret` value, which will automatically generate a service account user for which the JWT token will be issued. +In addition to that, with authentik 2024.4 it is also possible to pass the configured `client_secret` value, which will automatically generate a service account user for which the JWT token will be issued. ### JWT-authentication diff --git a/website/docs/releases/2024/next.md b/website/docs/releases/2024/next.md deleted file mode 100644 index 2dbd959be0..0000000000 --- a/website/docs/releases/2024/next.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Release next -slug: /releases/next ---- - - - -## Breaking changes - -### Manual action is required - -### Manual action may be required - -- **Configuration options migrated to the Admin interface** - - The following config options have been moved from the config file and can now be set using the Admin interface (under **System** -> **Settings**) or the API: - - - `AUTHENTIK_DEFAULT_TOKEN_LENGTH` - - When upgrading to 2024.next, the currently configured options will be automatically migrated to the database, and can be removed from the `.env` or helm values file afterwards. - -## New features - -- Configurable app password token expiring - - Thanks @jmdilly for contributing this feature! - - Admins can now configure the default token duration (which defaults to `minutes=30`) in the admin interface as specified above. This value can also be overridden per-user with the `goauthentik.io/user/token-maximum-lifetime` attribute. - -## Upgrading - -This release does not introduce any new requirements. - -### docker-compose - -To upgrade, download the new docker-compose file and update the Docker stack with the new version, using these commands: - -```shell -wget -O docker-compose.yml https://goauthentik.io/version/xxxx.x/docker-compose.yml -docker compose up -d -``` - -The `-O` flag retains the downloaded file's name, overwriting any existing local file with the same name. - -### Kubernetes - -Upgrade the Helm Chart to the new version, using the following commands: - -```shell -helm repo update -helm upgrade authentik authentik/authentik -f values.yaml --version ^xxxx.x -``` - -## Minor changes/fixes - - - -## API Changes - - diff --git a/website/docs/releases/2024/v2024.4.md b/website/docs/releases/2024/v2024.4.md new file mode 100644 index 0000000000..de6905fd96 --- /dev/null +++ b/website/docs/releases/2024/v2024.4.md @@ -0,0 +1,104 @@ +--- +title: Release 2024.4 +slug: /releases/2024.4 +--- + +:::::note +2024.4 has not been released yet! We're publishing these release notes as a preview of what's to come, and for our awesome beta testers trying out release candidates. + +To try out the release candidate, replace your Docker image tag with the latest release candidate number, such as 2024.4.0-rc1. You can find the latest one in [the latest releases on GitHub](https://github.com/goauthentik/authentik/releases). If you don't find any, it means we haven't released one yet. +::::: + +## Highlights + +- **OAuth/SAML as authentication factor** Enterprise Use an external provider as part of an MFA authentication flow, including custom implementations + +- **SCIM Source** Preview Provision users and groups in authentik using an SCIM API + +- **Configurable WebAuthn device restrictions** Configure which types of WebAuthn devices can be used to enroll and validate for different authorization levels. + +- **Performance improvements** The API Endpoints to list Users, Groups, and Events have been optimized by 100%, y% and z% respectively + +## Breaking changes + +### Manual action may be required + +- **Configuration options migrated to the Admin interface** + + The following config options have been moved from the config file and can now be set using the Admin interface (under **System** -> **Settings**) or the API: + + - `AUTHENTIK_DEFAULT_TOKEN_LENGTH` + + When upgrading to 2024.4, the currently configured options will be automatically migrated to the database, and can be removed from the `.env` or helm values file afterwards. + +## New features + +- **Source stage** Enterprise + + The source stage allows for an inclusion of a source as part of a flow. This can be used to link a user to a source as part of their authentication/enrollment, or it can be used as an external multi-factor to provide device health attestation for example. + + For details refer to [Source stage](../../flow/stages/source/index.md) + +- **SCIM Source** Preview + + Provision users and groups in authentik using an SCIM API. + + For details refer to [SCIM Source](../../../integrations/sources/scim/) + +- **Configurable WebAuthn device restrictions** + + Configure which types of WebAuthn devices can be used to enroll and validate for different authorization levels. + + For details refer to [WebAuthn authenticator setup stage](../../flow/stages/authenticator_webauthn/index.md) + +- **Revamped UI for log messages** + + Log messages from several API endpoints are now shown with much greater detail, which helps with implementing custom policies and property mappings. + +- **Python API Client** + + There's now an official API Client for Python: https://pypi.org/project/authentik-client/. This API Client can be used to create/update/delete objects within authentik as well as using the Flow executor to authenticate. + +- **Configure LDAP sources to not store hashed password in authentik** + + When authentik is configured to federate with an LDAP source, upon authentication, authentik hashed the password and stored it in its own database. This allows authentication to function when LDAP is unreachable. Admins can now configure this behavior for when this is not desirable. + + For details refer to [LDAP Source](../../../integrations/sources/ldap/) + +- **Configurable app password token expiring** + + Thanks @jmdilly for contributing this feature! + + Admins can now configure the default token duration (which defaults to `minutes=30`) in the admin interface as specified above. This value can also be overridden per-user with the `goauthentik.io/user/token-maximum-lifetime` attribute. + +## Upgrading + +This release does not introduce any new requirements. + +### docker-compose + +To upgrade, download the new docker-compose file and update the Docker stack with the new version, using these commands: + +```shell +wget -O docker-compose.yml https://goauthentik.io/version/2024.4/docker-compose.yml +docker compose up -d +``` + +The `-O` flag retains the downloaded file's name, overwriting any existing local file with the same name. + +### Kubernetes + +Upgrade the Helm Chart to the new version, using the following commands: + +```shell +helm repo update +helm upgrade authentik authentik/authentik -f values.yaml --version ^2024.4 +``` + +## Minor changes/fixes + + + +## API Changes + + diff --git a/website/docs/releases/_template.md b/website/docs/releases/_template.md index 899529d715..9496266f28 100644 --- a/website/docs/releases/_template.md +++ b/website/docs/releases/_template.md @@ -3,6 +3,12 @@ title: Release xxxx.x slug: "/releases/xxxx.x" --- +:::::note +xxxx.x has not been released yet! We're publishing these release notes as a preview of what's to come, and for our awesome beta testers trying out release candidates. + +To try out the release candidate, replace your Docker image tag with the latest release candidate number, such as xxxx.x.0-rc1. You can find the latest one in [the latest releases on GitHub](https://github.com/goauthentik/authentik/releases). If you don't find any, it means we haven't released one yet. +::::: + ## New features diff --git a/website/integrations/sources/ldap/index.md b/website/integrations/sources/ldap/index.md index 426e9e0bee..ed7e66afc8 100644 --- a/website/integrations/sources/ldap/index.md +++ b/website/integrations/sources/ldap/index.md @@ -1,11 +1,9 @@ --- -title: LDAP +title: LDAP Source --- Sources allow you to connect authentik to an existing user directory. They can also be used for social logins, using external providers such as Facebook, Twitter, etc. -## LDAP Source - This source allows you to import users and groups from an LDAP Server. :::info diff --git a/website/integrations/sources/oauth/index.md b/website/integrations/sources/oauth/index.md index 4a0014c469..34c7e29ca1 100644 --- a/website/integrations/sources/oauth/index.md +++ b/website/integrations/sources/oauth/index.md @@ -1,5 +1,5 @@ --- -title: OAuth +title: OAuth Source --- :::note diff --git a/website/integrations/sources/scim/index.md b/website/integrations/sources/scim/index.md index 1f577d7f07..5ef94ea12b 100644 --- a/website/integrations/sources/scim/index.md +++ b/website/integrations/sources/scim/index.md @@ -1,5 +1,5 @@ --- -title: SCIM source +title: SCIM Source --- :::info @@ -10,14 +10,20 @@ The SCIM source allows other applications to directly create users and groups wi The base SCIM URL is in the format of `https://authentik.company/source/scim//v2`. Authentication is done via Bearer tokens that are generated by authentik. When an SCIM source is created, a service account is created and a matching token is provided. +## First steps + +To set up an SCIM source, log in as an administrator into authentik. Navigate to **Directory->Federation & Social login**, and click on **Create**. Select the **SCIM Source** type in the wizard, and give the source a name. + +After the source is created, click on the name of the source in the list, and you will see the **SCIM Base URL** which is used by the SCIM client. Use the **Click to copy token** button to copy the token which is used by the client to authenticate SCIM requests. + ## Supported Options & Resource types ### `/v2/Users` -Endpoint to list, create, patch, and delete users. +Endpoint to list, create, update and delete users. ### `/v2/Groups` -Endpoint to list, create, patch, and delete groups. +Endpoint to list, create, update and delete groups. There is also the `/v2/ServiceProviderConfig` and `/v2/ResourceTypes`, which is used by SCIM-enabled applications to find out which features authentik supports. diff --git a/website/sidebars.js b/website/sidebars.js index dc36186c36..0ee041b681 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -343,13 +343,14 @@ const docsSidebar = { description: "Release notes for recent authentik versions", }, items: [ + "releases/2024/v2024.4", "releases/2024/v2024.2", "releases/2023/v2023.10", - "releases/2023/v2023.8", { type: "category", label: "Previous versions", items: [ + "releases/2023/v2023.8", "releases/2023/v2023.6", "releases/2023/v2023.5", "releases/2023/v2023.4", diff --git a/website/sidebarsDev.js b/website/sidebarsDev.js index a5043d56bc..229bbc59d6 100644 --- a/website/sidebarsDev.js +++ b/website/sidebarsDev.js @@ -47,6 +47,7 @@ module.exports = { "api/making-schema-changes", "api/websocket", "api/browser", + "api/clients", ], }, {