From 0096f5d06815b706b6df309102ef8dbd166be8f5 Mon Sep 17 00:00:00 2001 From: Madhan Neethiraj Date: Tue, 12 Dec 2023 13:23:49 -0800 Subject: [PATCH] RANGER-4587: blog: dynamic expressions - #2 --- .../resources/blogs/dynamic_expressions.html | 463 +++++++++++------- 1 file changed, 286 insertions(+), 177 deletions(-) diff --git a/docs/src/site/resources/blogs/dynamic_expressions.html b/docs/src/site/resources/blogs/dynamic_expressions.html index 039ad5a533..d9e6943f11 100644 --- a/docs/src/site/resources/blogs/dynamic_expressions.html +++ b/docs/src/site/resources/blogs/dynamic_expressions.html @@ -28,6 +28,10 @@ /* Style Definitions */ p.MsoNormal, li.MsoNormal, div.MsoNormal {margin:0in; font-size:12.0pt; font-family:"Calibri",sans-serif;} + p.MsoSmaller, li.MsoNormal, div.MsoNormal + {margin:0in; font-size:10.0pt; font-family:"Calibri",sans-serif;} + p.MsoSmall, li.MsoNormal, div.MsoNormal + {margin:0in; font-size:8.0pt; font-family:"Calibri",sans-serif;} p.HalfLine {margin:0in; font-size:6.0pt; font-family:"Calibri",sans-serif;} h1 @@ -59,11 +63,11 @@
-

Apache Ranger - Dynamic Expression

+

Apache Ranger - Dynamic Expressions

 

Madhan Neethiraj, Apache Ranger committer

-

Dec 10, 2023

+

Dec 12, 2023

 

@@ -79,21 +83,21 @@

Introduction

 

-

1. Consistent model to authorize access for data across large number of services

+

1. Consistent model to authorize access data in large number of services

 

-

2. Ability to dynamically apply data masking and row-filtering

+

2. Ability to dynamically apply data masking and row-filtering

 

-

3. Delegated access control administration

+

3. Delegated access control administration

 

-

4. Ability to explicitly deny access

+

4. Ability to explicitly deny access

 

-

5. Use of wildcards in resource names in access policies

+

5. Use of wildcards in resource names in access policies

 

-

6. Role-based access control (RBAC)

+

6. Role-based access control (RBAC)

 

-

7. Tag-based access control (TBAC), based on tags associated with resources

+

7. Tag-based access control (TBAC), based on tags associated with resources

 

-

8. Attribute-based access control (ABAC), based on attributes of users, groups and tags

+

8. Attribute-based access control (ABAC), based on attributes of users, groups and tags

 

 @@ -119,53 +123,67 @@

Dynamic expressions

Policy conditions

-

- Expressions used in policy conditions should evaluate to a boolean value i.e., true or false. Examples: + Expressions can used in policy conditions to decide whether to evaluate the policy or a policy-item. These + expressions should evaluate to a boolean value i.e., true + or false. Examples:

+

 

-

 

+

Condition for highly sensitive data (level >= 10)

+

 

+

TAG.sensitiveLevel >= 10

+

 

- -

TAG.sensitiveLevel >= 10

-

 

-

USER.allowedSensitiveLevel >= TAG.sensitiveLevel

-

 

-

IS_IN_GROUP('finance') AND IS_IN_ROLE('analyst')

-

 

- +

Condition to check if the user has appropriate level of clearance to access sensitive data

+

 

+

USER.allowedSensitiveLevel >= TAG.sensitiveLevel

+

 

+ +

Condition to check if the user belongs to group finance and is in role analyst

+

 

+

IS_IN_GROUP('finance') AND IS_IN_ROLE('analyst')

+

 

Row filters

- Expressions can be used to set up row-filters with dynamic values. To distinguish - expressions from the rest of the row-filter text, they should be enclosed within delimiters - ${{ and }}. Examples: + Expressions can be used to set up row-filters with dynamic values. To distinguish expressions from the rest + of the row-filter text, they should be enclosed within delimiters ${{ + and }}. Examples:

-

 

+

 

- -

dept_code == ${{USER.department}}

-

 

-

data_source in (${{USER.allowedSources}})

-

 

- +

Row-filter expression to restrict users to access only rows belonging to their department:

+

 

+

dept_code == ${{USER.department}}

+

 

+ +

