Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Revert developer docs changes; keep docs/plans

Łukasz Adamczyk9830f33af4a9
diff --git a/docs/developer/admin/admin.mdx b/docs/developer/admin/admin.mdx
index f088d686fb..0dfec62954 100644
--- a/docs/developer/admin/admin.mdx
+++ b/docs/developer/admin/admin.mdx
@@ -201,7 +201,7 @@ bin/rails g controller Spree::Admin::Brands --skip-routes
Admin users must be authenticated to access the dashboard. Spree supports:
-- Built-in `has_secure_password` authentication (the gem-owned `Spree::AdminUser` model)
+- Built-in Devise authentication
- Custom authentication adapters
- SSO integration
diff --git a/docs/developer/admin/authentication.mdx b/docs/developer/admin/authentication.mdx
index e558d7d619..da3f518cb1 100644
--- a/docs/developer/admin/authentication.mdx
+++ b/docs/developer/admin/authentication.mdx
@@ -1,32 +1,59 @@
---
title: Admin Panel Authentication
sidebarTitle: Authentication
-description: How to customize authentication for the Spree admin
+description: How to customize the Spree admin panel authentication
---
-Spree uses a separate model for admin/staff accounts (`Spree::AdminUser`) from storefront customers (`Spree::Customer`) — the default since Spree 5.2. Both are gem-owned and backed by [`has_secure_password`](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html); the admin dashboard authenticates against the Admin API with JWT access + refresh tokens, so no setup is required for the default.
+Spree allows you to use a different model for the admin panel than the storefront (that's the default since Spree 5.2).
+Here you can find how to customize the admin panel authentication to use a different model.
-You only need the steps below if you want the admin to authenticate against your **own** admin model.
+Let's assume you have an existing `AdminUser` model in your application and you're using Devise for authentication.
-## Using your own admin model
-
-Point `Spree.admin_user_class` at your model in `config/initializers/spree.rb`:
+In `config/initializers/spree.rb` file, add the following line:
```ruby
-Spree.admin_user_class = 'MyApp::AdminUser'
+Spree.admin_user_class = 'AdminUser'
```
-On that model, include the admin concern (roles, permissions, store access) and add `has_secure_password`:
+This will tell Spree to use your `AdminUser` model for the admin panel. You will also need to add the following line in that model file:
```ruby
-# app/models/my_app/admin_user.rb
-class MyApp::AdminUser < ApplicationRecord
- has_secure_password validations: false
+include Spree::UserMethods
+```
- include Spree::AdminUserMethods
+In your `config/initializers/routes.rb` file, you will need to define devise routes for the 2nd model:
+
+```ruby
+Spree::Core::Engine.routes.prepend_routes do
+ # Admin authentication
+ devise_for(
+ Spree.admin_user_class.model_name.singular_route_key,
+ class_name: Spree.admin_user_class.to_s,
+ controllers: {
+ sessions: 'spree/admin/user_sessions',
+ passwords: 'spree/admin/user_passwords'
+ },
+ skip: :registrations,
+ path: :admin_user,
+ router_name: :spree
+ )
end
```
-If the model keeps an existing password column (for example `encrypted_password`), bridge it as described in [Authentication](/developer/customization/authentication#keeping-an-existing-password-column).
+And now in your `lib/spree/authentication_helpers.rb` file, please replace the following lines:
+
+```diff
+ def spree_admin_login_path(opts = {})
+- spree_login_path(opts)
++ new_admin_user_session_path(opts)
+ end
+
+ def spree_admin_logout_path(opts = {})
+- spree_logout_path(opts)
++ destroy_admin_user_session_path(opts)
+ end
+```
+
+Now when attempting to access the admin panel, you will be redirected to the dedicated admin panel login page.
-The admin dashboard signs in through the Admin API auth endpoints (`POST /api/v3/admin/auth/login`, plus `refresh` and `logout`); custom providers plug in via `Spree.admin_authentication_strategies` (see [Custom authentication providers](/developer/customization/authentication#custom-authentication-providers)).
+![Admin panel login page](/images/developer/admin/admin_panel_login.png)
\ No newline at end of file
diff --git a/docs/developer/admin/extending-ui.mdx b/docs/developer/admin/extending-ui.mdx
index 303a33e90f..a2a8923049 100644
--- a/docs/developer/admin/extending-ui.mdx
+++ b/docs/developer/admin/extending-ui.mdx
@@ -431,7 +431,7 @@ Here's a list of all places you can inject your custom code:
#### Variables
- <ParamField path="user" type="Spree.customer_class">
+ <ParamField path="user" type="Spree.user_class">
The customer displayed on the page.
</ParamField>
diff --git a/docs/developer/admin/tables.mdx b/docs/developer/admin/tables.mdx
index 5af38da200..92b3252035 100644
--- a/docs/developer/admin/tables.mdx
+++ b/docs/developer/admin/tables.mdx
@@ -501,7 +501,7 @@ Spree registers tables for all built-in resources:
| `:products` | `Spree::Product` |
| `:orders` | `Spree::Order` |
| `:checkouts` | `Spree::Order` (draft) |
-| `:users` | `Spree.customer_class` |
+| `:users` | `Spree.user_class` |
| `:promotions` | `Spree::Promotion` |
| `:customer_returns` | `Spree::CustomerReturn` |
| `:option_types` | `Spree::OptionType` |
diff --git a/docs/developer/advanced/adding_spree_to_rails_app.mdx b/docs/developer/advanced/adding_spree_to_rails_app.mdx
index 198578994a..50a9d17b17 100644
--- a/docs/developer/advanced/adding_spree_to_rails_app.mdx
+++ b/docs/developer/advanced/adding_spree_to_rails_app.mdx
@@ -38,20 +38,19 @@ Spree uses a modular installation approach. First install the core, then add opt
### Install core Spree
-This installs core models, API, CLI, and the gem-owned authentication models (`Spree::Customer` and `Spree::AdminUser`):
+This installs core models, API, CLI, and authentication:
```bash
-bin/rails g spree:install
+bin/rails g spree:install --user_class=Spree::User --authentication=devise
```
-To authenticate against your own user model instead of the defaults, pass `--user_class` (see [Authentication](/developer/customization/authentication)).
-
**Core installation options:**
| Option | Description |
|--------|-------------|
-| `user_class` | The customer model class (default: `Spree::Customer`) |
-| `admin_user_class` | The admin model class (default: `Spree::AdminUser`) |
+| `user_class` | The class for your users, eg. `Spree::User` or `User` |
+| `admin_user_class` | The class for admin users (defaults to `user_class`) |
+| `authentication` | Authentication gem: `devise` or `custom` |
| `migrate` | Whether to run migrations (default: true) |
| `seed` | Whether to run the seed file (default: true) |
| `sample` | Whether to add sample data (default: false) |
@@ -62,6 +61,7 @@ To authenticate against your own user model instead of the defaults, pass `--use
```bash
bin/rails g spree:admin:install
+bin/rails g spree:admin:devise # if using Devise authentication
```
### Add sample data (optional)
diff --git a/docs/developer/core-concepts/events.mdx b/docs/developer/core-concepts/events.mdx
index a02d777ead..cb06b4b4d3 100644
--- a/docs/developer/core-concepts/events.mdx
+++ b/docs/developer/core-concepts/events.mdx
@@ -256,7 +256,7 @@ Models with lifecycle events enabled include: `Order`, `Payment`, `Price`, `Ship
| `user.updated` | User was updated |
| `user.deleted` | User was deleted |
-When `Spree.admin_user_class` differs from `Spree.customer_class`, admin users publish the equivalent `admin.*` events (see the Admin Events table below).
+When `Spree.admin_user_class` differs from `Spree.user_class`, admin users publish the equivalent `admin.*` events (see the Admin Events table below).
### Admin Events
diff --git a/docs/developer/core-concepts/imports-exports.mdx b/docs/developer/core-concepts/imports-exports.mdx
index e0f8775ffa..2c9d83454f 100644
--- a/docs/developer/core-concepts/imports-exports.mdx
+++ b/docs/developer/core-concepts/imports-exports.mdx
@@ -472,7 +472,7 @@ module Spree
def find_or_create_user
email = attributes['email'].strip.downcase
- Spree.customer_class.find_or_create_by!(email: email)
+ Spree.user_class.find_or_create_by!(email: email)
end
def find_plan
diff --git a/docs/developer/core-concepts/users.mdx b/docs/developer/core-concepts/users.mdx
index 20c4bd1825..05a6ec8d24 100644
--- a/docs/developer/core-concepts/users.mdx
+++ b/docs/developer/core-concepts/users.mdx
@@ -1,6 +1,6 @@
---
title: Users
-description: How Spree models customer and admin users — account data, roles, abilities, and access permissions across stores.
+description: How Spree models customer and admin users — Devise authentication, account data, roles, abilities, and access permissions across stores.
---
## Overview
@@ -12,11 +12,11 @@ Spree has two separate user types:
| User type | Class | Default |
|-----------|-------|---------|
-| Customers | `Spree.customer_class` | `Spree::Customer` |
+| Customers | `Spree.user_class` | `Spree::User` |
| Admins | `Spree.admin_user_class` | `Spree::AdminUser` |
<Info>
-You can use your own user classes. See the [Customize Authentication guide](/developer/customization/authentication) for details. `Spree.user_class` still works as a deprecated alias for `Spree.customer_class` and will be removed in Spree 6.1.
+You can use your own user classes. See the [Customize Authentication guide](/developer/customization/authentication) for details.
</Info>
## Customers
diff --git a/docs/developer/customization/authentication.mdx b/docs/developer/customization/authentication.mdx
index b60f79eebd..ae7bb11d99 100644
--- a/docs/developer/customization/authentication.mdx
+++ b/docs/developer/customization/authentication.mdx
@@ -1,54 +1,103 @@
---
title: Authentication
-description: How Spree authenticates customers and admins, and how to plug in your own user model or authentication provider.
+description: Integrate Spree with a custom authentication setup, including Devise, an existing user model, OmniAuth providers, and JWT or OAuth API tokens.
version: v5
---
-Spree ships with built-in, gem-owned authentication models — `Spree::Customer` (storefront customers) and `Spree::AdminUser` (staff) — backed by Rails' [`has_secure_password`](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html). If you installed Spree following the [Quickstart guide](/developer/quickstart), authentication is already set up and you can skip this page.
+If you installed Spree following the [Quickstart guide](/developer/quickstart), you can completely skip this step - you are all set and integrated with the [Devise](https://github.com/plataformatec/devise) gem.
-You only need the steps below if you want Spree to authenticate against your **own** user model — for example a shared/SSO user table, or an existing application you're adding Spree to.
+However if you're adding Spree to an existing application that has its own authentication system, you will need to follow these steps.
-## Using your own user model
+## Using Devise
-Point `Spree.customer_class` (and optionally `Spree.admin_user_class`) at your model in `config/initializers/spree.rb`:
+If you're currently using [Devise](https://github.com/plataformatec/devise) for authentication, you can follow the steps below to integrate Spree with your existing authentication system.
+
+Firstly set your `User` class as `Spree.user_class` in your `config/initializers/spree.rb` file:
```ruby
-Spree.customer_class = 'MyApp::User'
+Spree.user_class = 'User'
+```
+
+Now, run the generator to set up Spree integration with Devise:
+
+<CodeGroup>
+
+```bash Spree CLI (Docker)
+spree generate spree:authentication:devise
+```
+
+```bash Without Spree CLI
+bin/rails g spree:authentication:devise
```
-> `Spree.user_class` still works as a deprecated alias for `Spree.customer_class` and will be removed in Spree 6.1.
+</CodeGroup>
-On that model, include the Spree customer concern — a single include that brings in addresses, payment sources, orders, wishlists, and store credit — and add `has_secure_password`:
+This will create a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You can then use this file to customize the routes to your liking. It should automatically pick up standard Devise routes.
+
+Secondly, this generator will add necessary modules to your `User` model.
```ruby
-# app/models/my_app/user.rb
-class MyApp::User < ApplicationRecord
- has_secure_password validations: false
+# app/models/user.rb
+class User < ApplicationRecord
+ # ... your existing code ...
- include Spree::CustomerMethods
+ include Spree::UserAddress
+ include Spree::UserMethods
+ include Spree::UserPaymentSource
end
```
-`Spree::CustomerMethods` absorbs the former `Spree::UserAddress` and `Spree::UserPaymentSource` concerns, so this single include is all that's required.
+This will ensure that your `User` model can be used as a Spree user.
+
+This generator will also add 2 new lines to your Spree initializer file:
+
+```ruby
+Devise.parent_controller = "Spree::BaseController"
+Devise.parent_mailer = "Spree::BaseMailer"
+```
+
+This ensures that Devise will use Spree storefront layout for login/signup/etc and use Spree mailer layout for sending emails so they'll match your Storefront branding.
-### Keeping an existing password column
+If you have more complex setup, you can remove these lines and customize the routes and mailer in your own initializer file.
-If your model already stores its password digest in a column other than `password_digest` — for example the `encrypted_password` column from a Devise-based app — bridge it so `has_secure_password` can read it. Either alias the column:
+## Using Custom Authentication
+
+If you're using a custom authentication system, you can follow the steps below to integrate Spree with your existing authentication system.
+
+Firstly set your `User` class as `Spree.user_class` in your `config/initializers/spree.rb` file:
```ruby
-class MyApp::User < ApplicationRecord
- has_secure_password validations: false
- include Spree::CustomerMethods
+Spree.user_class = 'User'
+```
- alias_attribute :password_digest, :encrypted_password
-end
+Now, run the generator to set up Spree integration with your custom authentication system:
+
+<CodeGroup>
+
+```bash Spree CLI (Docker)
+spree generate spree:authentication:custom
```
-or rename the column to `password_digest` in a migration. A plain bcrypt digest (such as Devise's `encrypted_password` with no pepper configured) is read directly by `has_secure_password`, so existing passwords keep working with no reset.
+```bash Without Spree CLI
+bin/rails g spree:authentication:custom
+```
-## Custom authentication providers
+</CodeGroup>
-Spree authenticates through pluggable strategies — `Spree.store_authentication_strategies` and `Spree.admin_authentication_strategies` — which default to email + password. To plug in an external provider (Auth0, Clerk, SSO, and so on), implement a `Spree::Authentication::Strategies::BaseStrategy` subclass and register it. See [Custom API authentication](/developer/how-to/custom-api-authentication) for a worked example.
+This will create a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You will need to customize this file to fit your needs.
+
+Secondly, this generator will add necessary modules to your `User` model.
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+ # ... your existing code ...
+
+ include Spree::UserAddress
+ include Spree::UserMethods
+ include Spree::UserPaymentSource
+end
+```
## Admin Panel authentication
diff --git a/docs/developer/customization/permissions.mdx b/docs/developer/customization/permissions.mdx
index e08cef551a..0b85f53590 100644
--- a/docs/developer/customization/permissions.mdx
+++ b/docs/developer/customization/permissions.mdx
@@ -159,7 +159,7 @@ Spree::Role.find_or_create_by(name: 'warehouse_staff')
Assign a role to a user:
```ruby
-user = Spree.customer_class.find_by(email: '[email protected]')
+user = Spree.user_class.find_by(email: '[email protected]')
role = Spree::Role.find_by(name: 'customer_service')
user.spree_roles << role
```
@@ -221,7 +221,7 @@ class CustomAbility < Spree::Ability
def initialize(user, options = {})
alias_cancan_delete_action
- @user = user || Spree.customer_class.new
+ @user = user || Spree.user_class.new
@store = options[:store] || Spree::Current.store
if @user.respond_to?(:has_spree_role?) && @user.has_spree_role?('admin')
@@ -239,7 +239,7 @@ class CustomAbility < Spree::Ability
def apply_customer_service_permissions(user)
can :manage, Spree::Order
- can [:read, :admin], Spree.customer_class
+ can [:read, :admin], Spree.user_class
end
end
```
diff --git a/docs/developer/customization/quickstart.mdx b/docs/developer/customization/quickstart.mdx
index 05e4646f41..d23da7806a 100644
--- a/docs/developer/customization/quickstart.mdx
+++ b/docs/developer/customization/quickstart.mdx
@@ -149,7 +149,7 @@ Spree is a flexible platform allowing you to customize every part of it to suit
<Accordion title="Authentication">
**Best for:** Using your own user model or authentication system.
- Spree ships gem-owned `has_secure_password` models by default, and lets you point it at your own user model or authentication provider instead.
+ Spree allows you to use your own authentication system instead of the default Devise-based one.
You can find more information in the [Authentication](authentication) section.
</Accordion>
diff --git a/docs/developer/how-to/custom-api-authentication.mdx b/docs/developer/how-to/custom-api-authentication.mdx
index 9de0c7aa54..3f7c188bf4 100644
--- a/docs/developer/how-to/custom-api-authentication.mdx
+++ b/docs/developer/how-to/custom-api-authentication.mdx
@@ -25,7 +25,7 @@ The mechanism is identical for both surfaces. A strategy you write works on eith
| | Store API (customers) | Admin API (staff) |
|---|---|---|
| Registry | `Spree.store_authentication_strategies` | `Spree.admin_authentication_strategies` |
-| User class | `Spree.customer_class` | `Spree.admin_user_class` |
+| User class | `Spree.user_class` | `Spree.admin_user_class` |
| Login endpoint | `POST /api/v3/store/auth/login` | `POST /api/v3/admin/auth/login` |
| Refresh endpoint | `POST /api/v3/store/auth/refresh` | `POST /api/v3/admin/auth/refresh` |
| JWT audience | `aud: store_api` | `aud: admin_api` |
@@ -136,7 +136,7 @@ end
|---|---|
| `success(user)` | Wrap a user in a successful `ServiceModule::Result` |
| `failure(message)` | Wrap an error message in a failed result |
-| `find_user_by_email(email)` | Lookup against `Spree.customer_class` |
+| `find_user_by_email(email)` | Lookup against `Spree.user_class` |
| `find_or_create_user_from_oauth(provider:, uid:, info:, tokens: {})` | Calls `Spree::UserIdentity.find_or_create_from_oauth` with the right `user_class` |
| `params`, `request_env`, `user_class` | Reader access to the controller-supplied inputs |
@@ -181,7 +181,7 @@ Both registries are a `Spree::Authentication::StrategyRegistry` with the same AP
| `[key]` | Look up a registered class. |
| `key?(key)`, `keys`, `values`, `each`, `to_h` | Standard introspection. |
-The strategy is instantiated with the surface's user class automatically — `Spree.customer_class` from the store registry, `Spree.admin_user_class` from the admin registry — and your `authenticate` reads it via the `user_class` helper, so the same class provisions customers on one side and staff on the other.
+The strategy is instantiated with the surface's user class automatically — `Spree.user_class` from the store registry, `Spree.admin_user_class` from the admin registry — and your `authenticate` reads it via the `user_class` helper, so the same class provisions customers on one side and staff on the other.
<Tip>
Restrict a surface to SSO by removing the built-in email/password strategy after adding yours: `Spree.admin_authentication_strategies.remove(:email)` locks staff to your provider; the store side stays on email/password.
@@ -370,14 +370,14 @@ RSpec.describe MyApp::Auth::ExternalJwtStrategy do
end
it 'provisions a Spree user on first login' do
- expect { result }.to change(Spree.customer_class, :count).by(1)
+ expect { result }.to change(Spree.user_class, :count).by(1)
expect(result).to be_success
expect(result.value.email).to eq('[email protected]')
end
it 'reuses the user on subsequent logins' do
described_class.new(params: { token: token }, request_env: {}).authenticate
- expect { result }.not_to change(Spree.customer_class, :count)
+ expect { result }.not_to change(Spree.user_class, :count)
end
it 'fails on an expired token' do
@@ -395,4 +395,4 @@ end
- `Spree::Api::V3::Store::AuthController` — `spree/api/app/controllers/spree/api/v3/store/auth_controller.rb`
- `Spree::Api::V3::Admin::AuthController` — `spree/api/app/controllers/spree/api/v3/admin/auth_controller.rb`
- `Spree::Api::V3::JwtAuthentication` — `spree/api/app/controllers/concerns/spree/api/v3/jwt_authentication.rb`
-- See also: [Staff & Roles](/developer/core-concepts/staff-roles) for the admin login flow, [Customers](/developer/core-concepts/customers) for storefront auth, and [Authentication](/developer/customization/authentication) for `Spree.customer_class` integration.
+- See also: [Staff & Roles](/developer/core-concepts/staff-roles) for the admin login flow, [Customers](/developer/core-concepts/customers) for storefront auth, and [Authentication](/developer/customization/authentication) for `Spree.user_class` integration.
diff --git a/docs/developer/storefront/rails/helper-methods.mdx b/docs/developer/storefront/rails/helper-methods.mdx
index 5ca3117fcd..ef02567a83 100644
--- a/docs/developer/storefront/rails/helper-methods.mdx
+++ b/docs/developer/storefront/rails/helper-methods.mdx
@@ -50,11 +50,11 @@ Returns the current order object. If no order is found, it will return `nil`.
### `try_spree_current_user`
-<ResponseField name="try_spree_current_user" type="Spree.customer_class" description="The current user object.">
+<ResponseField name="try_spree_current_user" type="Spree.user_class" description="The current user object.">
<SpreeUser />
</ResponseField>
-Returns the current user object (class depends on the `Spree.customer_class` configuration). If the user is not signed in, it will return `nil`.
+Returns the current user object (class depends on the `Spree.user_class` configuration). If the user is not signed in, it will return `nil`.
<Tip>
If you want to check if the user is signed in, you can use the following: