diff --git a/docs/customization/adding_attributes_to_users.md b/docs/customization/adding_attributes_to_users.md
index 05530c6f3..83488afd2 100644
--- a/docs/customization/adding_attributes_to_users.md
+++ b/docs/customization/adding_attributes_to_users.md
@@ -74,6 +74,8 @@ php spark db:table users
 
 See [Customizing User Provider](./user_provider.md).
 
+Don't forget to add the added attributes to the `$allowedFields` property.
+
 ## Update Validation Rules
 
 You need to update the [validation rules](./validation_rules.md) for registration.
diff --git a/docs/customization/user_provider.md b/docs/customization/user_provider.md
index 12246043c..379574e80 100644
--- a/docs/customization/user_provider.md
+++ b/docs/customization/user_provider.md
@@ -1,5 +1,7 @@
 # Customizing User Provider
 
+## Creating Your Own UserModel
+
 If you want to customize user attributes, you need to create your own
 [User Provider](../getting_started/concepts.md#user-providers) class.
 The only requirement is that your new class MUST extend the provided `CodeIgniter\Shield\Models\UserModel`.
@@ -13,8 +15,42 @@ php spark shield:model UserModel
 
 The class name is optional. If none is provided, the generated class name would be `UserModel`.
 
-After creating the class, set the `$userProvider` property in **app/Config/Auth.php** as follows:
+## Configuring to Use Your UserModel
+
+After creating the class, set your model classname to the `$userProvider` property
+in **app/Config/Auth.php**:
 
 ```php
 public string $userProvider = \App\Models\UserModel::class;
 ```
+
+## Customizing Your UserModel
+
+Customize your model as you like.
+
+If you add attributes, don't forget to add the attributes to the `$allowedFields`
+property.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use CodeIgniter\Shield\Models\UserModel as ShieldUserModel;
+
+class UserModel extends ShieldUserModel
+{
+    protected function initialize(): void
+    {
+        parent::initialize();
+
+        $this->allowedFields = [
+            ...$this->allowedFields,
+            'first_name', // Added
+            'last_name',  // Added
+        ];
+    }
+}
+```