Structured Rego

About Structured Rego

The Platform uses a structured form of Rego to create Policies.

Rego is a declarative, context-aware language for authoring Policies and supports the Open Policy Agent (OPA).

Policies written in structured Rego can be imported to the Platform, where they will be visible with the UI and a Policy Map will be available. Any Policy available in PlainID administration point can be exported to Structured Rego.

Sample Structured Rego Policy

Following is a sample Policy that is expressed in Rego. In this case, the Policy specifies that Gold member customers and Standard customers (WHO) can view and manage their personal accounts and credit cards (WHAT).

# METADATA
# custom:
#   plainid:
# 	policyId: 08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825
# 	name: Manage personal account and Credit cards
# 	description: Customers can view and manage their account’s credit cards only with MFA
# 	accessType: Allow
package sample_policy
import future.keywords
 
# METADATA
# custom:
#   plainid:
# 	kind: DynamicGroup
# 	name: Gold member customers
dynamic_group(identity) {
	identity.template == "User"
	identity["User_Type"] == "External"
	identity["Membership_Type"] == "Gold"
}
# METADATA
# custom:
#   plainid:
# 	kind: DynamicGroup
# 	name: Standard Customers
dynamic_group1(identity) {
	identity.template == "User"
	identity["User_Type"] == "External"
	identity["Membership_Type"] == "Standard"
}
 
# METADATA
# custom:
#   plainid:
# 	kind: Ruleset
# 	name: User personal bank accounts
# 	description: Any account where the owner is the user currently trying to access
ruleset (asset, identity) {
	asset.template == "Bank Accounts"
	identity.template == "User"
	asset["account_owner"] == identity.Userid
}
 
# METADATA
# custom:
#   plainid:
# 	kind: Action
action(asset) {
	asset.template == "Bank Accounts"
	asset.action in ["Manage", "View"]
}
 
# METADATA
# custom:
#   plainid:
# 	kind: Ruleset
# 	name: User personal credit cards
# 	description: Any credit card where the owner is the user currently trying to access
ruleset(asset, identity) {
	asset.template == "Credit Cards"
	identity.template == "User"
	asset["card_owner"] == identity.Userid
}
 
# METADATA
# custom:
#   plainid:
# 	kind: Action
action(asset) {
	asset.template == "Credit Cards"
	asset.action in ["Manage", "View"]
}

Policy In Structured Rego

The structure of the Policy in Rego and each of its Rules are detailed in the following section as they would appear based on the sample Policy shared above.

Policy METADATA Comment Block

The Policy METADATA Comment Block contains general Details  about the Policy.

Example

# METADATA
# custom:
#   plainid:
# 	policyId: 08ae32e4-fbf3-4cc8-b3b9-3b4061d1c825
# 	name: Manage personal account and Credit cards
# 	description: Customers can view and manage their account’s credit cards only with MFA
# 	accessType: Allow
package sample_policy
import future.keywords

WHO In Structured Rego

The WHO section represents WHO will get access defined in that Policy. In our sample Policy, we have:

• WHO (DynamicGroup): Gold member customers
• WHO (DynamicGroup): Standard  customers

The Rego rule representing the Dynamic Group begins with a METADATA comment section

Example:

# METADATA
# custom:
#   plainid:
# 	kind: DynamicGroup
# 	name: Gold member customers

The Rule body contains the expressions which define Who access granted by this Dynamic Group.

Example:

dynamic_group(identity) {
	identity.template == "User"
	identity["User_Type"] == "External"
	identity["Membership_Type"] == "Gold"
}

under the specific Attribute form.

Supported Operators: Equals, Not equals, Contains, Starts with, Ends with, Greater than, Greater or equals, Less than, Less than or equals

The inserted value should be valid for the Attribute type.

In the following example:

identity[“User_Type”] == identity[“Membership_Type”] |

WHAT In Structured Rego

The WHAT in Rego can contain several Rules to specify WHAT Assets and WHAT Actions are part of the Policy. In our sample Policy, we have:

• WHAT (Ruleset): personal bank accounts
• WHAT (Ruleset): personal credit card
• WHAT (Action): view, manage

WHAT For Ruleset

The Rego rule representing the Ruleset begins with a METADATA comment section.

Example:

# METADATA
# custom:
#   plainid:
#     kind: Ruleset
#     name: bank accounts of location
}

The Rule body contains the expressions which define WHAT access is granted by this Ruleset.

Example 1:

ruleset(asset, identity, requestParams){
	asset.template == "Bank Accounts"
	identity.template == "User"
	asset["account_location"] == identity["User_Location"]
}

Example 2:

ruleset(asset, identity,requestParams){
	asset.template == "Bank Accounts"
	asset["account_owner"] == requestParams["owner"]
	}
}

WHAT For Action

Actions are optional. Asset Templates may or may not have Actions associated with it.

If Actions are associated with the Asset Template and used in Rulesets, then the Actions must be defined as part of the WHAT in the structured Rego.

The Rego rule representing the Action begins with a METADATA comment section.

Example:

# METADATA
# custom:
#   plainid:
# 	kind: Action

The Rule body contains the expressions which define WHAT Actions are granted by this Policy.

Example:

action (asset){
        asset.template == "Bank Accounts"
        asset.action in ["Manage", "View"]
}

