Package: auth

Source: api/packages/auth · imported version 0.2.41. The sections after the README are extracted from the code on every docs build.

README

What does it do

Package for user authentication. In addition, the package includes:

• user management,
• group management,
• profile management,
• registration.

Installing

• composer require ulams/auth
• php artisan migrate
• php artisan db:seed --class="Ulams\Auth\Database\Seeders\AuthPermissionSeeder"

Optional:

• Run command ulams:admin.

Commands

• ulams:admin - create account with role admin

Database

1. category_user - Table is used to store the user categories.
2. groups - Table for storing groups.
3. group_user - Table for storing groups assigned to the user.

User 1 -> n Categories
User 1 -> n Groups

Endpoints

All the endpoints are defined in

Tests

Run ./vendor/bin/phpunit to run tests.

Events

• AccountBlocked - Event is dispatched after blocking the user’s account (is_active=false).
• AccountConfirmed - Event is dispatched after the user verifies the account.
• AccountDeleted - Event is dispatched after deleting the user.
• AccountMustBeEnableByAdmin - Event is dispatched when the user registers and Config::get('ulams_auth.account_must_be_enabled_by_admin') === SettingStatusEnum::ENABLED
• AccountRegistered - Event is dispatched after the account is registered.
• ForgotPassword - Event is dispatched when a password reset request is sent.
• Login - Event is dispatched on successful login.
• Logout - Event is dispatched after logout.
• PasswordChanged - Event is dispatched after the password changed.
• ResetPassword - Event is dispatched after resetting the password.
• UserAddedToGroup - Event is dispatched after adding the user to the group.
• UserRemovedFromGroup - Event is dispatched after removing the user from the group.

Listeners

• CreatePasswordResetToken - The listener listens for the ForgotPassword event and executes the following method.

public function handle(ForgotPassword $event): void
{
    if (!is_callable(self::getRunEventForgotPassword()) || self::getRunEventForgotPassword()()) {
        $user = $event->getUser();

        $this->userRepository->update([
            'password_reset_token' => Str::random(32),
        ], $user->getKey());

        $user->refresh();

        $user->notify(new ResetPassword($user->password_reset_token, $event->getReturnUrl()));
    }
}

This is useful if you are using TemplateEmail and you don’t want to send the default e-mails.

 CreatePasswordResetToken::setRunEventForgotPassword(
    function () {
        $templateRepository = app(TemplateRepositoryContract::class);
        return empty($templateRepository->findTemplateDefault(
            ForgotPassword::class,
            EmailChannel::class
        ));
    }
 );

• SendEmailVerificationNotification - The listener listens for the AccountRegistered event and executes the following method.

public function handle(Registered $event)
{
    if (!is_callable(self::getRunEventEmailVerification()) || self::getRunEventEmailVerification()()) {
        if ($event->user instanceof MustVerifyEmail && !$event->user->hasVerifiedEmail()) {
            $event->user->sendEmailVerificationNotification();
        }
    }
}

How to use this on frontend

Admin panel

List of users

Creating/editing user

User categories

List of groups

Creating/editing group

My profile

Permissions

Permissions are defined in seeder.

More documentation in the package

• api/packages/auth/ADMIN.md
• api/packages/auth/docs/group_form.png
• api/packages/auth/docs/list_of_groups.png
• api/packages/auth/docs/list_of_users.png
• api/packages/auth/docs/my_profile.png
• api/packages/auth/docs/user_categories.png
• api/packages/auth/docs/user_form.png

API endpoints

