public interface Permission

A Permission represents the ability to perform an action or access a resource. A Permission is the most granular, or atomic, unit in a system's security policy and is the cornerstone upon which fine-grained security models are built.

It is important to understand a Permission instance only represents functionality or access - it does not grant it. Granting access to an application functionality or a particular resource is done by the application's security configuration, typically by assigning Permissions to users, roles and/or groups.

Most typical systems are what the Shiro team calls role-based in nature, where a role represents common behavior for certain user types. For example, a system might have an Aministrator role, a User or Guest roles, etc.

But if you have a dynamic security model, where roles can be created and deleted at runtime, you can't hard-code role names in your code. In this environment, roles themselves aren't aren't very useful. What matters is what permissions are assigned to these roles.

Under this paradigm, permissions are immutable and reflect an application's raw functionality (opening files, accessing a web URL, creating users, etc). This is what allows a system's security policy to be dynamic: because Permissions represent raw functionality and only change when the application's source code changes, they are immutable at runtime - they represent 'what' the system can do. Roles, users, and groups are the 'who' of the application. Determining 'who' can do 'what' then becomes a simple exercise of associating Permissions to roles, users, and groups in some way.

Most applications do this by associating a named role with permissions (i.e. a role 'has a' collection of Permissions) and then associate users with roles (i.e. a user 'has a' collection of roles) so that by transitive association, the user 'has' the permissions in their roles. There are numerous variations on this theme (permissions assigned directly to users, or assigned to groups, and users added to groups and these groups in turn have roles, etc, etc). When employing a permission-based security model instead of a role-based one, users, roles, and groups can all be created, configured and/or deleted at runtime. This enables an extremely powerful security model.

A benefit to Shiro is that, although it assumes most systems are based on these types of static role or dynamic role w/ permission schemes, it does not require a system to model their security data this way - all Permission checks are relegated to Realm implementations, and only those implementations really determine how a user 'has' a permission or not. The Realm could use the semantics described here, or it could utilize some other mechanism entirely - it is always up to the application developer.

Shiro provides a very powerful default implementation of this interface in the form of the WildcardPermission. We highly recommend that you investigate this class before trying to implement your own Permissions.