From 4cc827965e8c034a6cff9f8788ef89ad29bbb94c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@gmail.com>
Date: Mon, 25 Mar 2024 10:01:03 +0100
Subject: [PATCH] add guest installation instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
---
 .changeset/wild-bobcats-speak.md              |  5 +++
 .../README.md                                 | 38 +++++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 .changeset/wild-bobcats-speak.md

diff --git a/.changeset/wild-bobcats-speak.md b/.changeset/wild-bobcats-speak.md
new file mode 100644
index 0000000000..e189bdaace
--- /dev/null
+++ b/.changeset/wild-bobcats-speak.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend-module-guest-provider': patch
+---
+
+Add installation instructions
diff --git a/plugins/auth-backend-module-guest-provider/README.md b/plugins/auth-backend-module-guest-provider/README.md
index 79591c987b..92dcc549c9 100644
--- a/plugins/auth-backend-module-guest-provider/README.md
+++ b/plugins/auth-backend-module-guest-provider/README.md
@@ -2,6 +2,44 @@
 
 This module provides a guest auth provider implementation for `@backstage/plugin-auth-backend`. This is meant to supersede the existing `'guest'` option for authentication that does not emit tokens and is completely stored as frontend state.
 
+## Installation
+
+First add the package itself to your backend dependencies:
+
+```bash
+# From your Backstage root directory
+yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-guest-provider
+```
+
+Then import it into your backend
+
+```ts
+// In packages/backend/src/index.ts
+const backend = createBackend();
+backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));
+```
+
+> [!TIP]
+> If you happen to have enabled automatic feature discovery (which is
+> very uncommon at the time of writing), you do not need to perform this step.
+
+And finally make sure to enable it in your config:
+
+```yaml
+# In app-config.yaml - NOT app-config.production.yaml
+auth:
+  providers:
+    guest: {}
+```
+
+Notice the double curly braces, which correspond to an empty object. This sets everything up using the default settings, which are:
+
+- The user is signed in as a user with the ref `user:development/guest`
+- The user only claims ownership through that ref
+- The sign in will only work in development mode; if you try to enable it in production it will refuse to sign you in for security reasons.
+
+See [the config schema](https://github.com/backstage/backstage/blob/master/plugins/auth-backend-module-guest-provider/config.d.ts) for details about the available options. If you add options to your app-config file under the `guest` key, remember to remove the double curly braces as well.
+
 ## Links
 
 - [Backstage](https://backstage.io)