From a184240855de552aaf1112214c9b88d36b5a7389 Mon Sep 17 00:00:00 2001 From: Tana M Berry Date: Thu, 29 Feb 2024 15:55:06 -0600 Subject: [PATCH] website/docs: move Applications docs up a level, other edits (#8712) * redirect Apps docs * add new wizard and video link * move in sidebar * remove link to providers * tweaks * tweak * improve wording * kens edits * removed duplicate content * reworded * further explain apps and providers * more intro words * more word tweaks * ill stop now * capitalization * fix build Signed-off-by: Jens Langhammer * final surely --------- Signed-off-by: Jens Langhammer Co-authored-by: Jens Langhammer --- .../admin/applications/ApplicationListPage.ts | 2 +- website/docs/applications/index.md | 39 +++++++++++ website/docs/applications/manage_apps.md | 52 ++++++++++++++ website/docs/core/applications.md | 68 ------------------- website/netlify.toml | 6 ++ website/sidebars.js | 10 ++- 6 files changed, 107 insertions(+), 70 deletions(-) create mode 100644 website/docs/applications/index.md create mode 100644 website/docs/applications/manage_apps.md delete mode 100644 website/docs/core/applications.md diff --git a/web/src/admin/applications/ApplicationListPage.ts b/web/src/admin/applications/ApplicationListPage.ts index 379522a4cb3f..1244a992caa1 100644 --- a/web/src/admin/applications/ApplicationListPage.ts +++ b/web/src/admin/applications/ApplicationListPage.ts @@ -3,7 +3,7 @@ import { PFSize } from "@goauthentik/app/elements/Spinner"; import { DEFAULT_CONFIG } from "@goauthentik/common/api/config"; import { uiConfig } from "@goauthentik/common/ui/config"; import "@goauthentik/components/ak-app-icon"; -import MDApplication from "@goauthentik/docs/core/applications.md"; +import MDApplication from "@goauthentik/docs/applications/index.md"; import "@goauthentik/elements/Markdown"; import "@goauthentik/elements/buttons/SpinnerButton"; import "@goauthentik/elements/forms/DeleteBulkForm"; diff --git a/website/docs/applications/index.md b/website/docs/applications/index.md new file mode 100644 index 000000000000..0860535ec38b --- /dev/null +++ b/website/docs/applications/index.md @@ -0,0 +1,39 @@ +--- +title: Applications +slug: /applications +--- + +Applications, as defined in authentik, are used to configure and separate the authorization/access control and the appearance of a specific software application in the **My applications** page. + +When a user logs into authentik, they see a list of the applications for which authentik is configured to provide authentication and authorization (the applications that that they are authorized to use). + +Applications are the "other half" of providers. They typically exist in a 1-to-1 relationship; each application needs a provider and every provider can be used with one application. + +Applications can, however, use specific, additional providers to augment the functionality of the main provider. For more information, see [Backchannel providers](./manage_apps.md#backchannel-providers). + +Furthermore, the [RAC (Remote Access Control)](../providers/rac/index.md) feature uses a single application and a single provider, but multiple "endpoints". An endpoint defines each remote machine. + +## Appearance + +Applications are displayed to users when: + +- The user has access defined via policies (or the application has no policies bound) +- A valid Launch URL is configured/could be guessed, this consists of URLs starting with http:// and https:// + +The following aspects can be configured: + +- _Name_: This is the name shown for the application card +- _Launch URL_: The URL that is opened when a user clicks on the application. When left empty, authentik tries to guess it based on the provider + + You can use placeholders in the launch url to build them dynamically based on the logged in user. For example, you can set the Launch URL to `https://goauthentik.io/%(username)s`, which will be replaced with the currently logged in user's username. + + Only applications whose launch URL starts with `http://` or `https://` or are relative URLs are shown on the users' **My applications** page. This can also be used to hide applications that shouldn't be visible on the **My applications** page but are still accessible by users, by setting the _Launch URL_ to `blank://blank`. + +- _Icon (URL)_: Optionally configure an Icon for the application + + If the authentik server does not have a volume mounted under `/media`, you'll get a text input. This accepts absolute URLs. If you've mounted single files into the container, you can reference them using `https://authentik.company/media/my-file.png`. + + If there is a mount under `/media` or if [S3 storage](../installation/storage-s3.md) is configured, you'll instead see a field to upload a file. + +- _Publisher_: Text shown below the sapplication +- _Description_: Subtext shown on the application card below the publisher diff --git a/website/docs/applications/manage_apps.md b/website/docs/applications/manage_apps.md new file mode 100644 index 000000000000..db6ad6c8a8e3 --- /dev/null +++ b/website/docs/applications/manage_apps.md @@ -0,0 +1,52 @@ +--- +title: Manage applications +--- + +Managing the applications that your team uses involves several tasks, from initially adding the application and provider, to controlling access and visibility of the application, to providing access URLs. + +## Add new applications + +Learn how to add new applications from our video or follow the instructions below. + +### Video + + + +### Instructions + +To add an application to authentik and have it display on users' **My applications** page, you can use the Application Wizard, which creates both the new application and the required provider at the same time. + +1. Log into authentik as an admin, and navigate to **Applications --> Applications**. + +2. Click **Create with Wizard**. (Alternatively, use our legacy process and click **Create**. The legacy process requires that the application and its authentication provider be configured separately.) + +3. In the **New application** wizard, define the application details, the provider type and configuration, and then click **Submit**. + +4. To manage the display of the new application on the **My applications** page, you can optionally define the bindings for a specific policy, group, or user. Note that if you do not define bindings, then all users have access to the application, For more information, refer to [authorization](#authorization). + +## Authorization + +Application access can be configured using (Policy) Bindings. Click on an application in the applications list, and select the _Policy / Group / User Bindings_ tab. There you can bind users/groups/policies to grant them access. When nothing is bound, everyone has access. You can use this to grant access to one or multiple users/groups, or dynamically give access using policies. + +By default, all users can access applications when no policies are bound. + +When multiple policies/groups/users are attached, you can configure the _Policy engine mode_ to either: + +- Require users to pass all bindings/be member of all groups (ALL), or +- Require users to pass either binding/be member of either group (ANY) + +## Hide applications + +To hide an application without modifying its policy settings or removing it, you can simply set the _Launch URL_ to `blank://blank`, which will hide the application from users. + +Keep in mind that users still have access, so they can still authorize access when the login process is started from the application. + +## Launch URLs + +To give users direct links to applications, you can now use a URL like `https://authentik.company/application/launch//`. If the user is already logged in, they will be redirected to the application automatically. Otherwise, they'll be sent to the authentication flow and, if successful, forwarded to the application. + +## Backchannel providers + +Backchannel providers can augment the functionality of applications by using additional protocols. The main provider of an application provides the SSO protocol that is used for logging into the application. Then, additional backchannel providers can be used for protocols such as [SCIM](../providers/scim/index.md) and [LDAP](../providers/ldap/index.md) to provide directory syncing. + +Access restrictions that are configured on an application apply to all of its backchannel providers. diff --git a/website/docs/core/applications.md b/website/docs/core/applications.md deleted file mode 100644 index 1cf8da196f29..000000000000 --- a/website/docs/core/applications.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Applications -slug: /applications ---- - -Applications in authentik are the other half of providers. They exist in a 1-to-1 relationship, each application needs a provider and every provider can be used with one application. Starting with authentik 2023.5, applications can use multiple providers, to augment the functionality of the main provider. For more information, see [Backchannel providers](#backchannel-providers). - -Applications are used to configure and separate the authorization / access control and the appearance in the _My applications_ page. - -## Authorization - -Application access can be configured using (Policy) Bindings. Click on an application in the applications list, and select the _Policy / Group / User Bindings_ tab. There you can bind users/groups/policies to grant them access. When nothing is bound, everyone has access. You can use this to grant access to one or multiple users/groups, or dynamically give access using policies. - -By default, all users can access applications when no policies are bound. - -When multiple policies/groups/users are attached, you can configure the _Policy engine mode_ to either - -- Require users to pass all bindings/be member of all groups (ALL), or -- Require users to pass either binding/be member of either group (ANY) - -## Appearance - -The following aspects can be configured: - -- _Name_: This is the name shown for the application card -- _Launch URL_: The URL that is opened when a user clicks on the application. When left empty, authentik tries to guess it based on the provider - - Starting with authentik 2022.2, you can use placeholders in the launch url to build them dynamically based on logged in user. For example, you can set the Launch URL to `https://goauthentik.io/%(username)s`, which will be replaced with the currently logged in user's username. - - Only applications whose launch URL starts with `http://` or `https://` or are relative URLs are shown on the users's **My applications** page. This can also be used to hide applications that shouldn't be visible on the **My applications** page but are still accessible by users, by setting the _Launch URL_ to `blank://blank`. - -- _Icon (URL)_: Optionally configure an Icon for the application - - If the authentik server does not have a volume mounted under `/media`, you'll get a text input. This accepts absolute URLs. If you've mounted single files into the container, you can reference them using `https://authentik.company/media/my-file.png`. - - If there is a mount under `/media` or if [S3 storage](../installation/storage-s3.md) is configured, you'll instead see a field to upload a file. - -- _Publisher_: Text shown below the application -- _Description_: Subtext shown on the application card below the publisher - -Applications are shown to users when - -- The user has access defined via policies (or the application has no policies bound) -- A Valid Launch URL is configured/could be guessed, this consists of URLs starting with http:// and https:// - -#### Hiding applications - -To hide applications without modifying policy settings and without removing it, you can simply set the _Launch URL_ to `blank://blank`, which will hide the application from users. - -Keep in mind, the users still have access, so they can still authorize access when the login process is started from the application. - -### Launch URLs - -:::info -Requires authentik 2022.3 -::: - -To give users direct links to applications, you can now use an URL like `https://authentik.company/application/launch//`. This will redirect the user directly if they're already logged in, and otherwise authenticate the user, and then forward them. - -### Backchannel providers - -:::info -Requires authentik version 2023.5 or later. -::: - -Backchannel providers can augment the functionality of applications by using additional protocols. The main provider of an application provides the SSO protocol that is used for logging into the application. Then, additional backchannel providers can be used for protocols such as [SCIM](../providers/scim/index.md) and [LDAP](../providers/ldap/index.md) to provide directory syncing. - -Access restrictions that are configured on an application apply to all of its backchannel providers. diff --git a/website/netlify.toml b/website/netlify.toml index da8c567f6c14..3f0dcf2c856c 100644 --- a/website/netlify.toml +++ b/website/netlify.toml @@ -38,3 +38,9 @@ command = "npm run watch" targetPort = 3000 publish = "build" + +# Moving doc files +[[redirects]] + from = "/docs/core/applications" + to = "/docs/applications" + status = 302 diff --git a/website/sidebars.js b/website/sidebars.js index 59999176daac..44ef192a17b5 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -36,7 +36,6 @@ const docsSidebar = { collapsed: true, items: [ "core/terminology", - "core/applications", "core/brands", "core/certificates", "core/geoip", @@ -57,6 +56,15 @@ const docsSidebar = { "enterprise/entsupport", ], }, + { + type: "category", + label: "Applications", + link: { + type: "doc", + id: "applications/index", + }, + items: ["applications/manage_apps"], + }, { type: "category", label: "Providers",