# [Usage](../../../usage.md) > [Resources](resources.md) > Roles resource

Use the Roles resource when you need an admin UI to create roles, map them to `auth`-protected routes, and assign them to users — the same data read at runtime by `->setAuthorize()` / `->setAuthorizeRole()` and by [RolesHelper](roles_helper.md). Enable it together with the [Users resource](users_resource.md) so permission setup and user assignment live side by side.

K-Framework provides a role system that integrates perfectly with standard Laravel Authenticable model.

---
## How it works

There are four models:
- **RolesName**: store the role names.
- **RolesRoute**: store all the routes found in the application, is an automatic process and is advised to not remove any record from this model, also the route deletion is handled automatically.
- **RolesPermission**: associates the RolesName with RolesRoute, if a role is associated with the route, then any User that have the role can view/post on that route.
- **RolesUser**: simply associates User (Authenticable) with the RolesName, a User can have more than one role.

The process of authorization is fully automatic:  
When a User does not have authorization for the route, the application will return an "unauthorized" and redirect to the login. If a Button component have a route that cannot be accessed by the user, the button is not generated.

**NOTE**: the role system will work ONLY for routes under the `auth` middleware.  
**NOTE 2**: once enabled, the role middleware will automatically create the role `root`. This role should not be deleted, but if so, then it will be automatically re-created. The `root` role has access to everything and all the rules makes no effect on him. Be sure to give this role only to trusted web-admins.

## Installation
Be sure to run the migrations:
```bash
php artisan migrate
```

To enable the Roles resource in the config:
```html
config/k-framework/modules.php
```

and enable `roles_resource`:
```php
'roles_resource' => true,
```

Now, Roles resource is enabled, but the role system does not already work, you need to configure it. Being the Roles a resource, the routes to access to it are automatically defined:

```html
/resources/roles
```

You can add it directly to your navigation:
```php
'Roles' => ['shield', '/resources/roles', null, null, 1],
```

Here you can create, edit or delete the roles.

![image](img/roles_resource_1.png)

You can also change the route definitions for a more user-friendly approach:

![img.png](img/roles_resource_2.png)

After creating roles, assign them to Users, be sure to have at least one User with `root` role in case you have no backup.

Lastly, is possible to enable the role system in the configuration `config\k-framework\roles.php`:

```php
<?php

return [
    'enabled' => true,
    'excluded_routes' => []
];
```
where 'excluded_routes' is an array of route names that are under the `auth` middleware but must be excluded from role check.

## Example

```php
// config/k-framework/modules.php
'roles_resource' => true,
'users_resource' => true,
```

```php
// routes navigation definition
'Roles' => ['shield', '/resources/roles', null, null, 1],
'Users' => ['account-group', '/resources/users', null, null, 2],
```

```php
// Blade: same rule as the middleware, checked inline
@if(\KFramework\Helpers\RolesHelper::hasRole('root'))
    <a href="/resources/roles">Manage roles</a>
@endif
```

Create roles at `/resources/roles`, assign them in `/resources/users`, then protect components with `->setAuthorize('route.name')`.

## See also

- [Usage](../../../usage.md)
- [Resource](resources.md) — base template this resource extends
- [RolesHelper](roles_helper.md) — `hasPermission()` / `hasRole()` runtime checks
- [Authorize](../../components/shared_attributes/authorize.md) / [AuthorizeRole](../../components/shared_attributes/authorizeRole.md)