Authorization

Authorization is the process of verifying that an authenticated entity has access to a resource and can perform a desired action. Ververica Platform uses a role-based access control model where roles are assigned to individual users or identity provider groups.

Roles

The following roles are available:

Role Assignments

Roles are configured in the initialAccessFileContent block of your Helm values. Each entry in the initialAccess array grants a role to a principal (a user or a group) at a given scope.

Individual User Assignments

Use userId to assign a role to a specific user. The userId must match the identifier your identity provider sends — the email address for OIDC, or the NameId for SAML.

1global:
2  initialAccessFileContent:
3    initialAccess:
4      - userId: alice@example.com
5        workspaceId: defaultworkspace
6        namespaceId: default
7        role: EDITOR

Group-Based Role Assignments

Use userId with a group: prefix to assign a role to all members of an identity provider group. The group name must exactly match a group value extracted from the ID token or SAML assertion, as configured by groupsClaim or groups-attribute in Authentication.

1global:
2  initialAccessFileContent:
3    initialAccess:
4      - userId: "group:platform-admins"
5        workspaceId: defaultworkspace
6        role: ADMIN
7      - userId: "group:platform-editors"
8        workspaceId: defaultworkspace
9        namespaceId: default
10        role: EDITOR
11      - userId: "group:data-team"
12        workspaceId: defaultworkspace
13        namespaceId: analytics
14        role: VIEWER

Omit namespaceId to scope the assignment to the workspace level. Include it to scope the assignment to a specific namespace.

Access Resolution

When a user authenticates, Ververica Platform evaluates all role assignments that apply to that user:

• Direct assignments where userId matches the authenticated user.
• Group assignments where a group:-prefixed userId matches any group present in the user's token or assertion.

The effective permissions are the union of all matching role assignments. If a user belongs to one group with Viewer access and another group with Editor access in the same namespace, that user receives Editor permissions.

User-level and group-level assignments combine in the same way. A direct userId assignment and one or more group:-prefixed userId assignments can all apply to the same user simultaneously, and the most permissive combination takes effect.

Troubleshooting

Group Claim Not Found in Token

If no groups are being recognized, confirm that groupsClaim (OIDC) or groupsAttribute (SAML) is set in your authentication configuration and matches the exact claim or attribute name your identity provider uses, including case.

For OIDC, some providers require explicit configuration to include group memberships in the ID token:

• Add the groups scope (or equivalent) to the OAuth scopes in your Ververica Platform configuration.
• In your identity provider, enable group claims for the application registration.

For SAML, ensure your identity provider is configured to release the group attribute in assertions for the Ververica Platform service provider.

User Receives No Permissions Despite Group Membership

1. Inspect the ID token or SAML assertion to verify the group values are present and match the expected format. For OIDC, decode the ID token at jwt.io to see the raw claims.
2. Confirm that the group name in the userId value (after the group: prefix) in initialAccessFileContent exactly matches the group name in the token, including case and any special characters.
3. For Azure Entra ID, check whether token size limits are causing groups to be omitted from the token. See Azure AD Token Size Limits.

Debugging OIDC and SAML Group Mappings

To diagnose group mapping issues, inspect the raw token or assertion during the authentication flow:

• For OIDC: decode the ID token returned by your identity provider and look for the claim named in groupsClaim. Confirm both the claim name and the group name values.
• For SAML: capture the SAML assertion (most browser developer tools or browser extensions can do this) and inspect the attribute named in groupsAttribute.

Once you confirm the exact group names in the token, compare them against the group:-prefixed userId values in your initialAccessFileContent.

Examples

OIDC Group Mapping

Identity provider ID token:

1{
2  "email": "alice@example.com",
3  "groups": ["platform-admins", "data-team"]
4}

Authentication configuration:

1global:
2  authentication:
3    oidc:
4      enabled: true
5      clientId: my-client
6      clientSecret: my-secret
7      discoveryUri: https://idp.example.com/.well-known/openid-configuration
8      groupsClaim: groups

Role assignments:

1global:
2  initialAccessFileContent:
3    initialAccess:
4      - userId: "group:platform-admins"
5        workspaceId: defaultworkspace
6        role: ADMIN
7      - userId: "group:data-team"
8        workspaceId: defaultworkspace
9        namespaceId: default
10        role: EDITOR

A user who belongs to platform-admins receives Admin access at workspace level. A user who belongs to both groups receives Admin at workspace level and Editor in the default namespace simultaneously.

SAML Group Mapping

Identity provider assertion:

1<saml:Attribute Name="memberOf">
2  <saml:AttributeValue>platform-editors</saml:AttributeValue>
3</saml:Attribute>

Authentication configuration:

1global:
2  authentication:
3    saml:
4      enabled: true
5      identity-provider:
6        groups-attribute: memberOf

Role assignment:

1global:
2  initialAccessFileContent:
3    initialAccess:
4      - userId: "group:platform-editors"
5        workspaceId: defaultworkspace
6        namespaceId: default
7        role: EDITOR

Multiple Groups, Multiple Roles

A user belongs to three groups: platform-owners, analytics-viewers, and global-admins.

1global:
2  initialAccessFileContent:
3    initialAccess:
4      - userId: "group:platform-owners"
5        workspaceId: defaultworkspace
6        namespaceId: production
7        role: OWNER
8      - userId: "group:analytics-viewers"
9        workspaceId: defaultworkspace
10        namespaceId: analytics
11        role: VIEWER
12      - userId: "group:global-admins"
13        workspaceId: defaultworkspace
14        role: ADMIN

The user receives Owner in the production namespace, Viewer in the analytics namespace, and Admin at workspace level. All three assignments apply simultaneously.