mirror of
https://github.com/bknd-io/bknd/
synced 2026-08-02 16:16:02 +00:00
Jonas Perusquia Morales
96 lines
3.5 KiB
Plaintext
96 lines
3.5 KiB
Plaintext
---
|
|
title: "Auth"
|
|
description: "Easily implement reliable authentication strategies."
|
|
tags: ["documentation"]
|
|
---
|
|
|
|
<Callout type="info" title="The documentation is currently a work in progress">
|
|
Check back soon — or stay updated on our progress on
|
|
[GitHub](https://github.com/bknd-io/bknd) and join the conversation in
|
|
[Discord](https://discord.gg/952SFk8Tb8).
|
|
</Callout>
|
|
|
|
Authentication is essential for securing applications, and **bknd** provides a straightforward approach to implementing robust strategies.
|
|
|
|
### **Core Features**
|
|
|
|
- Automatically creates a `user` entity, with support for customizable fields.
|
|
- Authenticates users based on configurable strategies.
|
|
- Generates JWTs according to specified configurations.
|
|
- Provides session management for maintaining user authentication state.
|
|
|
|
### **Supported Authentication Strategies**
|
|
|
|
- **Email/Password**: Supports plain and SHA-256 password hashing (bcrypt planned for future
|
|
releases).
|
|
- **OAuth/OIDC**: Works with providers like Google and GitHub.
|
|
- 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.
|
|
|
|
---
|
|
|
|
## Server Module: `module.auth`
|
|
|
|
### `auth.changePassword([userId], [password])`
|
|
|
|
To change a user's password, use the `changePassword` method:
|
|
|
|
```ts
|
|
await app.module.auth.changePassword(user.id, password);
|
|
```
|
|
|
|
This method updates the password for the specified user.
|
|
- `userId`: The ID of the user whose password should be changed.
|
|
- `password`: The new password value.
|
|
|
|
This method throws an error if:
|
|
- The user with the given `userId` is not found.
|
|
- The user's authentication strategy is not `"password"` (e.g. the user registered via an OAuth provider).
|
|
|
|
|
|
## Securing Your Admin Portal
|
|
|
|
<Callout type="warn" title="Do not enable the Guard without an admin user">
|
|
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.
|
|
</Callout>
|
|
|
|
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
|