WHEN in Structured Rego

Conditions are external factors that you may want to use to create more flexible and precise Policies. With Conditions, you can allow or restrict Member actions based on:

• IP
• Identity Attributes
• Request Attributes

The Rego rule representing the Conditions always begins with a METADATA comment section.

WHEN for IP Conditions

IP Conditions allow or restrict users based on a preconfigured IP range.

Example:

# METADATA
# custom:
#   plainid:
#     kind: Condition IP
#     name: Local IP

The body contains the expressions which define WHEN access is granted or denied by this Condition.

Example 1:

condition_ip(env)
    {
	net.cidr_contains("10.0.0.0/8", env.sourceIp)
}

Example 2:

condition_ip(env)
    {
	not net.cidr_contains("10.0.0.0/8", env.sourceIp)
}

WHEN for Identity Attributes

Identity Attribute Conditions allow or restricts access based on an attribute associated to the Identity - like all users of a specific department; all users within a specific location (country, city, region, etc.), all users with a** specific title**.

Example:

# METADATA
# custom:
#   plainid:
#     kind: Condition Identity
#     name: User Site is USA

The body contains the expressions which define WHEN access is granted by this Condition.
Example 1:

    condition_identity(identity)
{
	identity.template == "User"
	identity["Site"] == "USA"
}

WHEN for Request Attributes

Request Attribute Conditions allow or restrict access based on the value of a specific request parameter.

Example:

# METADATA
# custom:
#   plainid:
#     kind: Condition Request
#     name: MFA Authentication
}

The body contains the expressions which define WHEN access is granted by this Condition.
Example 1:

condition_request(requestParams, identity)
{
	requestParams["Auth_Method"] == "MFA"
}

Example 2:

condition_request(requestParams, identity)
{
	identity.template == "User"
	requestParams["Auth_Method"] == identity["userMethod"]
}

Structured Rego Guidelines

Each Policy is represented as a single Rego Module (package) and is constructed using the following syntax rules:

• Each Policy file begins with a # METADATA comment block. This block contains the metadata for the Policy (Policy Name, Policy ID, Description and Access Type (Allow/Deny), etc.)
• Each Rule within Rego begins with an expression that specifies which Identity Template or Asset Template is being used (see Policy Structure in Rego for details).
• All Rego Rules are preceded by a # METADATA comment block, which contains the metadata about the building block, including its type (Dynamic Group, Ruleset, etc., and optionally other information such as name, to find the Asset Template ID.
• The expressions must conform to a strict format, wherein a value from the source is compared to a value (or a set of values) appearing directly in the expression, using an operator such as ==, <, > etc.
• Multiple statements may exist within a Rule. When there is more than one statement within a Rule, the statements are evaluated with an AND relationship between them.
• Multiple Rego Rules may exist for one building block. When there is more than one Rego Rule for a Building Block, the Rules are evaluated with an OR relationship between them
• Each such expression is a comparison between an Attribute and a fixed value, or between two Attributes.
• Attributes, which are defined as part of the Template (either an Identity Template in the case of Dynamic Groups and an Asset Template in the case of Rulesets), can source their values either from the Authorization Request itself, or from an external data source. Depending on the type of the Building Block, different operators are allowed in an expression. For details, please see the PlainID Policy Authoring documentation.
• Annotated code is validated to contain only expressions that use supported operators, and only access attributes that exist in the relevant Identity or Asset Templates.

Structured Rego Ordering Best Practices

To import a Policy into PlainID, these blocks and their parameters must be included in the Policy file:

• Policy metadata
• Dynamic Groups and Rulesets
  • Actions (optional)
  • Conditions (optional)

Note: All Structured Rego files include these constant parameters:

• METADATA
• custom
• plainid

When a Policy is exported from PlainID as a Rego file, the Policy Structured Rego is organized in the following manner:

• Policy metadata Block:

  • policyId
  • name
  • description (optional)
  • accessType

• Dynamic Group Block (sorted alphabetically by name):

  • kind
  • name
  • dynamic_group(identity)
    • identity.template
    • identity[{“IdentityAttName”}]

• Ruleset Block (sorted alphabetically by Asset Type Name and their associated Rulesets):

  • kind
  • name
  • ruleset(asset, identity)
    • asset.template
    • identity.template (optional)
    • asset[{“AssetAttName”}]

• Action Block (sorted alphabetically by Asset Type Name and their associated Action):

  • kind
  • name
  • action(asset)
    • asset.template
    • asset.action in[{“ActionName”}]

• Condition Block (sorted alphabetically by type and their associated Condition):

  • Type: Condition IP

    • kind
    • name
    • condition_ip(env)
    • net.cidr_contains ({“IPRange”}, env.sourceIp)

  • Type: Condition Request

    • kind
    • name
    • condition_request(requestParams, identity)
    • identity.template (optional)
    • requestParams[{“RequestAtt”}]

  • Type: Condition Identity

    • kind
    • name
    • condition_identity(identity)
    • identity.template
    • identity[{“IdentityAttName”}]
      
      

It is recommended to keep Rego files in the order returned by the Export API (or the code output of the Import API) to ensure that changes in the Policy via the console do not result in major differences in code. If the Rego files are managed in a source control system (such as Git), keeping the export order will result in minimal diffs between versions.