Key Concepts¶

SEAL has a couple of key concepts that are important to grasp.

policy is a set of rules that specifies authorization decisions for resources.
rule defines one singular action to apply to one specific operation depending on conditions.
subject is an authenticated principal. This is an entity that has passed the authN step in the request process.
permission is low level operation that is trying to be performed. In SEAL, we group permissions into verbs (aka roles). Permissions are what applications check in order to
verb is an operation that a subject is trying to perform. Verbs can also be thought of as roles with the caveat that they should be evocative so that they are easy to read in a policy rule.
action is a consequence of a policy rule decision. The default action, for example, could be deny. In opa terms, this is a decision.
resource-type is a resource that is being secured. In many cases these are domain objects in the system under use. Sometimes, they are synthetic (made up) types that aren’t stored anywhere but created in order to model authorization requests.
resource-family is a group of resources that can be referenced together in policy rules. This allows policy rules to be more succinct if the overall policy needs to have access to several types.

From these basic concepts, SEAL allows users to create action rules that describe an authorization policy. For example:

allow subject group foo to manage products.*;

In the above rule, subjects who are in the foo group can manage any types that are in the products resource family. The verbs referenced in action rules can also be defined. SEAL ships with some predefined verbs and permissions to get you started.

Subjects¶

SEAL is used to authorize someone against some resources. In this context, someone is called a subject. A subject can be a user or group. To reference a user in a policy rule you can use the “user” keyword. Likewise, to reference a group in a policy rule you can use the “group” keyword.

allow subject user someone@acme.com to manage products.inventory;

or

allow subject group finance to manage accounts.*;

Permissions¶

Permissions are string that define a type of authorization or consent. Permissions can be defined as valid for a type or type family. For many applications that follow the familiar CRUD model, it may make sense to define a permission for every type of operation: create, read, update & delete. In kubernetes, there is a standard set of operations:

define permission watch on *;
define permission list on *;
define permission get on *;
define permission create on *;
define permission update on *;
define permission delete on *;

Verbs¶

Verbs are actions that a policy author can reference. These verbs are used to group permissions together much in the same way a role is used in traditional RBAC. The difference is that the permissions that are referenced can themselves only be valid for specific types.

define verb read from permission watch, list, get;
define verb use from permission update and verb read;
define verb manage from permission create, delete and verb use;

Actions¶

Actions are the results of policy rule decisions. In SEAL, you can reference actions by associating them with a resource type. A very common set of actions is defined below.

openapi: "3.0.0"
components:
  schemas:
    products.inventory:
      type: object
      x-seal-actions:
      - allow
      - deny
      x-seal-default-action: deny

Sometimes it is usefull to allow actions to have parameters. For example, you may want to log a special log message if a particular action is taken.

 openapi: "3.0.0"
 components:
    schemas:
      allow:
        type: object
        properties:
          log:
            type: string
        x-seal-type: action
      products.inventory:
        type: object
        x-seal-actions:
        - allow
        - deny
        x-seal-default-action: deny

These versions of allow & deny would permit the following syntax:

allow (log="my special rule") subject user someone@acme.com to manage products.inventory;