diff --git a/README.md b/README.md index 7b20596..3535278 100755 --- a/README.md +++ b/README.md @@ -4,55 +4,39 @@ [](https://coveralls.io/github/Jagepard/Rudra-Auth?branch=master) ----- -## Authentication, session management and RBAC / Аутентификация, управление сессиями и ролевой доступ | [API](https://github.com/Jagepard/Rudra-Auth/blob/master/docs.md "Documentation API") +## Authentication, session management and RBAC | [API](https://github.com/Jagepard/Rudra-Auth/blob/master/docs.md "Documentation API") -#### Install / Установка +#### Install ```composer require rudra/auth``` -##### Usage / Использование +##### Usage ```php use Rudra\Auth\AuthFacade as Auth; ``` -##### Configuration / Конфигурация ->For the component to work correctly, you need to add the following parameters to the Rudra configuration file - ->Для корректной работы компонента необходимо добавить следующие параметры в конфигурационный файл Rudra: - +##### Configuration +>For the component to work correctly, you need to add the following parameters to the Rudra configuration file: ```yml -#---------------------------------------------------------------- # Secret key for encrypting cookies and generating session hashes -#---------------------------------------------------------------- -# Секретный ключ для шифрования cookie и генерации хэшей -#---------------------------------------------------------------- secret: your_super_secret_key_here -#--------------------------------------------------------------------------------------- # Roles for Role-Based Access Control (the smaller the number, the higher the privilege) -#--------------------------------------------------------------------------------------- -# Роли для Role-Based Access Control (чем меньше число, тем выше привилегия) -#--------------------------------------------------------------------------------------- roles: admin: 0 editor: 1 moderator: 2 user: 3 -#--------------------------------------------------------------------------- # Environment (in the 'test' environment, cookies are not deleted on logout) -#--------------------------------------------------------------------------- -# Окружение (в среде 'test' не удаляются cookie при logout) -#--------------------------------------------------------------------------- environment: production ``` - -##### User registration / Регистрация пользователя +##### User registration ```php $user = [ "email" => "user@email.com", "password" => Auth::bcrypt("password") ]; ``` -##### Getting a user from the database / Получение пользователя из базы данных +##### Getting a user from the database ```php $user = [ "email" => "user@email.com", @@ -60,12 +44,9 @@ $user = [ "role" => "admin" ]; ``` -##### Authentication / Аутентификация +##### Authentication > The second argument is the **plain text password** entered by the user. > The `$user['password']` must contain a **hash** from the database. - -> Второй аргумент — это **пароль в открытом виде**, введённый пользователем. -> В `$user['password']` должен быть **хэш** из базы данных. ```php Auth::authentication( $user, @@ -75,9 +56,7 @@ Auth::authentication( ); ``` > **Note:** For the "Remember Me" feature to work, the login form must contain a checkbox with the name `remember_me`. - -> **Примечание:** Чтобы работала функция "Запомнить меня", форма входа должна содержать чекбокс с именем `remember_me`. -##### Login form example / Пример формы входа +##### Login form example ```html
``` -##### Restoring session (Remember Me) / Восстановление сессии +##### Restoring session (Remember Me) >Called at the beginning of the application loading (before authorization check). >If the user has valid 'Remember Me' cookies, the session will be restored automatically. - ->Вызывается в начале загрузки приложения (до проверки авторизации). ->Если у пользователя есть валидные cookie "Remember Me", сессия будет восстановлена автоматически. ```php Auth::restoreSessionIfSetRememberMe("login"); ``` -##### Authorization check / Проверка авторизации +##### Authorization check -###### General authorization check / Общая проверка авторизации +###### General authorization check >Check if the user is authorized. If not — redirect to 'login' - ->Проверяем, авторизован ли пользователь. Если нет — редирект на 'login' ```php if (!Auth::authorization(null, "login")) { exit; } ``` >If you just need to get a boolean value without a redirect (for example, for an API): - ->Если нужно просто получить булево значение без редиректа (например, для API): ```php $isLoggedIn = Auth::authorization(); ``` -###### Access to personal user resources / Доступ к личным ресурсам пользователя +###### Access to personal user resources >For access control to a specific user's resources (e.g., profile, personal data), a token is used. The token is generated from the user's password, email, and session hash. - ->Для контроля доступа к ресурсам конкретного пользователя (например, профиль, личные данные) используется токен. -Токен генерируется из пароля, email пользователя и хэша сессии. - ```php -/** - * ------------------------------------------ - * Generate token for the current user - * ------------------------------------------ - * Генерируем токен для текущего пользователя - * ------------------------------------------ - */ +// Generate token for the current user $token = md5($user['password'] . $user['email'] . Auth::getSessionHash()); -/** - * -------------------------------------------- - * Check if the token matches the session token - * -------------------------------------------- - * Проверяем, совпадает ли токен с сессионным - * -------------------------------------------- - */ +// Check if the token matches the session token if (!Auth::authorization($token, "login")) { exit; } ``` -##### Role-Based Access Control / Ролевой доступ +##### Role-Based Access Control >Check if the current role ('admin') has privileges not lower than the requested ones ('editor'). >If privileges are insufficient — redirect to 'error/403' - ->Проверяем, имеет ли текущая роль ('admin') права не ниже запрашиваемых ('editor'). ->Если прав не хватает — редирект на 'error/403' ```php use Rudra\Container\Facades\Session; -/** - * ------------------------------------------------------------------------------------ - * Get the role of the current user from the session (for example, after authorization) - * ------------------------------------------------------------------------------------ - * Получаем роль текущего пользователя из сессии (например, после авторизации) - * ------------------------------------------------------------------------------------ - */ +// Get the role of the current user from the session (for example, after authorization) if (Session::has("user")) { $currentRole = Session::get("user")['role'] ?? 'user'; } -/** - * -------------------------------------------------------------------------------------------- - * Check if the permissions are sufficient for access (for example, 'editor' level is required) - * -------------------------------------------------------------------------------------------- - * Проверяем, достаточно ли прав для доступа (например, требуется уровень 'editor') - * -------------------------------------------------------------------------------------------- - */ +// Check if the permissions are sufficient for access (for example, 'editor' level is required) if (!Auth::roleBasedAccess($currentRole, "editor", "error/403")) { exit; } ``` -##### Log out of the authentication session with a redirect to the login page / Выход из сеанса аутентификации с редиректом на страницу входа +##### Log out of the authentication session with a redirect to the login page ```php Auth::logout("login"); ``` @@ -187,14 +128,4 @@ This project is licensed under the **Mozilla Public License 2.0 (MPL-2.0)** — - Permits combining with proprietary code in larger works. 📄 Full license text: [LICENSE](./LICENSE) -🌐 Official MPL-2.0 page: https://mozilla.org/MPL/2.0/ - --------------------------- -Проект распространяется под лицензией **Mozilla Public License 2.0 (MPL-2.0)**. Это означает: - - Вы можете свободно использовать, изменять и распространять код. - - При изменении файлов, содержащих исходный код из этого репозитория, вы обязаны оставить их открытыми под той же лицензией. - - Вы **обязаны сохранять уведомления об авторстве** и ссылку на оригинал. - - Вы можете встраивать код в проприетарные проекты, если исходные файлы остаются под MPL. - -📄 Полный текст лицензии (на английском): [LICENSE](./LICENSE) -🌐 Официальная страница: https://mozilla.org/MPL/2.0/ \ No newline at end of file +🌐 Official MPL-2.0 page: https://mozilla.org/MPL/2.0/ \ No newline at end of file