Access Control

OpenZeppelin Contracts provides AccessControl for implementing role-based access control. Its usage is straightforward: for each role that you want to define, you will create a new role identifier that is used to grant, revoke, and check if an account has that role.

Here’s a simple example of using AccessControl in an ERC20 token to define a 'minter' role, which allows accounts that have it create new tokens:

While clear and explicit, this isn’t anything we wouldn’t have been able to achieve with Ownable. Indeed, where AccessControl shines is in scenarios where granular permissions are required, which can be implemented by defining multiple roles.

Let’s augment our ERC20 token example by also defining a 'burner' role, which lets accounts destroy tokens, and by using the onlyRole modifier:

So clean! By splitting concerns this way, more granular levels of permission may be implemented than were possible with the simpler ownership approach to access control. Limiting what each component of a system is able to do is known as the principle of least privilege, and is a good security practice. Note that each account may still have more than one role, if so desired.

The ERC20 token example above uses _grantRole, an internal function that is useful when programmatically assigning roles (such as during construction). But what if we later want to grant the 'minter' role to additional accounts?

By default, accounts with a role cannot grant it or revoke it from other accounts: all having a role does is making the hasRole check pass. To grant and revoke roles dynamically, you will need help from the role’s admin.

Every role has an associated admin role, which grants permission to call the grantRole and revokeRole functions. A role can be granted or revoked by using these if the calling account has the corresponding admin role. Multiple roles may have the same admin role to make management easier. A role’s admin can even be the same role itself, which would cause accounts with that role to be able to also grant and revoke it.

This mechanism can be used to create complex permissioning structures resembling organizational charts, but it also provides an easy way to manage simpler applications. AccessControl includes a special role, called DEFAULT_ADMIN_ROLE, which acts as the default admin role for all roles. An account with this role will be able to manage any other role, unless _setRoleAdmin is used to select a new admin role.

Since it is the admin for all roles by default, and in fact it is also its own admin, this role carries significant risk. To mitigate this risk we provide AccessControlDefaultAdminRules, a recommended extension of AccessControl that adds a number of enforced security measures for this role: the admin is restricted to a single account, with a 2-step transfer procedure with a delay in between steps.

Let’s take a look at the ERC20 token example, this time taking advantage of the default admin role:

Note that, unlike the previous examples, no accounts are granted the 'minter' or 'burner' roles. However, because those roles' admin role is the default admin role, and that role was granted to msg.sender, that same account can call grantRole to give minting or burning permission, and revokeRole to remove it.

Dynamic role allocation is often a desirable property, for example in systems where trust in a participant may vary over time. It can also be used to support use cases such as KYC, where the list of role-bearers may not be known up-front, or may be prohibitively expensive to include in a single transaction.

Because accounts might grant and revoke roles dynamically, it is not always possible to determine which accounts hold a particular role. This is important as it allows proving certain properties about a system, such as that an administrative account is a multisig or a DAO, or that a certain role has been removed from all users, effectively disabling any associated functionality.

Under the hood, AccessControl uses EnumerableSet, a more powerful variant of Solidity’s mapping type, which allows for key enumeration. getRoleMemberCount can be used to retrieve the number of accounts that have a particular role, and getRoleMember can then be called to get the address of each of these accounts.

By default, the address that deployed the TimelockController gets administration privileges over the timelock. This role grants the right to assign proposers, executors, and other administrators.

The first step in configuring the TimelockController is to assign at least one proposer and one executor. These can be assigned during construction or later by anyone with the administrator role. These roles are not exclusive, meaning an account can have both roles.

Roles are managed using the AccessControl interface and the bytes32 values for each role are accessible through the ADMIN_ROLE, PROPOSER_ROLE and EXECUTOR_ROLE constants.

There is an additional feature built on top of AccessControl: giving the executor role to address(0) opens access to anyone to execute a proposal once the timelock has expired. This feature, while useful, should be used with caution.

At this point, with both a proposer and an executor assigned, the timelock can perform operations.

An optional next step is for the deployer to renounce its administrative privileges and leave the timelock self-administered. If the deployer decides to do so, all further maintenance, including assigning new proposers/schedulers or changing the timelock duration will have to follow the timelock workflow. This links the governance of the timelock to the governance of contracts attached to the timelock, and enforce a delay on timelock maintenance operations.

