Cloud API 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.

ClaimCenter example:

The following code defines the permissions for the Claims resource (for a collection of claims) as declared in the policyNumbers_core-1.0access.yaml file. The view permission is always granted. The create permission is granted if the Gosu expression user.hasPolicyAccess(resource, Optional.of(data)) returns true.

Claims:
  permissions:
    view: true
    create: "user.hasPolicyAccess(resource, Optional.of(data))"

PolicyCenter 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

BillingCenter example:

For example, the following code defines the permissions for the Accounts resource (for a collection of accounts) as declared in the internal_core-1.0access.yaml file. The view permission is granted if the caller has the acctabview and acctsummview permissions. The create permission is granted if the user has the acctcreate permission.

Accounts:
  permissions:
    view:
    - perm.System.accttabview
    - perm.System.acctsummview
    create: perm.System.acctcreate

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.

ClaimCenter example:

The following specifies permissions for the Claim entity. Note that is specifies standard view and edit permissions as well as a custom business action permission, close.

Claim:
  permissions:
    view: "perm.Claim.view(resource.Claim)"
    edit: "perm.Claim.edit(resource.Claim)"
    ...
    close: "perm.Claim.close(resource.Claim)"
    ...
PolicyCenter 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 ClaimActivities...view: __inherit in ClaimCenter, for example)
  • 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.

ClaimCenter example:
CheckSets:
  permissions:
    view:
      - __inherit
      - "perm.Claim.viewpayments(resource.Claim)"
PolicyCenter example:
Account:
  permissions:
    purge:
    - "perm.Account.edit(resource.Account)"
    - "perm.System.purge"
BillingCenter example:
Accounts:
  permissions:
    view:
    - perm.System.accttabview
    - perm.System.acctsummview