diff --git a/docs/content/docs/(documentation)/extending/config.mdx b/docs/content/docs/(documentation)/extending/config.mdx index 30c63f8..e6b0a4e 100644 --- a/docs/content/docs/(documentation)/extending/config.mdx +++ b/docs/content/docs/(documentation)/extending/config.mdx @@ -210,6 +210,10 @@ to the latest version upon boot ([`db` mode](/usage/introduction#ui-only-mode) o } ``` + + Setting `auth.guard.enabled` to `true` without first creating a user with an admin role will lock you out of the admin portal. See [Securing Your Admin Portal](/modules/auth#securing-your-admin-portal) for the required steps before enabling the Guard. + + You can use the [CLI](/usage/cli/#getting-the-configuration-config) to get the default configuration: ```sh diff --git a/docs/content/docs/(documentation)/modules/auth.mdx b/docs/content/docs/(documentation)/modules/auth.mdx index a3b5a89..069c7bb 100644 --- a/docs/content/docs/(documentation)/modules/auth.mdx +++ b/docs/content/docs/(documentation)/modules/auth.mdx @@ -27,3 +27,50 @@ Authentication is essential for securing applications, and **bknd** provides a s - Compatible with any specification-compliant provider. With a focus on flexibility and ease of integration, bknd's authentication system offers the essentials for managing secure user access in your applications. + +--- + +## Securing Your Admin Portal + + + Enabling the Guard without first creating a user with an admin role **will lock you out of the admin portal entirely**. There is no login screen that can save you — you'll need to manually edit the database to recover. Follow the checklist below before enabling the Guard. + + +The **Guard** protects your admin portal and API endpoints by requiring authentication and proper permissions. Before enabling it, you must set up at least one user with full admin access. + +### Checklist Before Enabling Guard + +Complete these steps **in order** before turning on the Guard: + +1. **Create an admin role** with `implicit_allow: true` + - This grants full access to all permissions + - Go to Auth → Roles → Create a new role + - Enable the "Implicit Allow" toggle + +2. **Create a user** + - Go to Auth → Users → Create a new user + - Set up their email and password + +3. **Attach the admin role to the user** + - Edit the user you just created + - Assign the admin role to them + +4. **Verify you can sign in** + - Open an incognito/private browser window + - Navigate to your app and sign in with the admin user + - Confirm you have access + +5. **Now enable the Guard** + - Go to Auth → Settings + - Enable the Guard + +### Recovery: If You're Locked Out + +If you enabled the Guard without setting up an admin user, you'll need to access your database directly: + +1. Connect to your database using a database client or CLI tool +2. Find the `__bknd` table +3. Locate the row where `type = 'config'` +4. In the `json` column, set `auth.guard.enabled` to `false` +5. Restart your bknd instance +6. Complete the checklist above, then re-enable the Guard diff --git a/docs/content/docs/guide/auth/permissions.mdx b/docs/content/docs/guide/auth/permissions.mdx index 972273f..7a13350 100644 --- a/docs/content/docs/guide/auth/permissions.mdx +++ b/docs/content/docs/guide/auth/permissions.mdx @@ -9,3 +9,7 @@ tags: ["guide"] [Discord](https://discord.gg/952SFk8Tb8). + + If you enable the Guard without first creating an admin role (with `implicit_allow: true`) and attaching it to a user, you will be locked out of the admin portal. See [Securing Your Admin Portal](/modules/auth#securing-your-admin-portal) for the full checklist. + + diff --git a/docs/content/docs/guide/auth/roles.mdx b/docs/content/docs/guide/auth/roles.mdx index 8fa77fd..dd53fda 100644 --- a/docs/content/docs/guide/auth/roles.mdx +++ b/docs/content/docs/guide/auth/roles.mdx @@ -9,3 +9,7 @@ tags: ["guide"] [Discord](https://discord.gg/952SFk8Tb8). + + If you enable the Guard without first creating a role with `implicit_allow: true` and attaching it to a user, you will be locked out of the admin portal. See [Securing Your Admin Portal](/modules/auth#securing-your-admin-portal) for the full checklist. + +