Resource access files: permissions

In a resource access file, both individual element resources (such as Activity) and collection resources (such as Activities) can have a permissions section. This section defines the actions associated users can take on accessible resources.

The permissions section consists of a list of permissions, each of which is followed by a Boolean expression. The permission is granted if and only if the Boolean expression returns true.

For example, the following code defines the permissions for the Account resource (for a single account resource) as declared in the accountholder_core-1.0access.yaml file. The view permission is granted is either Gosu expression returns true. The freeze permission is never granted.

Account:
  permissions:
    view:     "gw.rest.core.pc.security.v1.AccountHolderSecurityUtil.
               canAccessAccount(resource.Account) || resource.Account.New"
    freeze: false
    purge: false
    unfreeze: false

Permissions for element resources

For individual elements, you can specify view, create, edit, and delete permissions. You can also specify permissions for custom business actions. For example, if there is a POST /activities/{activityId}/assign endpoint, then for an Activity resource, you can specify an assign permission. For custom actions, the permission name must match the verb used at the end of the endpoint path.

For example, the following specifies permissions for the Job entity. Note that is specifies standard view and edit permissions as well as a custom business action permission, quote.

Job:
  permissions:
    view: "gw.rest.core.pc.security.v1.AccountHolderSecurityUtil.canView(resource.Job)"
    edit: "gw.rest.core.pc.security.v1.AccountHolderSecurityUtil.canEdit(resource.Job)"
    ...
    quote: "gw.rest.core.pc.security.v1.AccountHolderSecurityUtil.canQuote(resource.Job)"
    ...
Warning: If you create a new endpoint that executes a custom action, do not name the endpoint with a name that would conflict with a base permission, such as view, edit, create, or delete. Doing so will result in unexpected permission behaviors.

If a given permission is not specified in an access file, then the permission defaults to the permission of the resource's parent. If a given resource does not have a permissions section, then all permissions default to the permission of the resource's parent.

Possible Boolean expressions

Any Gosu expression that returns true or false can be used as a permission's Boolean expression.

For permissions, the base configuration includes the following types of Boolean expressions:

  • A Boolean value
  • The keyword __inherit (in which case the permission is inherited from the resource's parent, such as AccountActivities...view: __inherit)
  • A Gosu expression, including:
    • A Gosu system perm expressions (such as "perm.system.actview")
    • A Gosu resource perm expressions (such as "perm.Activity.view(resource.Activity)")
    • A Gosu expression (such as "!resource.Note.Confidential || resource.Note.Author == entity.User.util.CurrentUser || perm.Claim.viewconfidentialnotes(resource.Note.Claim)")
    • A Gosu method declared at the system API layer (such as "gw.rest.core.pl.util.v1.ActivityInternalPermissionUtil.canApprove(resource.Activity)")

For more information on writing Gosu expressions that check for system permissions or resource permissions, refer to the Rules Guide.

In some cases, multiple expressions are listed on several lines, such as the following example. In this case, the expressions are ANDed together. All expressions must return true for the permission to be granted.

Account:
  permissions:
    purge:
    - "perm.Account.edit(resource.Account)"
    - "perm.System.purge"