Row-filter expression to restrict users to access only rows from data sources specified in user attribute named allowedSources:

+

 

+

data_source in (${{USER.allowedSources}})

+

 

Resource names

Use of expressions in resource names can help reduce the number of policies, which in turn makes it easier to manage policies. Examples:

+

 

-

 

+

Policy resource for home directory of the user:

+

 

+

/home/${{REQ.user}}

+

 

- -

/home/${{REQ.user}}

-

 

-

/data/dept/${{USER.dept}}

-

 

-

db_${{USER.dept}}

-

 

- +

Policy resource for directory of each user's department:

+

 

+

/data/dept/${{USER.dept}}

+

 

+ +

Policy resource for database of each user's department:

+

 

+

db_${{USER.dept}}

+

 

Supported expressions

 

@@ -175,10 +193,10 @@

Supported expressions

Variable/Function name

- +

Description

- +

Example values

@@ -186,365 +204,456 @@

Supported expressions

GET_TAG_NAMES()

- -

Names of tags associated with the resource, as CSV

+ +

Names of tags associated with the resource, as a CSV (comma separated values) string

- -

PII,FINANCE

+ +

PII,FINANCE

GET_TAG_ATTR_NAMES()

- -

Names of attributes in all tags associated with the resource, as CSV

+ +

Names of attributes in all tags associated with the resource, as a CSV string

- -

piiType,sensitiveLevel

+ +

piiType,sensitiveLevel

GET_TAG_ATTR(attrName)

- -

Value of the given attribute in tags associated with the resource, as CSV

+ +

Value of the given attribute in tags associated with the resource, as a CSV string

- -

email

+ +

email

GET_UG_NAMES()

- -

Names of groups the user belongs to, as CSV

+ +

Names of groups the user belongs to, as a CSV string

- -

managers,finance-admins

+ +

managers,finance-admins

GET_UG_ATTR_NAMES()

- -

Names of all attributes in groups the user belongs to, as CSV

+ +

Names of all attributes in groups the user belongs to, as a CSV string

- -

attr1,attr2

+ +

attr1,attr2

GET_UG_ATTR(attrName)

- -

Value of the given attribute in groups the user belongs to, as CSV

+ +

Value of the given attribute in groups the user belongs to, as a CSV string

- -

val1

+ +

val1

GET_UR_NAMES()

- -

Names of roles assigned to the user,  as CSV

+ +

Names of roles assigned to the user,  as a CSV string

- -

analyst,dba

+ +

analyst,dba

GET_USER_ATTR_NAMES()

- -

Names of all attributes of the user, as CSV

+ +

Names of all attributes of the user, as a CSV string

- -

allowedSensitiveLevel, allowedSources

-

 

-

 

+ +

allowedSensitiveLevel, allowedSources

GET_USER_ATTR(attrName)

- +

Value of the given attribute associated with the user

- -

10

+ +

10

HAS_TAG(tagName)

- +

Is the given tag associated with the resource?

- -

true

-

false

+ +

true

+

false

HAS_ANY_TAG

- +

Is any tag associated with the resource?

- -

true

-

false

+ +

true

+

false

HAS_NO_TAG

- +

Are not tags associated with the resource?

- -

true

-

false

+ +

true

+

false

HAS_USER_ATTR(attrName)

- +

Does the user have the given attribute?

- -

true

-

false

+ +

true

+

false

HAS_UG_ATTR(attrName)

- +

Does any group associated with the user have the specified attribute?

- -

true

-

false

+ +

true

+

false

HAS_TAG_ATTR(attrName)

- +

Does any tag associated with the resource have the specified attribute?

- -

true

-

false

+ +

true

+

false

IS_IN_GROUP(groupName)

- +

Does the user belong to the specified group?

- -

true

-

false

+ +

true

+

false

IS_IN_ROLE(roleName)

- +

Is the user assigned to the specified role?

- -

true

-

false

+ +

true

+

false

IS_IN_ANY_GROUP

- +

Does the user belong to any group?

- -

true

-

false

+ +

true

+

false

IS_IN_ANY_ROLE

- +

Is any role assigned to the user?

- -

true

-

false

+ +

true

+

false

IS_NOT_IN_ANY_GROUP

- +

Does the user belong to no group?

- -

true

-

false

+ +

true

+

false

IS_NOT_IN_ANY_ROLE

- +

