Skip to main content
Skip table of contents

CONFIG_ENTITY_PERMISSIONS

CONFIG_ENTITY_PERMISSIONS is a configuration package used to define and manage access control settings for entities in Agile Data Engine:

  • Entity permissions – Grantable privileges such as SELECT, UPDATE, INSERT, and DELETE.

  • Grantees – Specific objects that can receive permissions, such as user roles or groups.

  • Grantee types – Types of grantees, such as ROLE or SHARE.

  • Default grants – Default permission and grantee assignments defined per entity type.

  • Row-level policies – Definitions of row-level security rules that restrict data access based on conditions.

  • Row-level policy attributes – Mapping of row-level policies to specific entity attributes to enforce access control at the data level.

These configurations help ensure secure and consistent permission management when deploying entities across environments.

Note that the available permissions, grantee types, and supported features may vary depending on the target database product.


See also:


Usage

  1. Open CONFIG_ENTITY_PERMISSIONS, click Show Editor to view and modify the JSON configuration.

  2. Make your changes in the editor and click Save.

  3. Set permissions for individual entities by navigating to the Permissions tab within the entity's configuration in Designer. See Permissions for more details.

After making changes, the CONFIG_ENTITY_PERMISSIONS package will have uncommitted changes. To maintain a proper change history, it is recommended to commit the package. You must also deploy the corresponding entity packages to Runtime environments for the changes to take effect.


Notes

Variables have to be referenced in grantee names with ${variable_name} which differs from the standard notation <variable_name>.


Contents

Entity permission configuration

Entity permission configurations are managed within the JSON array block named entityPermissions.

Key

Value type

Example

Description

permission

String

SELECT

Specifies the name of the permission as recognized by the target database.
This should match the exact privilege name used in the target database.

description

String

Allows grantee to run a SELECT statement on the entity.

Description for the permission.

Example: Entity permission configuration

JSON
"entityPermissions": [
  ...
  {
    "permission": "SELECT",
    "description": "Allows grantee to run a SELECT statement on the entity."
  }
  ...
]

Grantee configuration

Grantee configurations are managed within the JSON array block named grantees.

Key

Value type

Example

Description

granteeId

Integer

2

Unique identifier for the grantee.

granteeName

String

READ_ONLY

Grantee name. This corresponds to the name of a database object to which permissions will be granted. This should match the name used in the target database system.

superGranteeId

Integer

null

Optional: Parent granteeId.

granteeType

String

ROLE

Specifies what kind of object the grantee is, such as a ROLE or SHARE, depending on the target database. This determines how permissions are applied during deployment.

It is also possible to reference predefined variables or environment variables defined in the CONFIG_ENVIRONMENT_VARIABLES configuration package by using the ${variable} syntax in the grantee name field. This allows dynamic assignment of grantee names based on the deployment environment.

Example: Grantee configuration

JSON
"grantees": [
  ...
  {
    "granteeId": 2,
    "granteeName": "READ_ONLY",
    "superGranteeId": null
  },
  {
    "granteeId": 3,
    "granteeName": "${EXEC_ROLE}",
    "superGranteeId": null
  }
  ...
]

Grantee type configuration

Grantee type configurations are managed within the JSON array block named granteeTypes.

Key

Value type

Example

Description

granteeType

String

ROLE

Type of the grantee. This must match the object type as defined in the target database, such as ROLE, USER, SHARE, group, serviceAccount or principalSet.

description

String

For granting permissions to roles.

Optional: Description for the grantee type.

Example: Grantee type configuration

JSON
"granteeTypes": [
  ...
  {
    "granteeType": "USER",
    "description": "For granting permissions to users."
  },
  {
    "granteeType": "ROLE",
    "description": "For granting permissions to roles."
  },
  {
    "granteeType": "SHARE",
    "description": "For granting permissions to shares."
  }
  ...
]

If an existing grantee type needs to be deleted, you must also remove or update any grantees that are currently assigned to that grantee type.

Note that grantee types for Google BigQuery are case-sensitive. The default grantee type USER should be set in lowercase, as required by the Google BigQuery user list.


Default grant configuration

Default grant configurations are managed inside the JSON array block named, defaultGrants.

Key

Value type

Example

Description

defaultGrantId

Integer

1

Unique identifier for the default grant.

entityType

String

GENERIC

Entity type name as defined in CONFIG_ENTITY_DEFAULTS.

permission

String

SELECT

Reference to the permission name defined in the entityPermissions configuration block.

granteeId

Integer

2

Reference to the grantee id defined in the grantees configuration block.

withGrantOption

Boolean

false

Specifies whether the grant option is enabled. When enabled, the grantee is allowed to further grant the permission to other grantees.

Example: Default grant configuration

JSON
"defaultGrants": [
  ...
  {
    "entityType": "GENERIC",
    "permission": "SELECT",
    "granteeId": 2,
    "withGrantOption": false,
    "defaultGrantId": 1
  },
  ...
]

Row-level policy configuration

Row-level policy configurations are managed within the JSON array block named rowLevelPolicies.

Key

Value type

Example

Description

rowLevelPolicyId

String

4ab86cae-614c-47b7-f770e6e0bda4

Unique identifier for the row level policy. Can be generated with online tools, such as UUID Generator.

label

String

access based on sales unit

The display name of the policy as it appears in the user interface. This name is intended to be user-friendly and descriptive for easier identification.

preDefinedPolicyFunctionName