Method	Path	Auth	Action
GET	/api/meta		MetaController@show
POST	/api/auth/device/code		DeviceAuthController@code
POST	/api/auth/device/token		DeviceAuthController@token
GET	/api/auth/device/requests/{user_code}	yes	DeviceAuthController@show
POST	/api/auth/device/requests/{user_code}/approve	yes	DeviceAuthController@approve
POST	/api/auth/device/requests/{user_code}/deny	yes	DeviceAuthController@deny
GET	/api/auth/tokens	yes	TokenController@index
POST	/api/auth/tokens	yes	TokenController@store
GET	/api/auth/tokens/current	yes	TokenController@current
DELETE	/api/auth/tokens/{id}	yes	TokenController@destroy
GET	/api/admin/tokens	yes	TokenAdminController@index
DELETE	/api/admin/tokens/{id}	yes	TokenAdminController@destroy
GET	/api/admin/tokens/{id}/audit	yes	TokenAdminController@audit
GET	/api/admin/agent-audit	yes	TokenAdminController@agentAudit
POST	/api/admin/auth/impersonate	yes	LoginApiController@impersonate
POST	/api/auth/register	yes	RegisterApiController@register
POST	/api/auth/login	yes	LoginApiController@login
GET	/api/auth/registerable-groups	yes	AuthApiController@registerableGroups
POST	/api/auth/password/forgot	yes	AuthApiController@forgotPassword
POST	/api/auth/password/reset	yes	AuthApiController@resetPassword
GET	/api/auth/social/{provider}	yes	AuthApiController@socialRedirect
GET	/api/auth/social/{provider}/callback	yes	AuthApiController@socialCallback
POST	/api/auth/social/complete/{token}	yes	AuthApiController@completeSocialData
GET	/api/auth/email/verify/{id}/{hash}	yes	AuthApiController@verifyEmail
POST	/api/auth/email/resend	yes	AuthApiController@resendEmailVerification
POST	/api/auth/logout	yes	LogoutApiController@logout
GET	/api/auth/refresh	yes	AuthApiController@refresh
GET	/api/profile/me	yes	ProfileAPIController@me
PUT	/api/profile/me	yes	ProfileAPIController@update
PUT	/api/profile/me-auth	yes	ProfileAPIController@updateAuthData
PUT	/api/profile/password	yes	ProfileAPIController@updatePassword
PUT	/api/profile/interests	yes	ProfileAPIController@interests
GET	/api/profile/settings	yes	ProfileAPIController@settings
PUT	/api/profile/settings	yes	ProfileAPIController@settingsUpdate
POST	/api/profile/upload-avatar	yes	ProfileAPIController@uploadAvatar
DELETE	/api/profile/delete-avatar	yes	ProfileAPIController@deleteAvatar
DELETE	/api/profile	yes	ProfileAPIController@delete
POST	/api/profile/delete/init	yes	ProfileAPIController@initProfileDeletion
GET	/api/profile/delete/{userId}/{token}		ProfileAPIController@confirmDeletionProfile
GET	/api/admin/users	yes	UserController@listUsers
POST	/api/admin/users	yes	UserController@createUser
GET	/api/admin/users/{id}	yes	UserController@getUser
PATCH	/api/admin/users/{id}	yes	UserController@partialUpdateUser
PUT	/api/admin/users/{id}	yes	UserController@updateUser
DELETE	/api/admin/users/{id}	yes	UserController@deleteUser
POST	/api/admin/users/{id}/avatar	yes	UserController@uploadAvatar
DELETE	/api/admin/users/{id}/avatar	yes	UserController@deleteAvatar
GET	/api/admin/users/{id}/settings	yes	UserSettingsController@listUserSettings
PATCH	/api/admin/users/{id}/settings	yes	UserSettingsController@patchUserSettings
PUT	/api/admin/users/{id}/settings	yes	UserSettingsController@putUserSettings
GET	/api/admin/users/{id}/interests	yes	UserInterestsController@listUserInterests
PUT	/api/admin/users/{id}/interests	yes	UserInterestsController@updateUserInterests
POST	/api/admin/users/{id}/interests	yes	UserInterestsController@addUserInterest
DELETE	/api/admin/users/{id}/interests/{interest_id}	yes	UserInterestsController@deleteUserInterest
GET	/api/admin/user-groups	yes	UserGroupsController@listGroups
GET	/api/admin/user-groups/tree	yes	UserGroupsController@listGroupsTree
GET	/api/admin/user-groups/users	yes	UserGroupsController@listWithUsers
POST	/api/admin/user-groups	yes	UserGroupsController@createGroup
GET	/api/admin/user-groups/{id}	yes	UserGroupsController@getGroup
PUT	/api/admin/user-groups/{id}	yes	UserGroupsController@updateGroup
PATCH	/api/admin/user-groups/{id}	yes	UserGroupsController@updateGroup
DELETE	/api/admin/user-groups/{id}	yes	UserGroupsController@deleteGroup
POST	/api/admin/user-groups/{id}/members	yes	UserGroupsController@addMember
DELETE	/api/admin/user-groups/{id}/members/{user_id}	yes	UserGroupsController@removeMember

Permissions

