Security levels
API roles specify the resources that callers can access, and the properties on those resources that callers can view or edit. In an API role file, you can explicitly list each property and its view and edit access. However, there may be some situations where it is easier to grant access to a set of properties without explicitly naming all of them. In these situations, you can use security levels.
Security level is a property-level attribute that can be used by API roles to grant
view or edit permissions to a set of properties. API roles can grant view or edit permissions
using the "*level"
expression, which means "grant the permission to
all properties on this resource with the security level of level."
There are three security levels: internal, sensitive, and public. These levels are not hierarchical. Granting access to a specific security level does not inherently include any other security levels. Also, there is no inherent meaning tied to them. They are arbitrary labels that you can use in whatever way is most appropriate.
Specifying a field's security level
Security levels are set in the resource's schema file. The syntax is
"securityLevel": level
.
level
must be eitherinternal
,sensitive
, orpublic
.- If a property has no specified security level, it defaults to
public
.
For example, the following code snippet, from
policyperiod_core-1.0.schema.json
, declares two properties for the
Cost
resource:
"Cost": {
"properties": {
"adjustedRate": {
...
"securityLevel": "internal"
}
},
"amount": {
...
},
The adjustedRate
property has a security level of
internal
. The amount
property has no defined security
level, and therefore defaults to a security level of public
.
Using security levels in API roles
In an API role file, when specifying view and edit permissions for a given resource, you
can use the expression "*level"
to indicate "all properties on the
resource that have the specified level". For example, the following grants access to fields
on the Cost
resource. The grantee can edit and view all properties on the
Cost
resource that have a security level of public
as
well as the sortableId
property (which presumably is not a public field).
(Based on the previous code snippet, the grantee would be able to view and edit
amount
but not adjustedRate
.)
accessibleFields:
Cost:
edit:
- "*public"
- sortableId
view:
- "*public"
- sortableId
Additional behaviors of security levels
Security levels are not hierarchical. To grant access to multiple levels, all levels must
be listed explicitly. For example, the following grants edit access to all properties on the
Cost
resource that are public or sensitive:
Cost:
edit:
- ["*public", "*sensitive"]
If the view or edit section of a resource lists both explicit properties and a
"*level
" expression, the grantee has access to all explicitly
listed properties and all properties with the given security level. For example, the
following grants edit access to all properties on the Cost
resource that
are public as well as the sortableId
property:
Cost:
edit:
- "*public"
- sortableId