CREATE ROLE MAPPING

CREATE ROLE MAPPING creates role mapping rules for an authentication integration. After a user authenticates through the integration, VeloDB Enterprise evaluates each RULE clause and grants the current session the combined roles from all matching rules.

Note:

Supported since VeloDB Enterprise 4.1.4.

Syntax

CREATE ROLE MAPPING [IF NOT EXISTS] <mapping_name>
ON AUTHENTICATION INTEGRATION <integration_name>
RULE (
    USING CEL '<condition>'
    GRANT ROLE <role_name> [, <role_name> ...]
)
[, RULE (
    USING CEL '<condition>'
    GRANT ROLE <role_name> [, <role_name> ...]
) ...]
[COMMENT '<comment>'];

Required parameters

Parameter	Description
<mapping_name>	Role mapping name.
<integration_name>	Authentication integration associated with the mapping.
RULE (...)	One or more rules. Each rule contains a Common Expression Language (CEL) condition and at least one VeloDB Enterprise role to grant.
USING CEL '<condition>'	CEL Boolean expression evaluated during authentication.
GRANT ROLE <role_name> [, <role_name> ...]	One or more roles to grant when the rule matches.

Optional parameters

Parameter	Description
IF NOT EXISTS	Suppresses the error if a mapping with the same name already exists.
COMMENT '<comment>'	Role mapping comment.

CEL helper functions

Function	Description
name()	Returns the authenticated login name.
external_principal()	Returns the external principal identifier.
is_service_principal()	Returns whether the current principal is a service principal.
has_group("<group>")	Checks whether the external groups contain the specified value.
has_role("<role>")	Checks whether the multivalued roles attribute contains the specified value.
has_scope("<scope>")	Checks whether the multivalued scope or scp attribute contains the specified value.
attr("<key>")	Returns a single-valued attribute, or an empty string if the attribute does not exist.
has_attr_value("<key>", "<value>")	Checks whether the attribute contains the specified value.
has_any_group("<g1>", "<g2>", ...)	Checks whether any of the specified groups match.
has_any_role("<r1>", "<r2>", ...)	Checks whether any of the specified role values match.
has_any_scope("<s1>", "<s2>", ...)	Checks whether any of the specified scopes match.
has_any_attr_value("<key>", "<v1>", "<v2>", ...)	Checks whether the attribute contains any of the specified values.

These are CEL helper names, not SQL functions. Use their case exactly as shown.

Access control requirements

The user executing this statement must have the following privilege, either directly or through a role:

Privilege	Object	Description
ADMIN_PRIV	User or role	Required to perform this operation.

Usage notes

• The integration must exist, and its plugin must provide groups, scopes, or other principal attributes.
• Each integration can have at most one role mapping.
• Every condition must be nonempty and compile to a CEL Boolean expression.
• Roles in GRANT ROLE must exist before you create the mapping.
• When multiple rules match, the session receives the combined roles from those rules.
• For OIDC, oidc.groups_claim specifies the field read by has_group(...). oidc.extra_claims specifies additional fields available to attr(...).

Examples

Create a mapping with multiple rules:

CREATE ROLE analyst;
CREATE ROLE finance_reader;
CREATE ROLE dashboard_readonly;

CREATE ROLE MAPPING corp_oidc_roles
ON AUTHENTICATION INTEGRATION corp_oidc
RULE (
    USING CEL 'has_group("analyst")'
    GRANT ROLE analyst
),
RULE (
    USING CEL 'attr("department") == "finance"'
    GRANT ROLE finance_reader
),
RULE (
    USING CEL 'has_scope("session:role:reader")'
    GRANT ROLE dashboard_readonly
)
COMMENT 'Role mapping for corporate OIDC users';

For the department rule, include department in the integration's oidc.extra_claims configuration. Grant the required object privileges to the roles separately.

Grant multiple roles with one rule:

CREATE ROLE platform_admin;
CREATE ROLE audit_reader;

CREATE ROLE MAPPING corp_oidc_admin_roles
ON AUTHENTICATION INTEGRATION corp_oidc
RULE (
    USING CEL 'has_group("platform-admin")'
    GRANT ROLE platform_admin, audit_reader
);

The two examples are alternatives. Because corp_oidc can have only one mapping, drop the first mapping before trying the second.