SPDL - Security Policy Definition Language

Syntax

Keywords

The reserved keywords in SPDL are as follows. You cannot use any of these keywords as user name, group name, action, resource, attribute name, and so on.

• role
• user
• group
• entity
• grant
• deny
• if
• in
• on
• from

The keywords are all case-insensitive, which means that you cannot use one of “role”, “ROLE”, “Role”, “rOLe”, etc as user name, group name, action, resource, attribute name, and so on.

Naming Convention

User Name: a user name consists of letters, decimal digits, punctuation marks except for comma  i.e. [\p{L}\p{Nd}[\p{Punct}&&[^,]]]+

Group Name: a group name consists of letters, decimal digits, punctuation marks except for comma i.e. [\p{L}\p{Nd}[\p{Punct}&&[^,]]]+

Role Name: a role name consists of letters, decimal digits, punctuation marks except for comma i.e. [\p{L}\p{Nd}[\p{Punct}&&[^,]]]+

Action: an action consists of letters, decimal digits, punctuation marks except for comma i.e. [\p{L}\p{Nd}[\p{Punct}&&[^,]]]+

Resource: a resource consists of letters, decimal digits, punctuation marks i.e. [\p{L}\p{Nd}\p{Punct}]+

Please see Unicode Standard and Javadoc for the definition of letter, decimal digit, and punctuation mark.

Syntax

POLICY = EFFECT SUBJECT ACTION RESOURCE if CONDITION
EFFECT = grant | deny
SUBJECT = AND_PRINCIPALS (, AND_PRINCIPALS)*
AND_PRINCIPALS = PRINCIPAL | \( PRINCIPAL_LIST \)
PRINCIPAL_LIST = PRINCIPAL (, PRINCIPAL)*
PRINCIPAL = PRINCIPAL_TYPE PRINCIPAL_NAME [PRINCIPAL_IDD]
PRINCIPAL_TYPE = user|group|entity|role
PRINCIPAL_IDD = from IDD_IDENTIFIER
IDD_IDENTIFIER = [\p{L}\p{Nd}\p{Punct}]+
ACTION = (ACTION_IDENTIFIER)(, ACTION_IDENTIFIER)*
RESOURCE = RESOURCE_IDENTIFIER
PRINCIPAL_NAME = [\p{L}\p{Nd}[\p{Punct}&&[^,]]]+
ACTION_IDENTIFIER = [\p{L}\p{Nd}[\p{Punct}&&[^,]]]+
RESOURCE_IDENTIFIER = [\p{L}\p{Nd}\p{Punct}]+

ROLE_POLICY = EFFECT SUBJECT ROLE (on RESOURCE)? if CONDITION
EFFECT = grant | deny
SUBJECT = PRINCIPAL (, PRINCIPAL)*
PRINCIPAL = PRINCIPAL_TYPE PRINCIPAL_NAME [PRINCIPAL_IDD]
PRINCIPAL_TYPE = user|group|entity|role
PRINCIPAL_IDD = from IDD_IDENTIFIER
IDD_IDENTIFIER = [\p{L}\p{Nd}\p{Punct}]+
ROLE = (role)? SUBJECT_IDENTIFIER
RESOURCE = RESOURCE_IDENTIFIER
SUBJECT_IDENTIFIER = [\p{L}\p{Nd}[\p{Punct}&&[^,]]]+
RESOURCE_IDENTIFIER = [\p{L}\p{Nd}\p{Punct}]+

Condition

1. Overview

Condition is supported in both policy and role policy definitions. The policy or role policy can take effect only when the condition is met.

This document focuses on what a condition is, and how to write a condition.

2. Condition

A condition is a bool expression that is constructed using attributes, functions, constants, operators, comparators or parenthesis and produces a bool value.

2.1 Data Types

The data type of an attribute value and constant can be a string, numeric, bool, datetime or an array of string, numeric, bool, datetime.
The data types and the corresponding supported operators and comparators are listed in following table.

Most comparators are self explanatory, here is the annotation for "=~":
"=~" is the regex comparator. It uses Go’s standard regexp flavor of regex. The left side is expected to be the candidate string; the right side is the pattern. "=~" returns whether or not the candidate string matches the regex pattern given on the right.

• Left side: string
• Right side: string
• Returns: bool

2.2 Attributes

An attribute in a condition represents a variable. The attribute value is determined at runtime, obtained from either the Authorization Decision Service (ADS) runtime or the customer. Built-in attributes are those values that are populated by the ADS runtime. Customer attributes are those values that are provided by the customer when asking the ADS for authorization decisions.

2.2.1 Built-in Attributes

Built-in attributes are as follows:

2.2.2 Customer Attributes

2.2.2.1 name

