Skip to main content
Version: 2.12

Authentication

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

Ververica Platform supports integration with OpenID Connect (OIDC) and Security Assertion Markup Language (SAML) identity providers for authentication.

If your organization uses a different authorization system, such as Lightweight Directory Access Protocol (LDAP) or Active Directory, an OIDC bridge such as Dex may be used 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​

To enable the OIDC integration, 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 binding 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

info

Due to spring boot version upgrade, upgrading to Ververica Platform version 2.12.0 requires changing clientAuthenticationMethod from basic to client_secret_basic in the helm chart values.yaml file.

    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: client_secret_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.

Credentials​

The following credentials are required:

  • Server certificate from the identity provider, used by VVP to authenticate sign on asssertions received from the identity provider
  • User created key/certificate pair, used by VVP to sign logout assertions sent to the identity provider; the identity provider requires the certificate only to authenticate logout assertions from VVP

Configuration​

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

  • Single sign on URL: <your-vvp-installation>/login/saml2/sso/<registrationId>
  • Single logout URL: <your-vvp-installation>/login/saml2/slo/<registrationId>
  • An id to identify VVP: <your-vvp-installation>/saml2/service-provider-metadata/<registrationId>
  • Single logout credentials, the certificate only from a user created key/certificate pair the identity provider will use to authenticate assertions from VVP

The URI to replace <your-vvp-installation> with should look something like the following, for example: https://vvp-ui.my-company.com/login/saml2/sso/vvp-saml.

Here, registrationId can be chosen arbitrarily to identify the pair vvp service/identity provider. It must match the id set in the main VVP configuration file which defaults to vvp-saml unless overridden.

The identity provider requires a certificate so it can authenticate logout assertions from VVP. You should see a setting for Signature Certificate or similar. To provide this certificate, generate a key/certificate pair locally; your identity provider requires the certificate only, VVP will require both the private key and the certificate. See [How to generate a key pair](#How to generate a key pair) below for the steps to generate a key/certificate pair.

You will also need to download the identity provider's server certificate and provide it to VVP.

For the complete configuration, add the following lines to the main configuration file:

vvp:
  auth:
    enabled: true
    saml:
      groupsAttribute: groups  # The SAML assertion attribute containing a list of the user's groups
      registrationId: vvp-saml  # Must match the id set with your identity provider above, defaults to `vvp-saml`
      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  # Identity provider's single sign on service URL
      sloServiceLocation: https://my-saml-provider.com/some-application/abcdefg123/slo/saml  # Identity provider's single logout service URL
      certificateLocation: /vvp/secrets/saml-creds/certificate.crt  # optional, absolute path in gateway container to the identity provider certificate
      sloSigningKeyLocation: /vvp/secrets/saml-slo-signing-creds/key.pem  # optional, absolute path in gateway container to user supplied single logout private key
      sloSigningCertificateLocation: /vvp/secrets/saml-slo-signing-creds/certificate.crt  # optional, absolute path in gateway container to user supplied single logout certificate

  • The groupsAttribute key indicates the name of the attribute in the SAML assertion that contains a list of the user's groups, and defaults to groups. These groups can be referenced in role bindings by using the group: prefix. The list of groups can be provided as a comma-separated string or an 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 must match the id you set for VVP in your identity provider settings, defaults to vvp-saml if not specified.

  • Values for entityId, ssoServiceLocation, and sloServiceLocation should be retrieved from your identity provider and are specific to the VVP service.

  • certificateLocation is the absolute path inside the gateway container to the identity provider server certificate. Should be specified only if the certificate is injected into the gateway container at a location which is different from the default /vvp/secrets/saml-creds/certificate.crt.

  • sloSigningKeyLocation is the absolute path inside the gateway container to the single logout key location. If you use a name other than key.pem or path other than the default /vvp/secrets/saml-slo-signing-creds/key.pem be sure to specify it here.

  • sloSigningCertificateLocation is the absolute path inside the gateway container to the single logout certificate location. If you use a name other than certificate.crt or path other than the default /vvp/secrets/saml-slo-signing-creds/certificate.crt be sure to specify it here.

Configuring single sign on​

Single sign on requires an identify provider server certificate.

Provide the server certificate directly in the main configuration​

To configure directly in the main configuration file, paste the base64 encoded text as the value of the samlCredentials.certificate property:

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

In this case VVP will automatically create and mount a secret from the certificate text.

Provide the server certificate as a Kubernetes secret​

To avoid putting credentials into the configuration file in plaintext, an existing Kubernetes secret can also be used. In the main configuration file set samlCredentials.existingSecret to the name of the Kubernetes secret that contains your identify provider certificate under certificate.crt. VVP will mount it under the /vvp/secrets/saml-creds directory.

If you use a different certificate name then adapt vvp.auth.saml.certificateLocation accordingly.

If you do not already have a secret see `How to create a Kubernetes secret How to create a Kubernetes secret.

Provide the server certificate as a mounted volume​

To mount the server certificate as a volume add an appropriate volume to the main configuration file:

    volumes:
      - name: volume-name
    secret:
          secretName: <secret-name>
  
    volumeMounts:
      - name: volume-name
        mountPath: <saml-credentials-mount-path>, e.g. "/vvp/user/secrets/saml-sso-creds"

Be sure that vvp.auth.saml.certificateLocation points to the certificate file.

Note that this example creates the volume from the secret, but the volume can be of any type.

Configuring single logout​

Single logout requires credentials consisting of a private key and X509 certificate.

You can use an existing key/certificate pair that identifies you or generate a new key pair, see How to generate a key pair below.

Providing single logout credentials as a Kubernetes secret​

You can use an existing secret, or create a new secret from a key pair, see How to create a Kubernetes secret.

In the main configuration file set the following root property with the name of the Kubernetes secret that contains your private key (under the key.pem key) and your certificate (under the certificate.crt key):

    samlCredentials:
      sloSigning:
        existingSecret: <secret-name>  # The name of your Kuberbetes secret

The secret will be mounted in the gateway container under the directory default path /vvp/secrets/saml-slo-signing-creds/.

If you use different key/certificate keys then adapt vvp.auth.saml.sloSigningKeyLocation and/or vvp.auth.saml.sloSigningCertificateLocation accordingly.

Providing single logout credentials as a mounted volume​

To mount the single logout key/certificate pair as a volume add an appropriate volume to the main configuration file:

    volumes:
      - name: saml-signing-credentials
    secret:
          secretName: <saml-slo-signing-credentials-secret>
  
    volumeMounts:
      - name: saml-signing-credentials
        mountPath: <saml-slo-signing-credentials-mount-path>, e.g. "/vvp/user/secrets/saml-slo-signing-creds"

Be sure that vvp.auth.saml.sloSigningKeyLocation points to the key file and vvp.auth.saml.sloSigningCertificateLocation points to the certificate file.

Note that this example creates the volume from the secret, but the volume can be of any type.

How to create a Kubernetes secret​

If you don't have a secret already, you can create one by preparing a configuration file following the example below, and paste in the contents of the file(s) as base64 encoded text:

    # 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>
      # Omit key.pem to encode a certificate only
      key.pem: <base64 encoded key>

Run kubectl apply -f samlCredentials.yaml to generate the secret.

To base64 encode an existing file or string run base64 -w 0 <file> for a file and echo -n <string> | base64 -w 0 for a string, where -w 0 disables line wrapping to avoid line break issues in the yaml. Use the output as the base64 encoded text.

How to generate a key pair​

The certificate must be in X509 format. To generate a new key pair, this command works on any platform with openssl installed, or use an appropriate command for the platform you are using:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.crt