Auth

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:

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

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

Setup row based authentication

Follow these steps if you want to create a "role" that allows users to only edit their own user data:

1. Create an user role
   • Go to Auth → Roles → Create a new role
   • In this case we name it "user"
   • In section "Data Permissions" switch ON the toggles data.entity.update and data.entity.read
   • For both click on the "settings" logo and past the following code in Condition

{
  "entity": "users"
}

• For Effect choose "filter" and past in the following code

{
  "id": "@user.id"
}

• Leave both the sections "Auth Permissions" and "Media Permissions" untouched
• In the section "System Permissions" switch ON all toggles except for system.build, system.info and system.config.write

2. Create a user (or use an existing)

   • Go to Auth → Users → Create a new user
   • Set up their email and password

3. Attach the user role to the created user

   • Edit the user you just created
   • Assign the "user" role to it

4. Sign in as a user

   • Open an incognito/private browser window
   • Navigate to your app and sign in with the user
   • Confirm you have access to edit your own user data