Is the user associated with no roles?

- -

true

-

false

+ +

true

+

false

REQ

- +

Request details, as a map

- -

{

-

 "accessType":  "select",

-

 "clientIPAddress": "10.120.27.49",

-

 "clusterType": "etl",

-

 "clusterName": "etl-e1",

-

 "accessType":  "select",

-

 "user":        "scott",

-

 "userGroups":  [ "g1" ],

-

 "userRoles":   [ "r1" ],

-

}

+ +

{

+

 "accessType":  "select",

+

 "clientIPAddress": "10.120.27.49",

+

 "clusterType": "etl",

+

 "clusterName": "etl-e1",

+

 "accessType":  "select",

+

 "user":        "scott",

+

 "userGroups":  [ "g1" ],

+

 "userRoles":   [ "r1" ],

+

}

RES

- +

Resource details, as a map

- -

{

-

  "database":   "db1",

-

  "table":      "tbl1",

-

  "Column":     "col1",

-

  "_ownerUser": "jane"

-

}

+ +

{

+

  "database":   "db1",

+

  "table":      "tbl1",

+

  "Column":     "col1",

+

  "_ownerUser": "jane"

+

}

TAG

- +

Current tag, as a map.

This is available only in tag-based policies.

- -

{

-

 "_type": "SENSITIVE",

-

 "sensitiveLevel": 10

-

}

+ +

{

+

 "_type": "SENSITIVE",

+

 "sensitiveLevel": 10

+

}

TAGNAMES

- +

Names of tags associated with the resource, as a list

- -

[ "PII", "SENSITIVE" ]

+ +

[ "PII", "SENSITIVE" ]

TAGS

- +

All tags associated with the resource, as a map

- -

{

-

 "SENSITIVE": {

-

  "_type", "SENSITIVE",

-

  "level": 10

-

 },

-

 "PII": {

-

  "_type",   "PII",

-

  "piiType": "email"

-

 }

-

}

+ +

{

+

 "SENSITIVE": {

+

  "_type", "SENSITIVE",

+

  "level": 10

+

 },

+

 "PII": {

+

  "_type",   "PII",

+

  "piiType": "email"

+

 }

+

}

UGNAMES

- +

Names of groups the user belongs to, as a list

- -

[ "g1" ]

+ +

[ "g1" ]

URNAMES

- +

Names of roles the user is assigned to, as a list

- -

[ "r1" ]

+ +

[ "r1" ]

USER

- +

Name of the user

- -

"scott"

+ +

"scott"

 

+ +

+ Most functions listed in the table above take optional parameters, to make it easier to handle use cases that require special handling. +

+ +

 

+ +

Default value

+

+ A function call can include a default value as an optional parameter, which will be returned when there is no + value available. For example, consider the following expression: +

+ +

 

+ + +

USER.allowedSensitiveLevel >= TAG.sensitiveLevel

+

 

+ + +

+ When the user doesn’t have an attribute named allowedSensitiveLevel, the expression will always evaluate to + false since USER.allowedSensitiveLevel would evaluate to null. To handle such cases, consider the following + alternate expression which would use 0 as the value instead of null: +

+ +

 

+ + +

GET_USER_ATTR('allowedSensitiveLevel', 0) >= TAG.sensitiveLevel

+

 

+ + +

+ Here is another example of using default value in function calls: +

+ +

 

+ + +

dept_code in (${{GET_UG_ATTR('deptCode', -1)}})

+

 

+ + +

 

+ +

Separator

+

+ Functions that return a CSV string, like GET_TAG_NAMES(), can include following optional parameters: +

+ + +

 

+

optional #1. default value: value to return when no value is available

+

 

+

optional #2. separator: string to use as the separator between values

+

 

+ + +

 

+

+ Here is an example of using optional parameters: +

+ + +

 

+

GET_TAG_NAMES('', '|') == 'tag1|tag2|tag3'

+

 

+ + +

Quotes

+

+ Each function that returns a CSV string has another version with _Q appended to the function name; this version + surrounds each value within quotes. For example, consider the following row-filter expression: +

+ + +

 

+

location_state IN (${{GET_UG_ATTR_Q('state')}})

+

 

+ + +

 

+

+ The expression can evaluate to the following, if the user belongs to groups having an attribute named state: +

+ + +

 

+

location_state IN ('CA','OR','WA')

+

 

+ +