Authentication¶

Note

This feature is only available in Ververica Platform Stream Edition and above.

Authentication is the process of verifying who an entity (such as a user) is. In order to enable authentication for Ververica Platform you have to integrate with an external identity provider. Ververica Platform does not actively manage user records (such as names or passwords).

The following identity providers are supported:

OpenID Connect (OIDC)
- Configuration
- Secure clientSecret with Kubernetes Secrets
Security Assertion Markup Language (SAML)
- Configuration
- Credentials

If your organization uses a different authorization system, such as Lightweight Directory Access Protocol (LDAP) or Active Directory you may use an OIDC bridge such as Dex to connect the systems.

OpenID Connect (OIDC)¶

Ververica Platform supports integration with OpenID Connect (OIDC) identity providers for authentication. OIDC is an authentication protocol that is based on the OAuth 2.0 family of specifications.

Configuration ¶

In order to enable the OIDC integration, you have to configure it in the main configuration file under the vvp.auth.oidc key by providing a registration and provider specification.

The groupsClaim key indicates the OIDC ID token claim that contains a list of the user’s groups. These groups can be referenced in Role Bindings by using the group: prefix. For example, if the ID token for an authenticated user contains the claim groups: ["vvp-editors"], and you configure vvp.auth.oidc.groupsClaim=groups, a role binding assigning the role editor to group:vvp-editors will match this user.

Note that currently this claim must be present in the ID token returned by the OIDC provider. Claims in the access token are not supported because access tokens have no standardized structure and parsing them is implementation-specific.

Example: OIDC configuration template

vvp:
  auth:
    enabled: true
    admins:
    - user:foo@bar.com
    oidc:
      groupsClaim: roles  # The OIDC ID token claim containing a list of the user's groups
      registrationId: my-oidc-provider
      registration:
        clientId: vvp
        clientSecret: secret
        redirectUri: "{baseUrl}/{action}/oauth2/code/{registrationId}"
        clientAuthenticationMethod: basic
        authorizationGrantType: authorization_code
        scope:
        - openid
      provider:
        authorizationUri: http://my-oidc-provider.internal/openid-connect/auth
        tokenUri: http://my-oidc-provider.internal/openid-connect/token
        userInfoUri: http://my-oidc-provider.internal/openid-connect/userinfo
        jwkSetUri: http://my-oidc-provider.internal/openid-connect/certs
        userNameAttribute: email  # Required to correctly identify users
      endSessionEndpoint: http://my-oidc-provider.internal/openid-connect/logout

registration and provider expose Spring Security objects; more information about configuring these objects can be found in the Spring Boot documentation.

Please consult the Configuration section for more specific examples.

Secure `clientSecret` with Kubernetes Secrets ¶

In a production environment, you may want to secure clientSecret with Kubernetes Secrets. To do so, you first remove it from the configuration above, then create a yaml file containing:

# file: env_secret.yaml
env:
# OIDC authentication:
- name: vvp.auth.oidc.registration.clientSecret
  valueFrom:
    secretKeyRef:
      name: mysecrets  # the name of the Kubernetes Secret
      key: oidc        # the key

Then you can install Ververica Platform with this additional values file:

$ helm install ... --values env_secret.yaml

Use helm upgrade if you are upgrading/modifying an existing installation.

Security Assertion Markup Language (SAML)¶

Ververica Platform supports integration with Security Assertion Markup Language (SAML) identity providers for authentication. SAML is an XML-based markup language for security assertions.

Configuration ¶

To enable SAML, first register your VVP application at your identity provider, setting the following values:

Single sign on URL: your-vvp-installation/login/saml2/sso/<registrationId>
Service provider entity id: your-vvp-installation/saml2/service-provider-metadata/<registrationId>

Here, registrationId can be chosen arbitrarily and identifies the pair of service provider and identity provider. It has to match the one set in the Ververica Platform configuration (see below), which will default to vvp-saml unless overridden.

Next, update the main configuration file by adding the following lines:

vvp:
  auth:
    enabled: true

    saml:
      groupsAttribute: groups  # The SAML assertion attribute containing a list of the user's groups
      registrationId: vvp-saml  # Your chosen identifier for the <service provider> - <identity provider> pair
      entityId: http://www.my-saml-provider.com/abcdefg123  # entity id of the identity provider
      ssoServiceLocation: https://my-saml-provider.com/some-application/abcdefg123/sso/saml  # service location of the identity provider
      certificateLocation: /vvp/secrets/saml-creds/cert.crt  # absolute path to the certificate in the gateway container

The groupsAttribute key indicates the name of the attribute in the SAML assertion that contains a list of the user’s groups, and will default to groups. These groups can be referenced in Role Bindings by using the group: prefix. The list of groups can be provided as comma-separated string or array of strings. For example, assume that the assertion for an authenticated user contains the attribute groups: "vvp-editors,vvp-viewers". If a role binding assigning the role editor to group:vvp-editors was created in Ververica Platform, then the user would receive the editor role. registrationId has to coincide with the one set at the identity provider. It will default to vvp-saml if it is not specified. Both entityId and ssoServiceLocation have to be retrieved from the identity provider; the latter is specific to the application registered there. certificateLocation is the absolute path inside the gateway container to the certificate, which can also be retrieved from the identity provider. It only needs to be specified if the certificate is injected into the gateway container at a location which is different from the default /vvp/secrets/saml-creds/cert.crt (see below).

Credentials ¶

The necessary certificate file can be provided in several ways.

Injecting the certificate into the container ¶

In case you have existing infrastructure to inject credentials files into containers, the certificate can be injected into the gateway container of your Ververica Platform deployment, and the path can be referenced as shown in the configuration example above.

Providing the certificate directly in the configuration file ¶

The certificate can also be provided directly in the main configuration file. To do so, add the following lines to your values.yaml:

samlCredentials:
  certificate: |-
    -----BEGIN CERTIFICATE-----
    <...>
    -----END CERTIFICATE-----

Using an existing Kubernetes secret ¶

In order to avoid putting the certificate into the configuration file in plaintext, an existing Kubernetes secret containing it can also be used. To do so, reference the secret by name by setting samlCredentials.existingSecret: secret-name. The secret should contain the keys certificate.crt, with the certificate as the value (if the key is named differently, certificateLocation has to be adapted accordingly). This secret will automatically be mounted in the gateway container at /vvp/secrets/saml-creds/. If you don’t have a secret already, you can create one by preparing a file like:

# file: samlCredentials.yaml
apiVersion: v1
kind: Secret
metadata:
  name: secret-name
  labels:
    chart: "ververica-platform-x.y.z"
    component: ververica-platform
    heritage: "Helm"
    release: "ververica-platform"
    system: ververica-platform
type: Opaque
data:
  certificate.crt: <base64 encoded certificate>

The secret can then be created by running kubectl apply -f samlCredentials.yaml. Note that values in secrets have to be base64 encoded by default! You can base64 encode an existing file or string by running base64 -w 0 <file> for a file and echo -n <string> | base64 -w 0 for a string (note that line wrapping is disabled to avoid line break issues in the yaml).