Permission	Seeded for roles	Constant
user_manage		AuthPermissionsEnum::USER_MANAGE
user_create	admin	AuthPermissionsEnum::USER_CREATE
user_delete	admin	AuthPermissionsEnum::USER_DELETE
user_delete_self	admin, student, tutor	AuthPermissionsEnum::USER_DELETE_SELF
user_update	admin	AuthPermissionsEnum::USER_UPDATE
user_update_self	admin, student, tutor	AuthPermissionsEnum::USER_UPDATE_SELF
user_read	admin	AuthPermissionsEnum::USER_READ
user_read_self	admin, student, tutor	AuthPermissionsEnum::USER_READ_SELF
user_read_course-authored	admin, tutor	AuthPermissionsEnum::USER_READ_OWNED
user_list	admin	AuthPermissionsEnum::USER_LIST
user_list_course-authored	admin, tutor	AuthPermissionsEnum::USER_LIST_OWNED
user_verify_account	admin	AuthPermissionsEnum::USER_VERIFY_ACCOUNT
user-group_create	admin	AuthPermissionsEnum::USER_GROUP_CREATE
user-group_delete	admin	AuthPermissionsEnum::USER_GROUP_DELETE
user-group_list	admin	AuthPermissionsEnum::USER_GROUP_LIST
user-group_list_self	admin, student, tutor	AuthPermissionsEnum::USER_GROUP_LIST_SELF
user-group_member-add	admin	AuthPermissionsEnum::USER_GROUP_MEMBER_ADD
user-group_member-remove	admin	AuthPermissionsEnum::USER_GROUP_MEMBER_REMOVE
user-group_read	admin	AuthPermissionsEnum::USER_GROUP_READ
user-group_read_self	admin, student, tutor	AuthPermissionsEnum::USER_GROUP_READ_SELF
user-group_update	admin	AuthPermissionsEnum::USER_GROUP_UPDATE
user-interest_update	admin	AuthPermissionsEnum::USER_INTEREST_UPDATE
user-interest_update_self	admin, student, tutor	AuthPermissionsEnum::USER_INTEREST_UPDATE_SELF
user-setting_update	admin	AuthPermissionsEnum::USER_SETTING_UPDATE
user-setting_update_self	admin, student, tutor	AuthPermissionsEnum::USER_SETTING_UPDATE_SELF
user_impersonate	admin	AuthPermissionsEnum::USER_IMPERSONATE
token_manage	admin	AuthPermissionsEnum::TOKEN_MANAGE
platform_admin	admin	AuthPermissionsEnum::PLATFORM_ADMIN

Settings

Registered with AdministrableConfig::registerConfig (editable in the admin panel under Configuration → Settings).

Key	Rules	Public	Read-only
ulams_auth.registration	required, string, in: . implode(,, SettingStatusEnum::getValues())	yes
ulams_auth.account_must_be_enabled_by_admin	required, string, in: . implode(,, SettingStatusEnum::getValues())	yes
ulams_auth.auto_verified_email	required, string, in: . implode(,, SettingStatusEnum::getValues())	yes
ulams_auth.return_url	required, url	yes
ulams_auth.socialite_remember_me	required, boolean	yes
ulams_auth.token_expiration_minutes	required, integer	no
services.facebook.client_id	nullable, string	no
services.facebook.client_secret	nullable, string	no
services.facebook.redirect	nullable, url	no
services.google.client_id	nullable, string	no
services.google.client_secret	nullable, string	no
services.google.redirect	nullable, url	no

Events

Event	Description	Notification templates
AccountBlocked		Email
AccountConfirmed		Email
AccountDeleted		Email
AccountDeletionRequested		Email
AccountMustBeEnableByAdmin		Email, Email
AccountRegistered		Email
ForgotPassword		Email
Impersonate
Login
Logout
PasswordChanged		Email
ResetPassword
UserAddedToGroup		Email
UserRemovedFromGroup		Email

Notification templates registered here

None.

Artisan commands

Command	Description	Signature
ulams:admin	Create a new admin account	ulams:admin
ulams:auth:prune-agent-audit	Delete agent audit log rows older than the retention period	ulams:auth:prune-agent-audit {--days= : Keep this many days (default: ulams_auth.agent_audit_days)}
ulams:auth:prune-device-authorizations	Revoke device-login tokens nobody collected and delete device requests expired for over a day	ulams:auth:prune-device-authorizations
ulams:tokens:export-scopes	Write the token scope vocabulary and route map as JSON for the CLI generator	ulams:tokens:export-scopes {--check : Fail when the committed JSON is out of date}

Scheduled jobs

Kind	Target	Frequency
command	'ulams:auth:prune-agent-audit'	daily()
command	'ulams:auth:prune-device-authorizations'	hourly()

Environment variables read

APP_VERSION, AUTH_AGENT_AUDIT_DAYS, AUTH_DEVICE_APPROVE_PER_MINUTE, AUTH_MAX_TOKENS_PER_USER, AUTH_SUPERADMIN_EMAIL