A valid customer attribute name is a sequence of letters, digits or the underscore character " _ ". It must begin with a letter, and is limited to 255 characters. Customer attribute names must adhere to this rule, and should not use any reserved words (built-in attribute, built-in function name, operators, comparators) as attribute names.

2.2.2.2 value

When customer attributes are used in a condition, the customer needs to pass the customer attribute values when requesting an isAllowed result.

• Passing attribute values in Golang API
  Adhere to these rules when passing customer attribute values to a Golang API:

  • Use Golang bool type for bool attribute value.
  • Use Golang string type for string attribute value.
  • Use Golang float64 type for any numeric attribute value.
  • For datetime attribute value, use a Golang float64 representation of that datetime’s Unix time (using time.Time.Unix()).
  • Use Golang []interface{} for array attribute value.

• Passing attribute values in REST API
  Adhere to these rules when passing customer attribute values to a REST API:

  • Attribute is a struct, which contains name, type, value of the attribute. See the REST API for details.
  • Attribute type can be only “string”, “numeric”, “bool” or “datetime”.
  • Attribute value can be a single value or a slice.

2.3 Constants

Supported data types:

• string: single quotes, ‘foobar’
• numeric: 10, 3.1415926
• bool: true or false
• datetime: single quotes, conform to RFC3339. Datetime of RFC3339 format is YYYY-MM-DDTHH:mm:SS[.sssssssss]Z, Z is [+|-]HH:mm.
• array: array of type string, numeric, bool, datetime

The following table shows sample constants.

2.4 Functions

Use functions when existing operators or comparators do not meet customer requirements.

2.4.1 Built-in Functions

Speedle provides the following built-in functions.

2.4.2 Custom Functions

Customers can also expose their own functions through a REST API, and use custom functions in a condition expression.
For details, see custom function.

2.5 Operator/Comparator Precedence

2.5.1 Precedence order

When two operators share an operand, the operator with the higher precedence goes first. For example, 1 + 2 * 3 is treated as 1 + (2 * 3), whereas 1 * 2 + 3 is treated as (1 * 2) + 3 because multiplication has a higher precedence than addition.

2.5.2 Associativity

When an expression has two operators with the same precedence, the expression is evaluated according to its associativity. 72 / 2 / 3is treated as (72 / 2) / 3 because the / operator has left-to-right associativity. Some operators are not associative: for example, the expressions (x <= y <= z) and x++-- are invalid.

2.5.3 Precedence and Associativity of Supported Operators and Comparators

The following table lists all supported operators/comparators from highest to lowest precedence, along with their associativity.

2.6 Sample Conditions

Condition Definition

Condition should be a valid bool expression. The bool expression Speedle supports is strictly defined as follows:

BoolExpr: ('!')BoolExpr
          | BoolExpr ('&&'|'||') BoolExpr
		  | BoolConstant
		  | Attribute
		  | Function
		  | RelationalExpr
		  | '(' BoolExpr ')'


RelationalExpr: NumericExpr ('=='|'!='|'>'|'>='|'<'|'<=') NumericExpr
              | StringExpr ('=='|'!='|'=~'|'>'|'>='|'<'|'<=') StringExpr
			  | BoolExpr ('=='|'!=') BoolExpr
			  | DateTimeExpr ('=='|'!='|'>'|'>='|'<'|'<=') DateTimeExpr
			  | (NumericExpr|StringExpr|BoolExpr|DateTimeExpr) ('in') ArrayExpr


NumericExpr: NumericExpr('+'|'-'|'*'|'/'|'%')NumericExpr
           | NumericConstant
		   | Attribute
		   | Function
		   | '(' NumericExpr ')'

StringExpr: StringExpr('+') StringExpr
           | StringConstant
		   | Attribute
		   | Function
           | '(' StringExpr ')'

DateTimeExpr: DateTimeConstant
           | Attribute
           | Function

ArrayExpr: ArrayConstant
         | Attribute
         | Function

ArrayConstant: '('Constant [, Constant]* ')'

Constant: NumericConstant
         |StringConstant
         |BoolConstant
         |DateTimeConstant

NumericConstant: any numeric float64 data
StringConstant: single quoted string, for example, 'string1'
BoolConstant: true|false
DateTimeConstant: single quoted datetime, datetime should conform to the format defined by RFC3339: YYYY-MM-DDTHH:mm:SS[.sssssssss]Z, Z is [+|-]HH:mm. For example, '2016-01-02T15:04:05-07:00'

Attribute: attribute name should conform to  [a-zA-Z]+[a-zA-Z0-9_]*, length should be <=255
Function: FuntionName '(' Argument [,Argument]* ')'

Appendix

Full Syntax of SPDL