diff --git a/docs/commerce/storefront/configure_storefront.md b/docs/commerce/storefront/configure_storefront.md index 9ec8ce587a..802646b7d0 100644 --- a/docs/commerce/storefront/configure_storefront.md +++ b/docs/commerce/storefront/configure_storefront.md @@ -85,7 +85,7 @@ interface CatalogResolverInterface The following user settings mechanisms used in `ibexa/storefront` are reused from `ibexa/user` package: -- [change password feature](user_management.md) +- [change password feature](passwords.md) - user avatar Settings for a Storefront user are configured under the `ibexa.system..storefront.user_settings_groups` [configuration key](configuration.md#configuration-files): diff --git a/docs/customer_management/create_user_registration_form.md b/docs/customer_management/create_user_registration_form.md index 350e927cff..178737d03a 100644 --- a/docs/customer_management/create_user_registration_form.md +++ b/docs/customer_management/create_user_registration_form.md @@ -14,7 +14,7 @@ First, make sure you [enabled user registration](permission_use_cases.md#registe In your configuration, under `allowed_field_definitions_identifiers` [configuration key](configuration.md#configuration-files), specify the fields that should be part of your registration form. You can also define what kind of user you want to create under `user_type_identifier` e.g. frontend user. -To learn more about available users, see [user types documentation](user_management.md#user-types). +To learn more about available users, see [user types documentation](user_registration#user-types). ``` yaml ibexa: diff --git a/docs/getting_started/first_steps.md b/docs/getting_started/first_steps.md index 27e604e294..e06cbc71c7 100644 --- a/docs/getting_started/first_steps.md +++ b/docs/getting_started/first_steps.md @@ -41,7 +41,7 @@ module.exports = [ eZConfig, ibexaConfig, ...customConfigs ]; Make sure that you change the default password before you switch your installation from development to production. - For more information about passwords, see [Passwords](user_management.md#passwords). + For more information about passwords, see [Passwords](passwords.md). For more information about production security, see [Security checklist](security_checklist.md). 2\. Select Admin and go to Content Types. diff --git a/docs/infrastructure_and_maintenance/security/development_security.md b/docs/infrastructure_and_maintenance/security/development_security.md index 27d3c1d54b..2320bee54c 100644 --- a/docs/infrastructure_and_maintenance/security/development_security.md +++ b/docs/infrastructure_and_maintenance/security/development_security.md @@ -96,7 +96,7 @@ If you want to use this feature, you must at least extend the login template in Symfony provides native support for [multiple user providers]([[= symfony_doc =]]/security/multiple_user_providers.html). This makes it easy to integrate any kind of login handlers, including SSO and existing third-party bundles (e.g. [FR3DLdapBundle](https://github.com/Maks3w/FR3DLdapBundle), [HWIOauthBundle](https://github.com/hwi/HWIOAuthBundle), [FOSUserBundle](https://github.com/FriendsOfSymfony/FOSUserBundle), [BeSimpleSsoAuthBundle](http://github.com/BeSimple/BeSimpleSsoAuthBundle), etc.). -See [Authenticating a user with multiple user provider](user_management.md#authenticate-user-with-multiple-user-providers) for more information. +See [Authenticating a user with multiple user provider](user_authentication.md#authenticate-user-with-multiple-user-providers) for more information. ## JWT authentication diff --git a/docs/infrastructure_and_maintenance/security/security_checklist.md b/docs/infrastructure_and_maintenance/security/security_checklist.md index 1b079af613..754fd04bb4 100644 --- a/docs/infrastructure_and_maintenance/security/security_checklist.md +++ b/docs/infrastructure_and_maintenance/security/security_checklist.md @@ -79,7 +79,7 @@ This is specially important for admin accounts and other privileged users. !!! tip "Password rules" - See [setting up password rules](user_management.md#password-rules). + See [setting up password rules](passwords.md#password-rules). ### Secure secrets diff --git a/docs/templating/layout/add_forgot_password_option.md b/docs/templating/layout/add_forgot_password_option.md index f20bc56c71..6e7dd4a2b5 100644 --- a/docs/templating/layout/add_forgot_password_option.md +++ b/docs/templating/layout/add_forgot_password_option.md @@ -27,7 +27,7 @@ which users receive after they request a password change. The [default templates](https://github.com/ibexa/user/tree/main/src/bundle/Resources/views) for forgot password form and email are located in `ibexa/user/src/bundle/Resources/views`. The [templates](https://github.com/ibexa/admin-ui/tree/main/src/bundle/Resources/views/themes/admin/account/forgot_password) specific for the Back Office are in `ibexa/admin-ui/src/bundle/Resources/views/themes/admin/account`. -You can also modify [other user management templates](user_management.md#other-user-management-templates). +You can also modify [other user management templates](user_registration.md#other-user-management-templates). To add a link redirecting to the reset password form, in the page layout template, provide the following code: diff --git a/docs/templating/layout/add_login_form.md b/docs/templating/layout/add_login_form.md index 9ce4fef0b6..88fa067075 100644 --- a/docs/templating/layout/add_login_form.md +++ b/docs/templating/layout/add_login_form.md @@ -5,9 +5,9 @@ description: Customize the login form for new users in your site front end. # Add login form You can create a login form for your users. -Follow the instruction below to create a template with login form. If you want to configure more options for example, password expiration, see [other user management templates](user_management.md#other-user-management-templates). +Follow the instruction below to create a template with login form. If you want to configure more options for example, password expiration, see [other user management templates](user_registration.md#other-user-management-templates). -First, make sure you have configured [login methods](user_management.md#login-methods). +First, make sure you have configured [login methods](login_methods.md). If you only want to change a template, add the following configuration under the `ibexa.system..user` [configuration key](configuration.md#configuration-files): @@ -52,7 +52,7 @@ In `templates/themes//login`, create an `expired_credentials.html.tw ## Customize login form You can use a custom template for example to display information about password expiration -or to customize [other user management templates](user_management.md#other-user-management-templates). +or to customize [other user management templates](user_registration.md#other-user-management-templates). In case of more advanced template customization, you can use a subscriber, for example in `src/EventSubscriber/LoginFormViewSubscriber.php`: diff --git a/docs/tutorials/beginner_tutorial/8_enable_account_registration.md b/docs/tutorials/beginner_tutorial/8_enable_account_registration.md index 66152d72bf..73886da62b 100644 --- a/docs/tutorials/beginner_tutorial/8_enable_account_registration.md +++ b/docs/tutorials/beginner_tutorial/8_enable_account_registration.md @@ -171,7 +171,7 @@ The User you have just created will have the Roles assigned to this group. !!! tip You can change the group in which new Users are placed (but you don't need to do it for this tutorial). - See [Registering new users](user_management.md#registering-new-users) for more information. + See [Registering new users](user_registration.md) for more information. At this point you don't want anyone who registers to be able to add content to the website. That's why you'll create a new User Group with additional permissions. diff --git a/docs/users/customer_groups.md b/docs/users/customer_groups.md index 9e622d4ae7..83221e0fab 100644 --- a/docs/users/customer_groups.md +++ b/docs/users/customer_groups.md @@ -11,7 +11,7 @@ For example, you can offer a 10% discount for all products in the catalog to use !!! tip - Note that customer groups are not the same as [User Groups](user_management.md#user-groups). + Note that customer groups are not the same as [User Groups](user_registration.md#user-groups). User Groups concern all users in the system and can be used, for example, to handle permissions. Customer groups refer specifically to the commerce functionalities and enable handling prices. diff --git a/docs/users/invitations.md b/docs/users/invitations.md index fb8cdc18de..c0cbed3c02 100644 --- a/docs/users/invitations.md +++ b/docs/users/invitations.md @@ -48,3 +48,5 @@ Here, you can specify which template should be used for the invitation mail, and what should be the expiration time for the invitation link included in that mail. If a user does not click the invitation link sent to them in time, you can refresh the invitation. Refresh resets the time limit and changes the hash in the invitation link. + +You can find more registration related templates in [Register new users documentation](user_registration.md#other-user-management-templates). \ No newline at end of file diff --git a/docs/users/login_methods.md b/docs/users/login_methods.md new file mode 100644 index 0000000000..d104cd2905 --- /dev/null +++ b/docs/users/login_methods.md @@ -0,0 +1,64 @@ +--- +description: Set up user login methods. +--- + +# Login methods + +Two login methods are available: with User name or with email. + +Providers for these two methods are `ibexa.security.user_provider.username` +and `ibexa.security.user_provider.email`, respectively. + +You can configure which method is allowed under the `security` [configuration key](configuration.md#configuration-files): + +``` yaml +security: + providers: + ibexa: + chain: + providers: [ibexa_username, ibexa_email] + + ibexa_username: + id: ibexa.security.user_provider.username + + ibexa_email: + id: ibexa.security.user_provider.email + + firewalls: + #... + ibexa_front: + # ... + provider: ibexa +``` + +You can customize per User Field whether the email address used as a login method must be unique or not. + +To check that all existing User accounts have unique emails, +run the `ibexa:user:audit-database` command. +It will list all User accounts with duplicate emails. + +!!! caution + + Because logging in with email was not available until version v3.0, + you can come across issues if you use the option on an existing database. + + This may happen if more than one account uses the same email address. + Login through the User name will still be available. + + To resolve the issues, run `ibexa:user:audit-database` + and manually modify accounts that have duplicate emails. + +## Login rules + +You can set the rules for allowed User names in the Back Office per User Field. + +The rules are set using regular expressions. + +For example, to ensure that User names can only contain lowercase letters, +set `[a-z]+$` as **Username pattern**: + +![Setting a User name pattern](username_pattern.png) + +To check that all existing User accounts have names that fit the current pattern, +run the `ibexa:user:audit-database` command. +It will check all User accounts in the database and list those that do not fit the pattern. \ No newline at end of file diff --git a/docs/users/passwords.md b/docs/users/passwords.md new file mode 100644 index 0000000000..a71bf600f7 --- /dev/null +++ b/docs/users/passwords.md @@ -0,0 +1,119 @@ +--- +description: Set up user password rules. +--- + +## Passwords + +## Changing and recovering passwords + +The user may request to change their password, or may forget it and ask to have it reset. + +To change password, the user must have the `user/password` permission. + +When the user requests a reset of a forgotten password, an email is sent to them with a token. +It allows them to create a new password. + +For information about how to create and configure the template, see [Add forgot password option](add_forgot_password_option.md) + +The template for this email is located in `Resources/views/forgot_password/mail/forgot_user_password.html.twig` in `ibexa/user`. +You can [customize it according to your needs](add_login_form.md#customize-login-form). + +The validity of the password recovery token can be set using the `ibexa.system..security.token_interval_spec` parameter. +By default, it is set to `PT1H` (one hour). + +## Revoking passwords + +In case of a security situation such as a data leakage, you may need to force users to change their passwords. +You can do it with the help of the `ibexa:user:expire-password` command, +which revokes the passwords for specific users, User Groups or users belonging to the chosen Content Type. + +To select which users to revoke passwords for, use one of the following options with the command: + +- `--user-id|-u` - the ID of the user. Accepts multiple user IDs +- `--user-group-id|-ug` - the ID of the user group. Accepts multiple group IDs +- `--user-content-type-identifier|-ct` - the identifier of the user Content Type. Accepts multiple Content Types + +You can use the following additional options with the command: + +- `--force|-f` - commits the change, otherwise the command only performs a dry run +- `--iteration-count|-c` - defines how many users are fetched at once. Lowering this value helps with memory issues +- `--password-ttl|-t` - number of days after which new passwords expire. Used when the command enables password expiration for user Content Types that do not use it yet. + +For example, to revoke the passwords of all users of the `user` Content Type, run: + +``` bash +php bin/console ibexa:user:expire-password --user-content-type-identifier=user --force +``` + +To perform a dry run (without saving the results) of revoking passwords of all users from user group 13, run: + +``` bash +php bin/console ibexa:user:expire-password --user-group-id=13 +``` + +## Password rules + +You can customize the password policy in your project. +Each password setting is customizable per User Field Type. +You can change the [password attributes](#password-attributes) or [password expiration settings](#password-expiration), and determine the rules for [repeating passwords](#repeating-passwords). + +To access the password settings: + +1. In the Back Office, in the **Admin** Panel, open the **Content Types** tab. +1. In the **Content Type groups** table, click on **Users**. +1. Edit the User Content Type. +1. In the **Field definitions** list, view the settings for **User account (ezuser)**. + +!!! tip + + There can be other Content Types that function as users, beyond the built-in User Content Type. + For details, see [User Identifiers](repository_configuration.md#user-identifiers). + +### Password attributes + +In the **User account (ezuser)** Field definition, you can determine if the password must contain at least: + +- One uppercase letter +- One lowercase letter +- One number +- One non-alphanumeric character + +You can also set the minimum password length. + +### Password expiration + +In the **User account (ezuser)** Field definition, you can set password expiration rules, which forces users to change their passwords periodically. + +![Password expiry settings](password_expiry.png) + +You can also decide when the user is notified that they need to change their password. +The notification is displayed in the Back Office after login and in the User Content item's preview. + +### Repeating passwords + +You can set a rule that the password cannot be reused. +You set it for the User Content Type in the **User account (ezuser)** Field Type's settings. +When this is set, the user cannot type in the same password when it expires. +It has to be changed to a new one. + +This only checks the new password against the current one. +A password that has been used before can be used again. + +This rule is valid by default when password expiration is set. + +### Breached passwords + +You can set a rule that prevents using passwords which have been exposed in a public breach. +To do this, in the **User account (ezuser)** Field definition, select "Password must not be contained in a public breach". + +![Protection against using breached passwords](password_breached.png) + +This rule checks the password against known password dumps by using the https://haveibeenpwned.com/ API. +It does not check existing passwords, so it won't block login for anyone. It applies only to new passwords when users change them. + +!!! note + + The password itself isn't sent to the https://haveibeenpwned.com/ API, which makes this check secure. + For more information on how that is possible, + see [Validating Leaked Passwords with k-Anonymity.](https://blog.cloudflare.com/validating-leaked-passwords-with-k-anonymity/) + diff --git a/docs/users/user_authentication.md b/docs/users/user_authentication.md new file mode 100644 index 0000000000..359dff6fb9 --- /dev/null +++ b/docs/users/user_authentication.md @@ -0,0 +1,110 @@ +--- +description: Customize user authentication. +--- + +# User authentication + +## Authenticate user with multiple user providers + +Symfony provides native support for [multiple user providers]([[= symfony_doc =]]/security/multiple_user_providers.html). +This makes it easier to integrate any kind of login handlers, including SSO and existing third party bundles (e.g. [FR3DLdapBundle](https://github.com/Maks3w/FR3DLdapBundle), [HWIOauthBundle](https://github.com/hwi/HWIOAuthBundle), [FOSUserBundle](https://github.com/FriendsOfSymfony/FOSUserBundle), [BeSimpleSsoAuthBundle](http://github.com/BeSimple/BeSimpleSsoAuthBundle), etc.). + +However, to be able to use *external* user providers with [[= product_name =]], a valid Platform user needs to be injected into the Repository. +This is mainly for the kernel to be able to manage content-related permissions (but not limited to this). + +Depending on your context, you either want to create a Platform User, return an existing User, or even always use a generic User. + +Whenever an *external* user is matched (i.e. one that does not come from Platform repository, like coming from LDAP), [[= product_name =]] kernel initiates an `MVCEvents::INTERACTIVE_LOGIN` event. +Every service listening to this event receives an `Ibexa\Core\MVC\Symfony\Event\InteractiveLoginEvent` object which contains the original security token (that holds the matched user) and the request. + +Then, it is up to the listener to retrieve a Platform User from the Repository and to assign it back to the event object. +This user is injected into the repository and used for the rest of the request. + +If no [[= product_name =]] User is returned, the Anonymous User is used. + +### User exposed and security token + +When an *external* user is matched, a different token is injected into the security context, the `InteractiveLoginToken`. +This token holds a `UserWrapped` instance which contains the originally matched User and the *API user* (the one from the [[= product_name =]] Repository). + +The *API user* is mainly used for permission checks against the repository and thus stays *under the hood*. + +### Customize the User class + +It is possible to customize the user class used by extending `Ibexa\Core\MVC\Symfony\Security\EventListener\SecurityListener` service, which defaults to `Ibexa\Core\MVC\Symfony\Security\EventListener\SecurityListener`. + +You can override `getUser()` to return whatever User class you want, as long as it implements `Ibexa\Core\MVC\Symfony\Security\UserInterface`. + +The following is an example of using the in-memory user provider: + +``` yaml +# config/packages/security.yaml +security: + providers: + # Chaining in_memory and ibexa user providers + chain_provider: + chain: + providers: [in_memory, ibexa] + ibexa: + id: ibexa.security.user_provider + in_memory: + memory: + users: + # You will then be able to login with username "user" and password "userpass" + user: { password: userpass, roles: [ 'ROLE_USER' ] } + # The "in memory" provider requires an encoder for Symfony\Component\Security\Core\User\User + encoders: + Symfony\Component\Security\Core\User\User: plaintext +``` + +### Implement the listener + +In the `config/services.yaml` file: + +``` yaml +services: + App\EventListener\InteractiveLoginListener: + arguments: ['@ibexa.api.service.user'] + tags: + - { name: kernel.event_subscriber }  +``` + +Do not mix `MVCEvents::INTERACTIVE_LOGIN` event (specific to [[= product_name =]]) and `SecurityEvents::INTERACTIVE_LOGIN` event (fired by Symfony security component). + +``` php +userService = $userService; + } + + public static function getSubscribedEvents() + { + return [ + MVCEvents::INTERACTIVE_LOGIN => 'onInteractiveLogin' + ]; + } + + public function onInteractiveLogin(InteractiveLoginEvent $event) + { + // This loads a generic User and assigns it back to the event. + // You may want to create Users here, or even load predefined Users depending on your own rules. + $event->setApiUser($this->userService->loadUserByLogin( 'lolautruche' )); + } +}  +``` diff --git a/docs/users/user_management.md b/docs/users/user_management.md deleted file mode 100644 index 86cb62fddb..0000000000 --- a/docs/users/user_management.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -description: Set up user login methods, password rules, and customize user authentication. ---- - -# User management - -## Passwords - -### Changing and recovering passwords - -The user may request to change their password, or may forget it and ask to have it reset. - -To change password, the user must have the `user/password` permission. - -When the user requests a reset of a forgotten password, an email is sent to them with a token. -It allows them to create a new password. - -For information about how to create and configure the template, see [Add forgot password option](add_forgot_password_option.md) - -The template for this email is located in `Resources/views/forgot_password/mail/forgot_user_password.html.twig` in `ibexa/user`. -You can [customize it according to your needs](add_login_form.md#customize-login-form). - -The validity of the password recovery token can be set using the `ibexa.system..security.token_interval_spec` parameter. -By default, it is set to `PT1H` (one hour). - -### Revoking passwords - -In case of a security situation such as a data leakage, you may need to force users to change their passwords. -You can do it with the help of the `ibexa:user:expire-password` command, -which revokes the passwords for specific users, User Groups or users belonging to the chosen Content Type. - -To select which users to revoke passwords for, use one of the following options with the command: - -- `--user-id|-u` - the ID of the user. Accepts multiple user IDs -- `--user-group-id|-ug` - the ID of the User Group. Accepts multiple group IDs -- `--user-content-type-identifier|-ct` - the identifier of the user Content Type. Accepts multiple Content Types - -You can use the following additional options with the command: - -- `--force|-f` - commits the change, otherwise the command only performs a dry run -- `--iteration-count|-c` - defines how many users are fetched at once. Lowering this value helps with memory issues -- `--password-ttl|-t` - number of days after which new passwords expire. Used when the command enables password expiration for user Content Types that do not use it yet. - -For example, to revoke the passwords of all users of the `user` Content Type, run: - -``` bash -php bin/console ibexa:user:expire-password --user-content-type-identifier=user --force -``` - -To perform a dry run (without saving the results) of revoking passwords of all users from User Group 13, run: - -``` bash -php bin/console ibexa:user:expire-password --user-group-id=13 -``` - -## Password rules - -You can customize the password policy in your project. -Each password setting is customizable per User Field Type. -You can change the [password attributes](#password-attributes) or [password expiration settings](#password-expiration), and determine the rules for [repeating passwords](#repeating-passwords). - -To access the password settings: - -1. In the Back Office, in the **Admin** Panel, open the **Content Types** tab. -1. In the **Content Type groups** table, click on **Users**. -1. Edit the User Content Type. -1. In the **Field definitions** list, view the settings for **User account (ezuser)**. - -!!! tip - - There can be other Content Types that function as users, beyond the built-in User Content Type. - For details, see [User Identifiers](repository_configuration.md#user-identifiers). - -### Password attributes - -In the **User account (ezuser)** Field definition, you can determine if the password must contain at least: - -- One uppercase letter -- One lowercase letter -- One number -- One non-alphanumeric character - -You can also set the minimum password length. - -### Password expiration - -In the **User account (ezuser)** Field definition, you can set password expiration rules, which will force users to change their passwords periodically. - -![Password expiry settings](password_expiry.png) - -You can also decide when the user will be notified that they need to change their password. -The notification will be displayed in the Back Office after login and in the User Content item's preview. - -### Repeating passwords - -You can set a rule that the password cannot be reused. -You set it for the User Content Type in the **User account (ezuser)** Field Type's settings. -When this is set, the user cannot type in the same password when it expires. -It has to be changed to a new one. - -This only checks the new password against the current one. -A password that has been used before can be used again. - -This rule is valid by default when password expiration is set. - -### Breached passwords - -You can set a rule that prevents using passwords which have been exposed in a public breach. -To do this, in the **User account (ezuser)** Field definition, select "Password must not be contained in a public breach". - -![Protection against using breached passwords](password_breached.png) - -This rule checks the password against known password dumps by using the https://haveibeenpwned.com/ API. -It does not check existing passwords, so it will not block login for anyone. It applies only to new passwords when users change them. - -!!! note - - The password itself isn't sent to the https://haveibeenpwned.com/ API, which makes this check secure. - For more information on how that is possible, - see [Validating Leaked Passwords with k-Anonymity.](https://blog.cloudflare.com/validating-leaked-passwords-with-k-anonymity/) - -## Login methods - -Two login methods are available: with User name or with email. - -Providers for these two methods are `ibexa.security.user_provider.username` -and `ibexa.security.user_provider.email`, respectively. - -You can configure which method is allowed under the `security` [configuration key](configuration.md#configuration-files): - -``` yaml -security: - providers: - ibexa: - chain: - providers: [ibexa_username, ibexa_email] - - ibexa_username: - id: ibexa.security.user_provider.username - - ibexa_email: - id: ibexa.security.user_provider.email - - firewalls: - #... - ibexa_front: - # ... - provider: ibexa -``` - -You can customize per User Field whether the email address used as a login method must be unique or not. - -To check that all existing User accounts have unique emails, -run the `ibexa:user:audit-database` command. -It will list all User accounts with duplicate emails. - -!!! caution - - Because logging in with email was not available until version v3.0, - you can come across issues if you use the option on an existing database. - - This may happen if more than one account uses the same email address. - Login through the User name will still be available. - - To resolve the issues, run `ibexa:user:audit-database` - and manually modify accounts that have duplicate emails. - -### Login rules - -You can set the rules for allowed User names in the Back Office per User Field. - -The rules are set using regular expressions. - -For example, to ensure that User names can only contain lowercase letters, -set `[a-z]+$` as **Username pattern**: - -![Setting a User name pattern](username_pattern.png) - -To check that all existing User accounts have names that fit the current pattern, -run the `ibexa:user:audit-database` command. -It will check all User accounts in the database and list those that do not fit the pattern. - -## Registering new users - -You can allow your users to create accounts by employing the `/register` route. This route leads to a registration form that, when filled in, creates a new User Content item in the repository. - -### User types - -There are two user types defined: `users` and `customers`. -`users` are Back Office users that are involved in creating the page such as editors, and `customers` are frontend users. -To decide where the user should be registered to, you need to specify their user type under the `ibexa.system..user_type_identifier` [configuration key](configuration.md#configuration-files). - -```yaml -ibexa: - system: - : - user_registration: - user_type_identifier: user -``` - -### User Groups - -By default, new Users generated in this way are placed in the Guest accounts group. You can select a different default group in the following section of configuration: - -``` yaml -ibexa: - system: - default: - user_registration: - group_id: -``` - -### Registration form field configuration - -To modify the registration form template, add or remove fields under the `allowed_field_definitions_identifiers` [configuration key](configuration.md#configuration-files): - -```yaml -ibexa: - system: - : - user_registration: - user_type_identifier: user - form: - allowed_field_definitions_identifiers: - - first_name - - last_name - - user_account -``` - -### Other user management templates - -You can also modify form templates in the following way: - -**Changing user password:** - -``` yaml -ibexa: - system: - : - user_change_password: - templates: - form: -``` - -**Password recovery forms:** - -``` yaml -ibexa.site_access.config..user_forgot_password.templates.form -ibexa.site_access.config..user_forgot_password_success.templates.form -ibexa.site_access.config..user_forgot_password_login.templates.form -ibexa.site_access.config..user_forgot_password.templates.mail -``` - -**Resetting password:** - -``` yaml -ibexa.site_access.config..user_reset_password.templates.form -ibexa.site_access.config..user_reset_password.templates.invalid_link -ibexa.site_access.config..user_reset_password.templates.success -``` - -**User settings:** - -``` yaml -ibexa.site_access.config..user_settings.templates.list -ibexa.site_access.config..user_settings.templates.update -``` - -## Authenticate user with multiple user providers - -Symfony provides native support for [multiple user providers]([[= symfony_doc =]]/security/multiple_user_providers.html). -This makes it easy to integrate any kind of login handlers, including SSO and existing third party bundles (e.g. [FR3DLdapBundle](https://github.com/Maks3w/FR3DLdapBundle), [HWIOauthBundle](https://github.com/hwi/HWIOAuthBundle), [FOSUserBundle](https://github.com/FriendsOfSymfony/FOSUserBundle), [BeSimpleSsoAuthBundle](http://github.com/BeSimple/BeSimpleSsoAuthBundle), etc.). - -However, to be able to use *external* user providers with [[= product_name =]], a valid Platform user needs to be injected into the Repository. -This is mainly for the kernel to be able to manage content-related permissions (but not limited to this). - -Depending on your context, you will either want to create a Platform User, return an existing User, or even always use a generic User. - -Whenever an *external* user is matched (i.e. one that does not come from Platform repository, like coming from LDAP), [[= product_name =]] kernel initiates an `MVCEvents::INTERACTIVE_LOGIN` event. -Every service listening to this event receives an `Ibexa\Core\MVC\Symfony\Event\InteractiveLoginEvent` object which contains the original security token (that holds the matched user) and the request. - -Then, it is up to the listener to retrieve a Platform User from the Repository and to assign it back to the event object. -This user will be injected into the repository and used for the rest of the request. - -If no [[= product_name =]] User is returned, the Anonymous User will be used. - -### User exposed and security token - -When an *external* user is matched, a different token will be injected into the security context, the `InteractiveLoginToken`. -This token holds a `UserWrapped` instance which contains the originally matched User and the *API user* (the one from the [[= product_name =]] Repository). - -Note that the *API user* is mainly used for permission checks against the repository and thus stays *under the hood*. - -### Customize the User class - -It is possible to customize the user class used by extending `Ibexa\Core\MVC\Symfony\Security\EventListener\SecurityListener` service, which defaults to `Ibexa\Core\MVC\Symfony\Security\EventListener\SecurityListener`. - -You can override `getUser()` to return whatever User class you want, as long as it implements `Ibexa\Core\MVC\Symfony\Security\UserInterface`. - -The following is an example of using the in-memory user provider: - -``` yaml -# config/packages/security.yaml -security: - providers: - # Chaining in_memory and ibexa user providers - chain_provider: - chain: - providers: [in_memory, ibexa] - ibexa: - id: ibexa.security.user_provider - in_memory: - memory: - users: - # You will then be able to login with username "user" and password "userpass" - user: { password: userpass, roles: [ 'ROLE_USER' ] } - # The "in memory" provider requires an encoder for Symfony\Component\Security\Core\User\User - encoders: - Symfony\Component\Security\Core\User\User: plaintext -``` - -### Implement the listener - -In the `config/services.yaml` file: - -``` yaml -services: - App\EventListener\InteractiveLoginListener: - arguments: ['@ibexa.api.service.user'] - tags: - - { name: kernel.event_subscriber }  -``` - -Do not mix `MVCEvents::INTERACTIVE_LOGIN` event (specific to [[= product_name =]]) and `SecurityEvents::INTERACTIVE_LOGIN` event (fired by Symfony security component). - -``` php -userService = $userService; - } - - public static function getSubscribedEvents() - { - return [ - MVCEvents::INTERACTIVE_LOGIN => 'onInteractiveLogin' - ]; - } - - public function onInteractiveLogin(InteractiveLoginEvent $event) - { - // This loads a generic User and assigns it back to the event. - // You may want to create Users here, or even load predefined Users depending on your own rules. - $event->setApiUser($this->userService->loadUserByLogin( 'lolautruche' )); - } -}  -``` diff --git a/docs/users/user_registration.md b/docs/users/user_registration.md new file mode 100644 index 0000000000..70564df0ef --- /dev/null +++ b/docs/users/user_registration.md @@ -0,0 +1,93 @@ +--- +description: Register new users. +--- + +# Register new users + +You can allow your users to create accounts by employing the `/register` route. This route leads to a registration form that, when filled in, creates a new User Content item in the repository. + +### User types + +There are two user types defined: `users` and `customers`. +`users` are Back Office users that are involved in creating the page such as editors, and `customers` are frontend users. +To decide where the user should be registered to, you need to specify their user type under the `ibexa.system..user_type_identifier` [configuration key](configuration.md#configuration-files). + +```yaml +ibexa: + system: + : + user_registration: + user_type_identifier: user +``` + +### User Groups + +By default, new Users generated in this way are placed in the Guest accounts group. You can select a different default group in the following section of configuration: + +``` yaml +ibexa: + system: + default: + user_registration: + group_id: +``` + +### Registration form field configuration + +To modify the registration form template, add or remove fields under the `allowed_field_definitions_identifiers` [configuration key](configuration.md#configuration-files): + +```yaml +ibexa: + system: + : + user_registration: + user_type_identifier: user + form: + allowed_field_definitions_identifiers: + - first_name + - last_name + - user_account +``` + +### Other user management templates + +You can also modify form templates in the following way: + +**Changing user password:** + +``` yaml +ibexa: + system: + : + user_change_password: + templates: + form: +``` + +**Password recovery forms:** + +``` yaml +ibexa.site_access.config..user_forgot_password.templates.form +ibexa.site_access.config..user_forgot_password_success.templates.form +ibexa.site_access.config..user_forgot_password_login.templates.form +ibexa.site_access.config..user_forgot_password.templates.mail +``` + +**Resetting password:** + +``` yaml +ibexa.site_access.config..user_reset_password.templates.form +ibexa.site_access.config..user_reset_password.templates.invalid_link +ibexa.site_access.config..user_reset_password.templates.success +``` + +**User settings:** + +``` yaml +ibexa.site_access.config..user_settings.templates.list +ibexa.site_access.config..user_settings.templates.update +``` + +**Changing registration form templates:** + +To change the registration form template, follow instructions in [Invitation and registration form templates](invitations.md#invitation-and-registration-form-templates). \ No newline at end of file diff --git a/docs/users/users.md b/docs/users/users.md index 00e6d995ef..e76c9190fc 100644 --- a/docs/users/users.md +++ b/docs/users/users.md @@ -9,7 +9,26 @@ Users in [[= product_name =]] refer to all kinds of user accounts: administrator managers or shop customers. All such user accounts have the same underlying mechanism and enable you to control access to te application, both the Back Office and the website front, by using the [permission system](permissions.md). +## Invite users + [[= cards([ - "users/user_management", - "users/invitations", +"users/invitations", +"users/user_registration", ], columns=3) =]] + +## Authenticate users + +[[= cards([ +"users/login_methods", +"users/passwords", +"users/user_authentication", +"users/oauth_authentication", +"users/add_login_through_external_service", +], columns=5) =]] + +## Group users + +[[= cards([ +"users/customer_groups", +"users/segment_api", +], columns=2) =]] diff --git a/mkdocs.yml b/mkdocs.yml index 925cee05e1..3d9fc7764b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -373,12 +373,18 @@ nav: - Custom Policies: permissions/custom_policies.md - Users: - Users: users/users.md - - User management: users/user_management.md - - Customer groups: users/customer_groups.md - - Invitations: users/invitations.md - - OAuth authentication: users/oauth_authentication.md - - Add login through external service: users/add_login_through_external_service.md - - Segment API: users/segment_api.md + - User setup: + - Invitations: users/invitations.md + - Registration: users/user_registration.md + - User authentication: + - Login methods: users/login_methods.md + - Passwords: users/passwords.md + - User authentication: users/user_authentication.md + - OAuth authentication: users/oauth_authentication.md + - Add login through external service: users/add_login_through_external_service.md + - User grouping: + - Customer groups: users/customer_groups.md + - Segment API: users/segment_api.md - Personalization: - Personalization: personalization/personalization.md - How Personalization works: personalization/how_it_works.md diff --git a/plugins.yml b/plugins.yml index e91826d469..2aa5e099fd 100644 --- a/plugins.yml +++ b/plugins.yml @@ -263,7 +263,8 @@ plugins: 'guide/limitation_reference.md': 'permissions/limitation_reference.md' 'guide/custom_policies.md': 'permissions/custom_policies.md' - 'guide/user_management/user_management.md': 'users/user_management.md' + 'guide/user_management/user_management.md': 'users/users.md' + 'users/user_management.md': 'users/users.md' 'api/public_php_api_managing_users.md': 'users/segment_api.md' 'guide/user_management/customer_groups.md': 'users/customer_groups.md' 'guide/user_management/login_and_registration.md': 'users/users.md'