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

Open CONFIG_ENTITY_PERMISSIONS, click Show Editor to view and modify the JSON configuration.
Make your changes in the editor and click Save.
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>.

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)

Usage

Notes

Contents

Entity permission configuration

Example: Entity permission configuration

Grantee configuration

Example: Grantee configuration

Grantee type configuration

Example: Grantee type configuration

Default grant configuration

Example: Default grant configuration

Row-level policy configuration

Example: Row-level policy configuration

Row-level policy attribute configuration

Example: Row-level policy attribute configuration

Examples

Using the environment_name variable