Skip to main content
Version: 3.1

Authentication

Authentication is the process of verifying who an entity (such as a user) is. Ververica Platform does not manage user credentials directly; it delegates authentication to an external identity provider using OpenID Connect (OIDC) or Security Assertion Markup Language (SAML).

note

For base OIDC and SAML setup — including how to enable SSO and configure an initial admin user — see Configure Single Sign-On in the installation guide.

Group Claim Configuration​

Ververica Platform 3.1.1 restores support for extracting group memberships from the identity provider token or assertion. Once configured, these groups can be used for role assignments, letting administrators manage access through identity provider groups rather than individual user entries.

OIDC​

Add groupsClaim to your OIDC configuration. The value must match the name of the ID token claim that contains the user's group memberships.

global:
  authentication:
    oidc:
      enabled: true
      clientId: {your-client-id}
      clientSecret: {your-client-secret}
      discoveryUri: {your-discovery-uri}
      groupsClaim: groups

The claim value must be an array of strings or a comma-separated string. For example, an ID token containing:

{
  "sub": "user@example.com",
  "email": "user@example.com",
  "groups": ["platform-editors", "data-team"]
}

exposes the groups platform-editors and data-team for use in role assignments.

note

The claim must be present in the ID token. Claims in the access token are not supported, because access tokens have no standardized claim structure.

Provider Examples​

Azure Entra ID

Azure Entra ID can include a groups claim containing object IDs of the user's security groups. To use human-readable names instead, configure app roles in the Azure application registration and assign users or groups to those roles. App roles are emitted in the roles claim:

groupsClaim: roles

See Known Limitations for important caveats about Azure AD token size.

AWS Cognito

Cognito includes group memberships in the cognito:groups claim:

groupsClaim: "cognito:groups"

Ensure the Cognito user pool groups are populated and that the ID token is requested with the appropriate scopes.

Dex and Google Workspace

When using Dex as an OIDC bridge with Google Workspace group sync configured, Dex emits group memberships under the groups claim:

groupsClaim: groups

Generic OIDC

Set groupsClaim to the name of the claim your provider includes in the ID token. Consult your identity provider's documentation to identify the correct claim name, and inspect an issued ID token to confirm the value format.

SAML​

Add groups-attribute nested under identity-provider in your SAML configuration. The value must match the name of the SAML assertion attribute that contains the user's group memberships.

global:
  authentication:
    saml:
      enabled: true
      identity-provider:
        groups-attribute: groups
        metadata: |
          <?xml version="1.0" encoding="UTF-8"?>
          <md:EntityDescriptor ...>
            ...
          </md:EntityDescriptor>
      service-provider:
        entity-id: {your-service-provider-entity-id}
      keystore:
        certificate: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
        private-key: |
          -----BEGIN PRIVATE KEY-----
          ...
          -----END PRIVATE KEY-----

The attribute value must be an array of strings or a comma-separated string. For example, an assertion containing:

<saml:Attribute Name="groups">
  <saml:AttributeValue>platform-editors</saml:AttributeValue>
  <saml:AttributeValue>data-team</saml:AttributeValue>
</saml:Attribute>

exposes the groups platform-editors and data-team for use in role assignments.

Known Limitations​

Groups Must Be Present in the ID Token​

For OIDC, groups must be present in the ID token. If your identity provider places group information only in the access token, configure it to also include the groups claim in the ID token.

Azure AD Token Size Limits​

Azure Active Directory imposes a size limit on JWT tokens. When a user belongs to many groups, Azure AD replaces the groups claim with an overage indicator and removes the individual group entries. In that case, group-based role assignments stop working because the token no longer contains the user's groups.

Workaround for JWT tokens: Use Azure AD app roles instead of security groups. App roles are not subject to the same size limits. Assign the relevant app roles to users or groups in Azure, then set groupsClaim: roles in your Ververica Platform configuration. The roles claim carries app role assignments and does not trigger the overage mechanism.

Workaround for SAML tokens: Configure attribute-level group filtering in the Azure AD enterprise application to limit the assertion to only the groups Ververica Platform needs. This reduces assertion size and avoids the overage threshold.

On this page