### 6.2.10 Using Roles

[]()

 A MySQL role is a named collection of privileges. Like user accounts, roles can have privileges granted to and revoked from them.

 A user account can be granted roles, which grants to the account the privileges associated with each role. This enables assignment of sets of privileges to accounts and provides a convenient alternative to granting individual privileges, both for conceptualizing desired privilege assignments and implementing them.

 The following list summarizes role-management capabilities provided by MySQL:

* [`CREATE ROLE`](create-role.html) and [`DROP ROLE`](drop-role.html) create and remove roles.

* [`GRANT`](grant.html) and [`REVOKE`](revoke.html) assign privileges to revoke privileges from user accounts and roles.

* [`SHOW GRANTS`](show-grants.html) displays privilege and role assignments for user accounts and roles.

* [`SET DEFAULT ROLE`](set-default-role.html) specifies which account roles are active by default.

* [`SET ROLE`](set-role.html) changes the active roles within the current session.

* The [`CURRENT_ROLE()`](information-functions.html#function_current-role) function displays the active roles within the current session.

* The [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) and [`activate_all_roles_on_login`](server-system-variables.html#sysvar_activate_all_roles_on_login) system variables enable defining mandatory roles and automatic activation of granted roles when users log in to the server.

 For descriptions of individual role-manipulation statements (including the privileges required to use them), see [Section 13.7.1, “Account Management Statements”](account-management-statements.html). The following discussion provides examples of role usage. Unless otherwise specified, SQL statements shown here should be executed using a MySQL account with sufficient administrative privileges, such as the `root` account.

* [Creating Roles and Granting Privileges to Them](roles.html#roles-creating-granting)

* [Defining Mandatory Roles](roles.html#mandatory-roles)

* [Checking Role Privileges](roles.html#roles-checking)

* [Activating Roles](roles.html#roles-activating)

* [Revoking Roles or Role Privileges](roles.html#roles-revoking)

* [Dropping Roles](roles.html#roles-dropping)

* [User and Role Interchangeability](roles.html#role-user-interchangeability)

#### Creating Roles and Granting Privileges to Them

 Consider this scenario:

* An application uses a database named `app_db`.

* Associated with the application, there can be accounts for developers who create and maintain the application, and for users who interact with it.

* Developers need full access to the database. Some users need only read access, others need read/write access.

 To avoid granting privileges individually to possibly many user accounts, create roles as names for the required privilege sets. This makes it easy to grant the required privileges to user accounts, by granting the appropriate roles.

 To create the roles, use the [`CREATE ROLE`](create-role.html) statement:

```
CREATE ROLE 'app_developer', 'app_read', 'app_write';
```

 Role names are much like user account names and consist of a user part and host part in `'*`user_name`*'@'*`host_name`*'` format. The host part, if omitted, defaults to `'%'`. The user and host parts can be unquoted unless they contain special characters such as `-` or `%`. Unlike account names, the user part of role names cannot be blank. For additional information, see [Section 6.2.5, “Specifying Role Names”](role-names.html).

 To assign privileges to the roles, execute [`GRANT`](grant.html) statements using the same syntax as for assigning privileges to user accounts:

```
GRANT ALL ON app_db.* TO 'app_developer';
GRANT SELECT ON app_db.* TO 'app_read';
GRANT INSERT, UPDATE, DELETE ON app_db.* TO 'app_write';
```

 Now suppose that initially you require one developer account, two user accounts that need read-only access, and one user account that needs read/write access. Use [`CREATE USER`](create-user.html) to create the accounts:

```
CREATE USER 'dev1'@'localhost' IDENTIFIED BY 'dev1pass';
CREATE USER 'read_user1'@'localhost' IDENTIFIED BY 'read_user1pass';
CREATE USER 'read_user2'@'localhost' IDENTIFIED BY 'read_user2pass';
CREATE USER 'rw_user1'@'localhost' IDENTIFIED BY 'rw_user1pass';
```

 To assign each user account its required privileges, you could use [`GRANT`](grant.html) statements of the same form as just shown, but that requires enumerating individual privileges for each user. Instead, use an alternative [`GRANT`](grant.html) syntax that permits granting roles rather than privileges:

```
GRANT 'app_developer' TO 'dev1'@'localhost';
GRANT 'app_read' TO 'read_user1'@'localhost', 'read_user2'@'localhost';
GRANT 'app_read', 'app_write' TO 'rw_user1'@'localhost';
```

 The [`GRANT`](grant.html) statement for the `rw_user1` account grants the read and write roles, which combine to provide the required read and write privileges.

 The [`GRANT`](grant.html) syntax for granting roles to an account differs from the syntax for granting privileges: There is an `ON` clause to assign privileges, whereas there is no `ON` clause to assign roles. Because the syntaxes are distinct, you cannot mix assigning privileges and roles in the same statement. (It is permitted to assign both privileges and roles to an account, but you must use separate [`GRANT`](grant.html) statements, each with syntax appropriate to what is to be granted.) As of MySQL 8.0.16, roles cannot be granted to anonymous users.

 A role when created is locked, has no password, and is assigned the default authentication plugin. (These role attributes can be changed later with the [`ALTER USER`](alter-user.html) statement, by users who have the global [`CREATE USER`](privileges-provided.html#priv_create-user) privilege.)

 While locked, a role cannot be used to authenticate to the server. If unlocked, a role can be used to authenticate. This is because roles and users are both authorization identifiers with much in common and little to distinguish them. See also [User and Role Interchangeability](roles.html#role-user-interchangeability).

#### Defining Mandatory Roles

 It is possible to specify roles as mandatory by naming them in the value of the [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) system variable. The server treats a mandatory role as granted to all users, so that it need not be granted explicitly to any account.

 To specify mandatory roles at server startup, define [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) in your server `my.cnf` file:

```
[mysqld]
mandatory_roles='role1,role2@localhost,r3@%.example.com'
```

 To set and persist [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) at runtime, use a statement like this:

```
SET PERSIST mandatory_roles = 'role1,role2@localhost,r3@%.example.com';
```

[`SET PERSIST`](set-variable.html) sets a value for the running MySQL instance. It also saves the value, causing it to carry over to subsequent server restarts. To change the value for the running MySQL instance without having it carry over to subsequent restarts, use the `GLOBAL` keyword rather than `PERSIST`. See [Section 13.7.6.1, “SET Syntax for Variable Assignment”](set-variable.html).

 Setting [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) requires the [`ROLE_ADMIN`](privileges-provided.html#priv_role-admin) privilege, in addition to the [`SYSTEM_VARIABLES_ADMIN`](privileges-provided.html#priv_system-variables-admin) privilege (or the deprecated [`SUPER`](privileges-provided.html#priv_super) privilege) normally required to set a global system variable.

 Mandatory roles, like explicitly granted roles, do not take effect until activated (see [Activating Roles](roles.html#roles-activating)). At login time, role activation occurs for all granted roles if the [`activate_all_roles_on_login`](server-system-variables.html#sysvar_activate_all_roles_on_login) system variable is enabled, or for roles that are set as default roles otherwise. At runtime, [`SET ROLE`](set-role.html) activates roles.

 Roles named in the value of [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) cannot be revoked with [`REVOKE`](revoke.html) or dropped with [`DROP ROLE`](drop-role.html) or [`DROP USER`](drop-user.html).

 To prevent sessions from being made system sessions by default, a role that has the [`SYSTEM_USER`](privileges-provided.html#priv_system-user) privilege cannot be listed in the value of the [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) system variable:

* If [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) is assigned a role at startup that has the [`SYSTEM_USER`](privileges-provided.html#priv_system-user) privilege, the server writes a message to the error log and exits.

* If [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) is assigned a role at runtime that has the [`SYSTEM_USER`](privileges-provided.html#priv_system-user) privilege, an error occurs and the [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) value remains unchanged.

 Even with this safeguard, it is better to avoid granting the [`SYSTEM_USER`](privileges-provided.html#priv_system-user) privilege through a role in order to guard against the possibility of privilege escalation.

 If a role named in [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) is not present in the `mysql.user` system table, the role is not granted to users. When the server attempts role activation for a user, it does not treat the nonexistent role as mandatory and writes a warning to the error log. If the role is created later and thus becomes valid, [`FLUSH PRIVILEGES`](flush.html#flush-privileges) may be necessary to cause the server to treat it as mandatory.

[`SHOW GRANTS`](show-grants.html) displays mandatory roles according to the rules described in [Section 13.7.7.21, “SHOW GRANTS Statement”](show-grants.html).

#### Checking Role Privileges

 To verify the privileges assigned to an account, use [`SHOW GRANTS`](show-grants.html). For example:

```
mysql> SHOW GRANTS FOR 'dev1'@'localhost';
+-------------------------------------------------+
| Grants for dev1@localhost                       |
+-------------------------------------------------+
| GRANT USAGE ON *.* TO `dev1`@`localhost`        |
| GRANT `app_developer`@`%` TO `dev1`@`localhost` |
+-------------------------------------------------+
```

 However, that shows each granted role without “expanding” it to the privileges the role represents. To show role privileges as well, add a `USING` clause naming the granted roles for which to display privileges:

```
mysql> SHOW GRANTS FOR 'dev1'@'localhost' USING 'app_developer';
+----------------------------------------------------------+
| Grants for dev1@localhost                                |
+----------------------------------------------------------+
| GRANT USAGE ON *.* TO `dev1`@`localhost`                 |
| GRANT ALL PRIVILEGES ON `app_db`.* TO `dev1`@`localhost` |
| GRANT `app_developer`@`%` TO `dev1`@`localhost`          |
+----------------------------------------------------------+
```

 Verify each other type of user similarly:

```
mysql> SHOW GRANTS FOR 'read_user1'@'localhost' USING 'app_read';
+--------------------------------------------------------+
| Grants for read_user1@localhost                        |
+--------------------------------------------------------+
| GRANT USAGE ON *.* TO `read_user1`@`localhost`         |
| GRANT SELECT ON `app_db`.* TO `read_user1`@`localhost` |
| GRANT `app_read`@`%` TO `read_user1`@`localhost`       |
+--------------------------------------------------------+
mysql> SHOW GRANTS FOR 'rw_user1'@'localhost' USING 'app_read', 'app_write';
+------------------------------------------------------------------------------+
| Grants for rw_user1@localhost                                                |
+------------------------------------------------------------------------------+
| GRANT USAGE ON *.* TO `rw_user1`@`localhost`                                 |
| GRANT SELECT, INSERT, UPDATE, DELETE ON `app_db`.* TO `rw_user1`@`localhost` |
| GRANT `app_read`@`%`,`app_write`@`%` TO `rw_user1`@`localhost`               |
+------------------------------------------------------------------------------+
```

[`SHOW GRANTS`](show-grants.html) displays mandatory roles according to the rules described in [Section 13.7.7.21, “SHOW GRANTS Statement”](show-grants.html).

#### Activating Roles

 Roles granted to a user account can be active or inactive within account sessions. If a granted role is active within a session, its privileges apply; otherwise, they do not. To determine which roles are active within the current session, use the [`CURRENT_ROLE()`](information-functions.html#function_current-role) function.

 By default, granting a role to an account or naming it in the [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) system variable value does not automatically cause the role to become active within account sessions. For example, because thus far in the preceding discussion no `rw_user1` roles have been activated, if you connect to the server as `rw_user1` and invoke the [`CURRENT_ROLE()`](information-functions.html#function_current-role) function, the result is `NONE` (no active roles):

```
mysql> SELECT CURRENT_ROLE();
+----------------+
| CURRENT_ROLE() |
+----------------+
| NONE           |
+----------------+
```

 To specify which roles should become active each time a user connects to the server and authenticates, use [`SET DEFAULT ROLE`](set-default-role.html). To set the default to all assigned roles for each account created earlier, use this statement:

```
SET DEFAULT ROLE ALL TO
  'dev1'@'localhost',
  'read_user1'@'localhost',
  'read_user2'@'localhost',
  'rw_user1'@'localhost';
```

 Now if you connect as `rw_user1`, the initial value of [`CURRENT_ROLE()`](information-functions.html#function_current-role) reflects the new default role assignments:

```
mysql> SELECT CURRENT_ROLE();
+--------------------------------+
| CURRENT_ROLE()                 |
+--------------------------------+
| `app_read`@`%`,`app_write`@`%` |
+--------------------------------+
```

 To cause all explicitly granted and mandatory roles to be automatically activated when users connect to the server, enable the [`activate_all_roles_on_login`](server-system-variables.html#sysvar_activate_all_roles_on_login) system variable. By default, automatic role activation is disabled.

 Within a session, a user can execute [`SET ROLE`](set-role.html) to change the set of active roles. For example, for `rw_user1`:

```
mysql> SET ROLE NONE; SELECT CURRENT_ROLE();
+----------------+
| CURRENT_ROLE() |
+----------------+
| NONE           |
+----------------+
mysql> SET ROLE ALL EXCEPT 'app_write'; SELECT CURRENT_ROLE();
+----------------+
| CURRENT_ROLE() |
+----------------+
| `app_read`@`%` |
+----------------+
mysql> SET ROLE DEFAULT; SELECT CURRENT_ROLE();
+--------------------------------+
| CURRENT_ROLE()                 |
+--------------------------------+
| `app_read`@`%`,`app_write`@`%` |
+--------------------------------+
```

 The first [`SET ROLE`](set-role.html) statement deactivates all roles. The second makes `rw_user1` effectively read only. The third restores the default roles.

[]()[]()[]()[]()

 The effective user for stored program and view objects is subject to the `DEFINER` and `SQL SECURITY` attributes, which determine whether execution occurs in invoker or definer context (see [Section 25.6, “Stored Object Access Control”](stored-objects-security.html)):

* Stored program and view objects that execute in invoker context execute with the roles that are active within the current session.

* Stored program and view objects that execute in definer context execute with the default roles of the user named in their `DEFINER` attribute. If [`activate_all_roles_on_login`](server-system-variables.html#sysvar_activate_all_roles_on_login) is enabled, such objects execute with all roles granted to the `DEFINER` user, including mandatory roles. For stored programs, if execution should occur with roles different from the default, the program body can execute [`SET ROLE`](set-role.html) to activate the required roles. This must be done with caution since the privileges assigned to roles can be changed.

#### Revoking Roles or Role Privileges

 Just as roles can be granted to an account, they can be revoked from an account:

```
REVOKE role FROM user;
```

 Roles named in the [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) system variable value cannot be revoked.

[`REVOKE`](revoke.html) can also be applied to a role to modify the privileges granted to it. This affects not only the role itself, but any account granted that role. Suppose that you want to temporarily make all application users read only. To do this, use [`REVOKE`](revoke.html) to revoke the modification privileges from the `app_write` role:

```
REVOKE INSERT, UPDATE, DELETE ON app_db.* FROM 'app_write';
```

 As it happens, that leaves the role with no privileges at all, as can be seen using [`SHOW GRANTS`](show-grants.html) (which demonstrates that this statement can be used with roles, not just users):

```
mysql> SHOW GRANTS FOR 'app_write';
+---------------------------------------+
| Grants for app_write@%                |
+---------------------------------------+
| GRANT USAGE ON *.* TO `app_write`@`%` |
+---------------------------------------+
```

 Because revoking privileges from a role affects the privileges for any user who is assigned the modified role, `rw_user1` now has no table modification privileges ([`INSERT`](privileges-provided.html#priv_insert), [`UPDATE`](privileges-provided.html#priv_update), and [`DELETE`](privileges-provided.html#priv_delete) are no longer present):

```
mysql> SHOW GRANTS FOR 'rw_user1'@'localhost'
       USING 'app_read', 'app_write';
+----------------------------------------------------------------+
| Grants for rw_user1@localhost                                  |
+----------------------------------------------------------------+
| GRANT USAGE ON *.* TO `rw_user1`@`localhost`                   |
| GRANT SELECT ON `app_db`.* TO `rw_user1`@`localhost`           |
| GRANT `app_read`@`%`,`app_write`@`%` TO `rw_user1`@`localhost` |
+----------------------------------------------------------------+
```

 In effect, the `rw_user1` read/write user has become a read-only user. This also occurs for any other accounts that are granted the `app_write` role, illustrating how use of roles makes it unnecessary to modify privileges for individual accounts.

 To restore modification privileges to the role, simply re-grant them:

```
GRANT INSERT, UPDATE, DELETE ON app_db.* TO 'app_write';
```

 Now `rw_user1` again has modification privileges, as do any other accounts granted the `app_write` role.

#### Dropping Roles

 To drop roles, use [`DROP ROLE`](drop-role.html):

```
DROP ROLE 'app_read', 'app_write';
```

 Dropping a role revokes it from every account to which it was granted.

 Roles named in the [`mandatory_roles`](server-system-variables.html#sysvar_mandatory_roles) system variable value cannot be dropped.

#### User and Role Interchangeability

 As has been hinted at earlier for [`SHOW GRANTS`](show-grants.html), which displays grants for user accounts or roles, accounts and roles can be used interchangeably.

 One difference between roles and users is that [`CREATE ROLE`](create-role.html) creates an authorization identifier that is locked by default, whereas [`CREATE USER`](create-user.html) creates an authorization identifier that is unlocked by default. However, distinction is not immutable because a user with appropriate privileges can lock or unlock roles or users after they have been created.

 If a database administrator has a preference that a specific authorization identifier must be a role, a name scheme can be used to communicate this intention. For example, you could use a `r_` prefix for all authorization identifiers that you intend to be roles and nothing else.

 Another difference between roles and users lies in the privileges available for administering them:

* The [`CREATE ROLE`](privileges-provided.html#priv_create-role) and [`DROP ROLE`](privileges-provided.html#priv_drop-role) privileges enable only use of the [`CREATE ROLE`](create-role.html) and [`DROP ROLE`](drop-role.html) statements, respectively.

* The [`CREATE USER`](privileges-provided.html#priv_create-user) privilege enables use of the [`ALTER USER`](alter-user.html), [`CREATE ROLE`](create-role.html), [`CREATE USER`](create-user.html), [`DROP ROLE`](drop-role.html), [`DROP USER`](drop-user.html), [`RENAME USER`](rename-user.html), and [`REVOKE ALL PRIVILEGES`](revoke.html) statements.

 Thus, the [`CREATE ROLE`](privileges-provided.html#priv_create-role) and [`DROP ROLE`](privileges-provided.html#priv_drop-role) privileges are not as powerful as [`CREATE USER`](privileges-provided.html#priv_create-user) and may be granted to users who should only be permitted to create and drop roles, and not perform more general account manipulation.

 With regard to privileges and interchangeability of users and roles, you can treat a user account like a role and grant that account to another user or a role. The effect is to grant the account's privileges and roles to the other user or role.

 This set of statements demonstrates that you can grant a user to a user, a role to a user, a user to a role, or a role to a role:

```
CREATE USER 'u1';
CREATE ROLE 'r1';
GRANT SELECT ON db1.* TO 'u1';
GRANT SELECT ON db2.* TO 'r1';
CREATE USER 'u2';
CREATE ROLE 'r2';
GRANT 'u1', 'r1' TO 'u2';
GRANT 'u1', 'r1' TO 'r2';
```

 The result in each case is to grant to the grantee object the privileges associated with the granted object. After executing those statements, each of `u2` and `r2` have been granted privileges from a user (`u1`) and a role (`r1`):

```
mysql> SHOW GRANTS FOR 'u2' USING 'u1', 'r1';
+-------------------------------------+
| Grants for u2@%                     |
+-------------------------------------+
| GRANT USAGE ON *.* TO `u2`@`%`      |
| GRANT SELECT ON `db1`.* TO `u2`@`%` |
| GRANT SELECT ON `db2`.* TO `u2`@`%` |
| GRANT `u1`@`%`,`r1`@`%` TO `u2`@`%` |
+-------------------------------------+
mysql> SHOW GRANTS FOR 'r2' USING 'u1', 'r1';
+-------------------------------------+
| Grants for r2@%                     |
+-------------------------------------+
| GRANT USAGE ON *.* TO `r2`@`%`      |
| GRANT SELECT ON `db1`.* TO `r2`@`%` |
| GRANT SELECT ON `db2`.* TO `r2`@`%` |
| GRANT `u1`@`%`,`r1`@`%` TO `r2`@`%` |
+-------------------------------------+
```

 The preceding example is illustrative only, but interchangeability of user accounts and roles has practical application, such as in the following situation: Suppose that a legacy application development project began before the advent of roles in MySQL, so all user accounts associated with the project are granted privileges directly (rather than granted privileges by virtue of being granted roles). One of these accounts is a developer account that was originally granted privileges as follows:

```
CREATE USER 'old_app_dev'@'localhost' IDENTIFIED BY 'old_app_devpass';
GRANT ALL ON old_app.* TO 'old_app_dev'@'localhost';
```

 If this developer leaves the project, it becomes necessary to assign the privileges to another user, or perhaps multiple users if development activies have expanded. Here are some ways to deal with the issue:

* Without using roles: Change the account password so the original developer cannot use it, and have a new developer use the account instead:

  ```
  ALTER USER 'old_app_dev'@'localhost' IDENTIFIED BY 'new_password';
  ```

* Using roles: Lock the account to prevent anyone from using it to connect to the server:

  ```
  ALTER USER 'old_app_dev'@'localhost' ACCOUNT LOCK;
  ```

   Then treat the account as a role. For each developer new to the project, create a new account and grant to it the original developer account:

  ```
  CREATE USER 'new_app_dev1'@'localhost' IDENTIFIED BY 'new_password';
  GRANT 'old_app_dev'@'localhost' TO 'new_app_dev1'@'localhost';
  ```

   The effect is to assign the original developer account privileges to the new account.