With both the proposer and executor roles assigned and the timelock in charge of its own administration, you can now transfer the ownership/control of any contract to the timelock.

Operations executed by the TimelockController are not subject to a fixed delay but rather a minimum delay. Some major updates might call for a longer delay. For example, if a delay of just a few days might be sufficient for users to audit a minting operation, it makes sense to use a delay of a few weeks, or even a few months, when scheduling a smart contract upgrade.

The minimum delay (accessible through the getMinDelay method) can be updated by calling the updateDelay function. Bear in mind that access to this function is only accessible by the timelock itself, meaning this maintenance operation has to go through the timelock itself.

OpenZeppelin Contracts provides AccessManager for managing roles across any number of contracts. The AccessManager itself is a contract that can be deployed and used out of the box. It sets an initial admin in the constructor who will be allowed to perform management operations.

In order to restrict access to some functions of your contract, you should inherit from the AccessManaged contract provided along with the manager. This provides the restricted modifier that can be used to protect any externally facing function. Note that you will have to specify the address of the AccessManager instance (initialAuthority) in the constructor so the restricted modifier knows which manager to use for checking permissions.

Here’s a simple example of an ERC20 token that defines a mint function that is restricted by an AccessManager:

Once the managed contract has been deployed, it is now under the manager’s control. The initial admin can then assign the minter role to an address and also allow the role to call the mint function. For example, this is demonstrated in the following Javascript code using Ethers.js:

Even though each role has its own list of function permissions, each role member (address) has an execution delay that will dictate how long the account should wait to execute a function that requires its role. Delayed operations must have the schedule function called on them first in the AccessManager before they can be executed, either by calling to the target function or using the AccessManager’s execute function.

Additionally, roles can have a granting delay that prevents adding members immediately. The AccessManager admins can set this grant delay as follows:

Note that roles do not define a name. As opposed to the AccessControl case, roles are identified as numeric values instead of being hardcoded in the contract as bytes32 values. It is still possible to allow for tooling discovery (e.g. for role exploration) using role labeling with the labelRole function.

Given the admins of the AccessManaged can modify all of its permissions, it’s recommended to keep only a single admin address secured under a multisig or governance layer. To achieve this, it is possible for the initial admin to set up all the required permissions, targets, and functions, assign a new admin, and finally renounce its admin role.

For improved incident response coordination, the manager includes a mode where administrators can completely close a target contract. When closed, all calls to restricted target functions in a target contract will revert.

Closing and opening contracts don’t alter any of their settings, neither permissions nor delays. Particularly, the roles required for calling specific target functions are not modified.

This mode is useful for incident response operations that require temporarily shutting down a contract in order to evaluate emergencies and reconfigure permissions.

An important aspect of the AccessControl contract is that roles aren’t granted nor revoked by role members. Instead, it relies on the concept of a role admin for granting and revoking.

In the case of the AccessManager, the same rule applies and only the role’s admins are able to call grant and revoke functions. Note that calling these functions will be subject to the execution delay that the executing role admin has.

Additionally, the AccessManager stores a guardian as an extra protection for each role. This guardian has the ability to cancel operations that have been scheduled by any role member with an execution delay. Consider that a role will have its initial admin and guardian default to the ADMIN_ROLE (0).

The AccessManager provides a built-in interface for configuring permission settings that can be accessed by its ADMIN_ROLE members.

This configuration interface includes the following functions:

As an admin, some actions will require a delay. Similar to each member’s execution delay, some admin operations require waiting for execution and should follow the schedule and execute workflow.

More specifically, these delayed functions are those for configuring the settings of a specific target contract. The delay applied to these functions can be adjusted by the manager admins with setTargetAdminDelay.

The delayed admin actions are:

Contracts already inheriting from Ownable can migrate to AccessManager by transferring ownership to the manager. After that, all calls to functions with the onlyOwner modifier should be called through the manager’s execute function, even if the caller doesn’t require a delay.

For systems already using AccessControl, the DEFAULT_ADMIN_ROLE can be granted to the AccessManager after revoking every other role. Subsequent calls should be made through the manager’s execute method, similar to the Ownable case.