website/docs: add procedural docs for RAC (#9006)

* draft

* how outposts work

* image and edits

* removed old image,edits

* new image

* formattiing tweak

* draft for review

* tweaks

* git fights

* added period

* Optimised images with calibre/image-actions

* typos

* new image, more procedurals

* updated screenshot

* final poplish

* Optimised images with calibre/image-actions

* Ken's excellent edits

* another typo

* tweak

* more tweaks

* not sure

* fix lint

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

* Update website/docs/outposts/index.mdx

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/outposts/index.mdx

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/outposts/index.mdx

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/outposts/index.mdx

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/outposts/index.mdx

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/providers/rac/how-to-rac.md

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/providers/rac/how-to-rac.md

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/providers/rac/how-to-rac.md

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/providers/rac/how-to-rac.md

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/providers/rac/how-to-rac.md

Co-authored-by: Jens L. <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* grammar

* rebase merge conflict

* merge fights

* fix embededded video syntax

* reworded for single endpoint

* undo root package

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

---------

Signed-off-by: Jens Langhammer <jens@goauthentik.io>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>
Co-authored-by: Tana M Berry <tana@goauthentik.com>
Co-authored-by: authentik-automation[bot] <135050075+authentik-automation[bot]@users.noreply.github.com>
Co-authored-by: Jens Langhammer <jens@goauthentik.io>

website/docs/outposts/index.mdx

@@ -2,30 +2,58 @@
 title: Outposts
 ---
 
-An outpost is a single deployment of an authentik component, which can be deployed in a completely separate environment:
+An outpost is a single deployment of an authentik component, essentially a service, that can be deployed anywhere that allows for a connection to the authentik API.
+
+An outpost is required if you use any of the following types of providers with your application:
 
 -   [LDAP Provider](../providers/ldap/index.md)
 -   [Proxy Provider](../providers/proxy/index.md)
 -   [RADIUS Provider](../providers/radius/index.md)
 -   [RAC Provider](../providers/rac/index.md)
 
-![](outposts.png)
+These types of providers use an outpost for increased flexibility and speed. Instead of the provider logic being implemented in authentik Core, these providers use an outpost to handle the logic, which provides improved performance.
 
-Upon creation, a service account and a token is generated. The service account only has permissions to read the outpost and provider configuration. This token is used by the Outpost to connect to authentik.
+An additional advantage of using an outpost is that outposts, like authentik itself, do not require access to the wider internet. Transactions between the application, the provider, and the outpost occur via the authentik API, and support single sign-on operations in firewalled or airgapped deployments and offline connections to remote machines that are not on the internet.
 
-authentik can manage the deployment, updating and general lifecycle of an Outpost. To communicate with the underlying platforms on which the outpost is deployed, authentik has several built-in integrations.
+An outpost is given permissions to access the authentik API using a service account and token, both of which are auto-generated when you create a new outpost. The outpost is granted rights to only the application/provider pairs configured (and other necessary related objects such as certificates).
+
+Any change made to the outpost's associated app or provider immediately triggers an event to update the configuration data stored on the outpost, via websockets. Websockets are used also by the outpost to send healthchecks to the authentik Core.
+
+## Create and configure an outpost
+
+    1. To create a new outpost, log in to authentik as an administrator, and open to the Admin interface.
+
+    2. Navigate to **Applications --> Outposts** and then click **Create**.
+
+![](outpost-create.png)
+
+    3. Define the following values:
+
+    - **Name**: a name for the new outpost
+    - **Type**: select the provider type (Proxy, LDAP, Radius, RAC)
+    - **Integration** (_optional_): select either your [Docker or Kubernetes connection](#more-about-outpost-integrations)
+    - **Applications**: select the applications that you want the outpost to serve
+    - **Advanced settings** (*optional*): For further optional configuration settings, refer to [Configuration](#configuration) below.
+
+    4. Click **Create** to save your new outpost settings and close the modal.
+
+Upon creation, a service account and a token is generated. The service account only has permissions to read the outpost and provider configuration. This token is used by the outpost to connect to authentik.
+
+### More about outpost integrations
+
+authentik can manage the deployment, updating, and general lifecycle of an outpost. To communicate with the underlying platforms on which the outpost is deployed, authentik has several built-in integrations.
 
 -   If you've deployed authentik on Docker Compose, authentik automatically creates an integration for the local docker socket (See [Docker](./integrations/docker.md)).
--   If you've deployed authentik on Kubernetes, with `kubernetesIntegration` set to true (default), authentik automatically creates an integrations for the local Kubernetes Cluster (See [Kubernetes](./integrations/kubernetes.md)).
+-   If you've deployed authentik on Kubernetes, with `kubernetesIntegration` set to true (default), authentik automatically creates an integrations for the local Kubernetes Cluster (see [Kubernetes](./integrations/kubernetes.md)).
 
-To deploy an outpost with these integrations, simply select them during the creation of an Outpost. A background task is started, which creates the container/deployment. You can see that Status on the System Tasks page.
+To deploy an outpost with these integrations, select them during the creation of an outpost. A background task is started, which creates the container/deployment. The outpost deployment can be monitored from the **Dashboards -> System Tasks** page in the Admin interface.
 
 To deploy an outpost manually, see:
 
 -   [Kubernetes](./manual-deploy-kubernetes.md)
--   [docker-compose](./manual-deploy-docker-compose.md)
+-   [Docker Compose](./manual-deploy-docker-compose.md)
 
-## Configuration
+### Configuration
 
 Outposts fetch their configuration from authentik. Below are all the options you can set, and how they influence the outpost.
 
@@ -33,8 +61,8 @@ import Configuration from "./_config.md";
 
 <Configuration />
 
-## Metrics
+## Prometheus Metrics
 
-Each authentik outpost has a Prometheus metrics endpoint accessible under port `:9300/metrics`. This endpoint is not mapped via docker, as the endpoint doesn't have any authentication.
+Each authentik outpost has a Prometheus metrics endpoint accessible under port `:9300/metrics`. This endpoint is not mapped via Docker, as the endpoint doesn't have any authentication.
 
 For the embedded outpost, the metrics of the outpost and the metrics of the core authentik server are both returned under the same endpoint.

website/docs/providers/rac/how-to-rac.md

@@ -0,0 +1,86 @@
+---
+title: Create a Remote Access Control (RAC) provider
+---
+
+:::info
+This feature is in technical preview, so please report any bugs on [GitHub](https://github.com/goauthentik/authentik/issues).
+:::
+
+The RAC provider is a highly flexible feature for accessing remote machines. This document provides instructions for the basic creation and configuration of a RAC provider within a defined scenario.
+
+Fow more information about using a RAC provider, see the [Overview](./index.md) documentation. You can also view our video on YouTube for setting up RAC.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/9wahIBRV6Ts;start=22" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+
+## Prereqisites
+
+The RAC provider requires the deployment of the [RAC Outpost](../../outposts/).
+
+## Overview workflow to create a RAC provider
+
+The typical workflow to create and configure a RAC provider is to 1. create app/provider, 2. create property mappings (that define the access credentials to each remote machine), 3. create an endpoint for each remote machine you want to connect to.
+
+Depending on whether you are connecting using RDP, SSH, or VNC, the exact configuration choices might differ, but the overall workflow applies to all RAC connections.
+
+### Step 1. Create an application and RAC provider
+
+The first step is to create the RAC app and provider.
+
+1. Log in as an admin to authentik, and go to the Admin interface.
+
+2. In the Admin interface, navigate to **Applications -> Applications**.
+
+3. Click **Create with Wizard**. Follow the [instructions](../../applications/manage_apps.md#instructions) to create your RAC application and provider.
+
+### Step 2. Create RAC property mapping
+
+Next, you need to add a property mapping for each of the remote machines you want to access. Property mappings allow you to pass information to external applications, and with RAC they are used to pass the host name, IP address, and access credentials for the remote machines.
+
+1. In the Admin interface, navigate to **Customization -> Property Mappings**.
+
+2. On the **Property Mappings** page, click **Create**.
+
+3. On the **New property mapping** modal, set the following:
+
+    - **Select Type**: RAC Property Mappings
+    - **Create RAC Property Mapping**:
+        - **Name**s: define a name for the property mapping, perhaps include the type of connection (RDP, SSH, VNC)
+        - **General settings**:
+            - **Username**: the username for the remote machine
+            - **Password**: the password for the remote machine
+        - **RDP settings**:
+            - **Ignore server certificate: select **Enabled\*\* (Depending on the setup of your RDP Server, it might be required to enable this setting.)
+            - **Enable wallpaper**: optional
+            - **Enable font smoothing**: optional
+            - **Enable full window dragging**: optional
+        - Advanced settings:
+            - **Expressions**: optional, using Python you can define custom [expressions](../../property-mappings/expression.mdx).
+
+4. Click **Finish** to save your settings and close the modal.
+
+### Step 3. Create Endpoints for the Provider
+
+Finally, you need to create an endpoint for each remote machine. Endpoints are defined within providers; connections between the remote machine and authentik are enabled through communication between the provider's endpoint and the remote machine.
+
+1. In the Admin interface navigate to **Applications -> Providers**.
+
+2. Select the RAC provider you created in Step 1 above.
+
+3. On the Provider page, under **Endpoints**, click **Create**.
+
+4. On the **Create Endpoint** modal, provide the following settings:
+
+    - **Name**: define a name for the endpoint, perhaps include the type of connection (RDP, SSH, VNC)
+    - **Protocol**: select the appropriate protocol
+    - **Host**: the host name or IP address of the system you are connecting to.
+    - **Maximum concurrent connections**: select a value or use `-1` to disable the limitation.
+    - **Property mapping**: select either the property mapping that you created in Step 2, or use one of the default settings.
+    - **Advance settings**: optional
+
+5. Click **Create** to save your settings and close the modal.
+
+### Access the remote machine
+
+To verify your configuration and access the remote machine, go to the **User interface** of your authentik instance. On the **My applications** page click the **Remote Access** application. authentik connects you to a secure shell on the remote machine, in your web browser.
+
+If you defined multiple endpoints, they are each displayed; click the endpoint for the remote machine that you want to access.

website/docs/providers/rac/index.md

@@ -1,5 +1,5 @@
 ---
-title: Remote Access (RAC) Provider
+title: Remote Access Control (RAC) Provider
 ---
 
 <span class="badge badge--primary">Enterprise</span>
@@ -7,22 +7,40 @@ title: Remote Access (RAC) Provider
 ---
 
 :::info
-This feature is in technical preview, so please report any Bugs you run into on [GitHub](https://github.com/goauthentik/authentik/issues)
+This feature is in technical preview, so please report any bugs on [GitHub](https://github.com/goauthentik/authentik/issues).
 :::
 
-The Remote access provider allows users to access Windows/macOS/Linux machines via [RDP](https://en.wikipedia.org/wiki/Remote_Desktop_Protocol)/[SSH](https://en.wikipedia.org/wiki/Secure_Shell)/[VNC](https://en.wikipedia.org/wiki/Virtual_Network_Computing).
-
 :::info
-This provider requires the deployment of the [RAC Outpost](../../outposts/)
+This provider requires the deployment of the [RAC Outpost](../../outposts/).
 :::
 
-## Endpoints
+## About the Remote Access Control (RAC) Provider
 
-Unlike other providers, where one provider-application pair must be created for each resource you wish to access, the RAC provider handles this slightly differently. For each machine (computer/server) that should be accessible, an _Endpoint_ object must be created within an RAC provider.
+The RAC provider allows users to access remote Windows, macOS, and Linux machines via [RDP](https://en.wikipedia.org/wiki/Remote_Desktop_Protocol)/[SSH](https://en.wikipedia.org/wiki/Secure_Shell)/[VNC](https://en.wikipedia.org/wiki/Virtual_Network_Computing). Just like other providers in authentik, the RAC provider is associated with an application that appears on a user's **My applications** page.
 
-The _Endpoint_ object specifies the hostname/IP of the machine to connect to, as well as the protocol to use. Additionally it is possible to bind policies to _endpoint_ objects to restrict access. Users must have access to both the application the RAC Provider is using as well as the individual endpoint.
+:::info
+Note that with RAC, you create a single application and associated provider that serves to connect with _all remote machines_ that you want to configure for access via RAC.
+:::
 
-Configuration like credentials can be specified through _settings_, which can be specified on different levels and are all merged together when connecting:
+For instructions on creating a RAC provider, refer to the [Managing RAC providers](./how-to-rac.md) documentation. You can also view our [video on YouTube](https://www.youtube.com/watch?v=9wahIBRV6Ts) for setting up a RAC.
+
+There are several components used with a RAC provider; let's take a closer look at the high-level configuration layout of these components and how they are managed using endpoints and connections.
+
+![](./rac-v3.png)
+
+The provider-application pair, the authentik server, and the authentik API are typical to all configurations. With RAC, there are some new components, namely the endpoints, the outpost, and of course the target remote machines.
+
+When a user starts the RAC application, the app communicates with the authentik server, which then connects to an instance of the outpost (the exact instance is selected dynamically based on connection load). After the outpost is selected, then the authentik server sends the outpost the instructions (based on the data you defined in the endpoint) required to connect to the remote machine.
+
+After the connection to the remote machine is made, the outpost sends a message back to the authentik server (via websockets), and the web browser opens the websocket connection to the remote machine.
+
+### Endpoints
+
+Unlike other providers, where one provider-application pair must be created for each resource you wish to access, the RAC provider handles this slightly differently. For each remote machine (computer/server) that should be accessible, you create an _Endpoint_ object within a single RAC provider. (And as mentioned above, a single provider-application pair is used for all remote connections.)
+
+The _Endpoint_ object specifies the hostname/IP of the machine to connect to, as well as the protocol to use. Additionally it is possible to bind policies to _endpoint_ objects to restrict access. Users must have access to both the application that the RAC Provider is using as well as the individual endpoint.
+
+Configuration details such as credentials can be specified through _settings_, which can be specified on different levels and are all merged together when connecting:
 
 1. Provider settings
 2. Endpoint settings
@@ -30,9 +48,9 @@ Configuration like credentials can be specified through _settings_, which can be
 4. Provider property mapping settings
 5. Endpoint property mapping settings
 
-## Connections
+### Connections
 
-Each connection is authorized through the policies bound to the application and the endpoint, and additional verification can be done with the authorization flow.
+Each connection is authorized through authentik Policy objects that are bound to the application and the endpoint. Additional verification can be done with the authorization flow.
 
 Additionally it is possible to modify the connection settings through the authorization flow. Configuration set in `connection_settings` in the flow plan context will be merged with other settings as shown above.
 

website/sidebars.js

@@ -124,7 +124,15 @@ const docsSidebar = {
                     items: ["providers/ldap/generic_setup"],
                 },
                 "providers/scim/index",
-                "providers/rac/index",
+                {
+                    type: "category",
+                    label: "RAC (Remote Access Control) Provider",
+                    link: {
+                        type: "doc",
+                        id: "providers/rac/index",
+                    },
+                    items: ["providers/rac/how-to-rac"],
+                },
             ],
         },
         {