String

security.validateAccessPerSalesUnit

Specifies the name of a predefined policy function in the target database that will be used to enforce the row-level security policy.

This field is required for most supported DBMSs, except Google BigQuery, where it is not needed.

nameSuffix

String

allowed_sales_unit

In Google BigQuery and Azure-based DBMSs, the policy name is constructed using the format: <schema>_<entity_name>_<nameSuffix>

requiresDefinedGrantees

Boolean

false

Indicates whether the policy requires the ADE developer to explicitly define the roles (grantees) that the policy applies to.

This must be set to true for policies in Amazon Redshift and Google BigQuery, where explicit role assignment is mandatory.

For other supported platforms, this can be set to false.

deleted

Boolean

false

Indicates whether the policy has been marked as removed from the system.

  • true – The policy is considered deleted and will not be applied during deployment.

  • false – The policy is active and included in the deployment process.

This flag is used for soft deletion, allowing policies to be deactivated without permanently removing them from the configuration history.

ruleExpression

String

sales_unit = ‘ACCESSORIES’

Defines the actual row-level access policy rule used in Google BigQuery.
The rule expression specifies the condition under which a row is accessible to a grantee. It is evaluated at query time to enforce row-level security.

description

String

Allow access to only specific sales units

Optional: Description for the row-level policy.

Example: Row-level policy configuration

JSON
"rowLevelPolicies": [
  ...
  {
    "rowLevelPolicyId": "4ab86cae-614d-47b7-8bb3-f770e6e0bda4",
    "label": "Sales info only if allowed",
    "preDefinedPolicyFunctionName": "manager_test.limited_sales_regions",
    "nameSuffix": "allowed_role",
    "requiresDefinedGrantees": true,
    "deleted": false,
    "ruleExpression": "sales_region = 'APAC'",
    "description": "Information only to allowed roles"
  }
  ...
]

If an existing row-level policy needs to be deleted, you must also remove or update any row-level policy attributes currently associated with that policy. Keep in mind that changes to row-level policies only take effect after the packages containing the affected entities are deployed to the Runtime environment.


Row-level policy attribute configuration

Row-level policy attribute configurations are managed within the JSON array block named rowLevelPolicyAttributes.

Key

Value type

Example

Description

rowLevelPolicyAttributeId

String

9b855c37-ecee-4e97-93a5-ex0e7705d73a

Unique identifier for the row-level policy attribute. Can be generated with online tools, such as UUID Generator.

rowLevelPolicyId

String

4ab86cae-614c-47b7-f770e6e0bda4

Reference to the row-level policy id defined in the rowLevelPolicies configuration block.

attributeName

String

sales_unit

Attribute name used in the policy.

position

Integer

1

Position of the attribute in the policy function/procedure.

dataType

String

VARCHAR

Logical datatype of the attribute.

dataPrecision

Integer

6

Optional: Defines the data type precision for the row-level policy attribute.

It is recommended to specify this value for decimal attributes in Amazon Redshift.

dataScale

Integer

2

Optional: Defines the data type scale for the row-level policy attribute.

It is recommended to specify this value for decimal attributes in Amazon Redshift.

dataLength

Integer

200

Optional: Defines the data type length for the row-level policy attribute.

It is recommended to specify this value for VARCHAR attributes in Amazon Redshift.

Example: Row-level policy attribute configuration

JSON
"rowLevelPolicyAttributes": [
  ...
  {
    "rowLevelPolicyAttributeId": "9b855c37-ecee-4e97-93a5-ec0e7705d73a",
    "rowLevelPolicyId": "29862c45-d36b-4da4-bb07-461892dca8f6",
    "attributeName": "sales_unit",
    "position": 1,
    "datatype": "VARCHAR"
  }
  ...
]

If an existing row-level policy attribute needs to be deleted, remember that changes to the row-level policies will only take effect after deploying the packages that contain the affected entities to the Runtime environment.

Good to know about applying row-level policies

Before a row-level policy can be attached to an entity, the entity must already contain the attributes defined in the policy configuration.

The following conditions must be met:

  • Attribute names must match exactly between the entity and the policy definition.

  • Attribute data types must match to ensure compatibility.

  • If data length, data scale, or data precision have been defined for the policy attributes, they must also match the corresponding entity attribute settings.

    • Amazon Redshift enforces strict datatype matching when attaching policies. Therefore, it is recommended to explicitly define and align precision, scale, and length for attributes used in policies.


Examples

Using the environment_name variable

Agile Data Engine provides predefined variables that can be used with CONFIG_ENTITY_PERMISSIONS.

In this example, environment_name is used as part of grantee name to use environment specific roles:

JSON
 ...
 "grantees": [
    ... ,
    {
      "granteeId": 1,
      "granteeName": "${environment_name}_ANALYST",
      "granteeType": "ROLE"
    },
    {
      "granteeId": 2,
      "granteeName": "${environment_name}_DEVELOPER",
      "granteeType": "ROLE"
    },
    ...
  ]
  ...

Note that any environment variable used in grantee name value is substituted and transformed to uppercase.

Any '-' and '.' are replaced with '_' (except for BigQuery).

For example:

Environment name:

Runtime.1_for-test

Grantee name:

${environment_name}-BI-Developer

Transformed result:

RUNTIME_1_FOR_TEST_BI_Developer.

(for BigQuery > RUNTIME.1_FOR-TEST-BI-Developer)

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.