website/docs: add new SSF provider docs (#13102)

* website/docs/add-secure-apps/providers/sff/index.md * draft * dir name * added procedural * first draft for review * tweak * tweak * backchannel info * tweak * edits form Ken and Dominic * not sure * tweak to rebuild * tweak * added finishing sentence * tweaks * typos --------- Co-authored-by: Tana M Berry <tana@goauthentik.com>
goauthentik · Feb 24, 2025 · ba63399 · ba63399
1 parent 86893d8
commit ba63399
Show file tree

Hide file tree

Showing 3 changed files with 113 additions and 3 deletions.
diff --git a/website/docs/add-secure-apps/providers/ssf/create-ssf-provider.md b/website/docs/add-secure-apps/providers/ssf/create-ssf-provider.md
@@ -0,0 +1,51 @@
+---
+title: Configure an SSF provider
+---
+
+The workflow to implement an SSF provider as a [backchannel provider](../../applications/manage_apps#backchannel-providers) for an application/provider pair is as follows:
+
+1. Create the SSF provider (which serves as the backchannel provider).
+2. Create an OIDC provider (which serves as the protocol provider for the application).
+3. Create the application, and assign both the OIDC provider and the SSF provider.
+
+## Create the SSF provider
+
+1. Log in to authentik as an admin, and in the Admin interface navigate to **Applications -> Providers**.
+
+2. Click **Create**.
+
+3. In the modal, select the **Provider Type** of **SSF**, and then click **Next**.
+
+4. On the **New provider** page, provide the configuration settings. Be sure to select a **Signing Key**.
+
+5. Click **Finish** to create and save the provider.
+
+## Create the OIDC provider
+
+1. Log in to authentik as an admin, and in the Admin interface navigate to **Applications -> Providers**.
+
+2. Click **Create**.
+
+3. In the modal, select the **Provider Type** of **OIDC**, and then click **Next**.
+
+4. Define the settings for the provider, and then click **Finish** to save the new provider.
+
+## Create the application
+
+1. Log in to authentik as an admin, and in the Admin interface navigate to **Applications -> Applications**.
+
+2. Click **Create**.
+
+3. Define the settings for the application:
+
+    - **Name**: define a descriptive name ofr the application.
+    - **Slug**: optionally define the internal application name used in URLs.
+    - **Group**: optionally select a group that you want to have access to this application.
+    - **Provider**: select the OIDC provider that you created.
+    - **Backchannel Providers**: select the SSF provider you created.
+    - **Policy engine mode**: define policy-based access.
+    - **UI Settings**: optionally define a launch URL, an icon, and other UI elements.
+
+4. Click **Create** to save the new application.
+
+The new application, with its OIDC provider and the backchannel SFF provider, should now appear in your list of Applications.
diff --git a/website/docs/add-secure-apps/providers/ssf/index.md b/website/docs/add-secure-apps/providers/ssf/index.md
@@ -0,0 +1,48 @@
+---
+title: Shared Signals Framework (SSF) Provider
+sidebar_label: SSF Provider
+---
+
+<span class="badge badge--preview">Preview</span>
+<span class="badge badge--version">authentik 2025.2+</span>
+&nbsp;
+
+Shared Signals Framework (SSF) is a common standard for sharing asynchronous real-time security signals and events across multiple applications and an identity provider. The framework is a collection of standards and communication processes, documented in a [specification](https://openid.net/specs/openid-sharedsignals-framework-1_0-ID3.html). SSF leverages the APIs of the application and the IdP, using privacy-protected, secure webhooks.
+
+## About Shared Signals Framework
+
+In authentik, an SSF provider allows applications to subscribe to certain types of security signals (which are then translated into SETs, or Security Event Tokens) that are captured by authentik (the IdP), and then the application can respond to each event. In this scenario, authentik acts as the _transmitter_ and the application acts as the _receiver_ of the events.
+
+Events in authentik that are tracked via SSF include when an MFA device is added or removed, logouts, sessions being revoked by Admin or user clicking logout, or credentials changed.
+
+## Example use cases
+
+A common use case for SSF is when an Admin wants to know if a user logs out of authentik, so that the user is then also automaticlaly logged out of all other work-focused applications.
+
+Another example use case is when an application uses SSF to subscribe to authorization events because the application needs to know if a user changed their password in authentik. If a user did change their password, then the application receives a POST request to write the fact that the password was changed.
+
+## About using SSF in authentik
+
+Let's look at a few details about using SSF in authentik.
+
+The SSF provider in authentik serves as a [backchannel provider](../../applications/manage_apps#backchannel-providers). Backchannel providers are used to augment the functionality of the main provider for an application. Thus you will still need to [create a typical application/provider pair](../../applications/manage_apps#instructions) (using an OIDC provider), and when creating the application, assign the SSF provider as a backchannel provider.
+
+When an authentik Admin [creates an SSF provider](./create-ssf-provider), they need to configure both the application (the receiver) and authentik (the IdP and the transmitter).
+
+### The application (the receiver)
+
+Within the application, the admin creates an SSF stream (which comprises all the signals that the app wants to subscribe to) and defines the audience, called `aud` in the specification (the URL that identifies the stream). A stream is basically an API request to authentik, which asks for a POST of all events. How that request is sent varies from application to application. An application can change or delete the stream.
+
+Note that authentik doesn't specify which events to subscribe to; instead the application defines which they want to listen for.
+
+### authentik (the transmitter)
+
+To configure authentik as a shared signals transmitter, the authentik Admin [creates a new provider](./create-ssf-provider), selecting the type "SSF", to serve as the backchannelprovider for the application.
+
+When creating the SSF provider you will need to select a signing key. This is the key that the Security Event Tokens (SET) is signed with.
+
+Optionally, you can specify a event retention time period: this value determines how long events are stored for. If an event could not be sent correctly, and retries occur, the event's expiration is also increased by this duration.
+
+:::info
+Be aware that the SET events are different events than those displayed in the authentik Admin interface under **Events**.
+:::
diff --git a/website/sidebars.js b/website/sidebars.js
@@ -200,8 +200,6 @@ export default {
                                 "add-secure-apps/providers/oauth2/github-compatibility",
                             ],
                         },
-                        "add-secure-apps/providers/saml/index",
-                        "add-secure-apps/providers/radius/index",
                         {
                             type: "category",
                             label: "Proxy Provider",
@@ -228,7 +226,6 @@ export default {
                                 },
                             ],
                         },
-                        "add-secure-apps/providers/scim/index",
                         {
                             type: "category",
                             label: "RAC (Remote Access Control) Provider",
@@ -238,6 +235,20 @@ export default {
                             },
                             items: ["add-secure-apps/providers/rac/how-to-rac"],
                         },
+                        "add-secure-apps/providers/radius/index",
+                        "add-secure-apps/providers/saml/index",
+                        "add-secure-apps/providers/scim/index",
+                        {
+                            type: "category",
+                            label: "SSF Provider",
+                            link: {
+                                type: "doc",
+                                id: "add-secure-apps/providers/ssf/index",
+                            },
+                            items: [
+                                "add-secure-apps/providers/ssf/create-ssf-provider",
+                            ],
+                        },
                     ],
                 },
                 {