How to enable SAML-based Single Sign-on in Ververica Platform with Active Directory Federation Services

Answer

Today, the Ververica platform (VVP) offers two methods of authenticating users via external Identity providers. Security Assertion Markup Language (SAML) and OpenID Connect (OIDC). 

This guide offers an example of how to easily bind existing AD users and groups with those managed within the Ververica Platform using SAML w/ Active Directory Federation Services (AD FS) and VVP as a Relying Party Trust (RPT).

Creating a secure ingress endpoint for VVP

AD FS requires an encrypted connection (i.e. HTTPS) for traffic to the relying party. Common methods to configure this in-front of VVP include using Istio Ingress Gateways, Load balancers, and Kubernetes gateway GRPC and HTTP routes set with TLS mode set to terminate.

Enable SAML & Auth in Ververica Platform

Let’s begin by making some simple edits to our helm values.yaml file that was used previously to deploy the platform. We’ll use the below configuration example to get started; replacing `my-adfs-server` with the resolvable hostname of our Windows server.

## Authentication configuration.
auth:
enabled: true
saml:
groupsAttribute: groups
registrationId: vvp-saml
entityId: http://<my-adfs-server>/adfs/services/trust
ssoServiceLocation: https://<my-adfs-server>/adfs/ls/
sloServiceLocation: https://<my-adfs-server>/adfs/ls/

## A list of users and groups that have administrator privileges.
## - `user:user@example.com` matches the user `user@example.com`

##
## SAML credentials
##
samlCredentials:
  ## Use an existing Kubernetes secret instead of providing credentials in this file. The keys
  ## within the secret must be named as shown below.
  ##
  existingSecret: secret-saml-sso

  sloSigning:
    ## Use an existing Kubernetes secret instead of providing credentials in this file. The keys
    ## within the secret must be named as shown below.
    ##
    existingSecret: secret-saml-slo

Note that we added a Single Logout (sloSigning) certificate and signing Key under the “samlCredentials” section with the values.yaml as the name of a Kubernetes secret that we will create. 

You can also choose to have the certificate and signing key as files within a mounted K8s volume, or embedded as text within your values.yaml. See our platform-operations/access-control documentation, for our supported credential options with examples.

Next we’ll need to store the certificates and signing-key for sso and slo as k8s secrets. First base64 encode the contents of each before copying them into the below k8s resource files.

Example secret for sso (Single Logon) (i.e. saml-sso-secret.yaml)

apiVersion: v1
kind: Secret
metadata:
  name: secret-saml-sso
  labels:
    chart: "ververica-platform-test"
    component: ververica-platform
    heritage: "Helm"
    release: "ververica-platform"
    system: ververica-platform
type: Opaque
data:
  certificate.crt: <base64 encoded>

Example secret for slo (SingleLogOut) yaml (i.e. saml-slo-secret.yaml)

apiVersion: v1
kind: Secret
metadata:
  name: secret-saml-slo
  labels:
    chart: "ververica-platform-test"
    component: ververica-platform
    heritage: "Helm"
    release: "ververica-platform"
    system: ververica-platform
type: Opaque
data:
  Key.pem: <base64 encoded>   

  certificate.crt: <base64 encoded>

Deploy both secrets in the VVP K8s namespace.

kubectl apply -f saml-sso-secret.yaml -n vvp
kubectl apply -f saml-slo-secret.yaml -n vvp

And now re-deploy the platform with the latest configuration.

helm upgrade --install vvp ververica/ververica-platform --namespace vvp --values values.yaml

We need to add VVP as a Relying Party Trust (RPT).  Make sure to select “Claims aware” in the first page of the wizard and click “Next”

The default SAML metadata endpoint is: https://<your-vvp-instance>/saml2/service-provider-metadata/vvp-saml. You can download the SAML metadata from VVP by simply opening this url within a browser.

In the next screen, select “Import data about the Relying Party from a file” and browse to the downloaded local copy of the metadata and click “Next”.

Choose an appropriate display name for the Relying Party. (e.g. Ververica Platform) and “Permit Everyone” for the initial Access Control Policy.

Mapping LDAP Attributes and SAML Claim values

Next, we’ll need to create an Admin group and a couple of users within the domain using the Active Directory Users and Computers tool. 

Create groups: VVP\admins, VVP\fraud-detection, and users: testuser1 and testuser2. Assign testuser1 to group VVP\admins, and testuser2 to VVP\fraud-detection.

Now we’ll switch back to Active Directory Federation Services window to edit the relying party (i.e. Ververica Platform)’s claim issuance policy.

The claim rules that need to be configured are as follows:

Claim rule name: LDAP email

Attribute store: Active Directory
Mapping of LDAP attributes to outgoing Claim Types:

• Email Addresses -> Email Address
• SAML-Account-Name -> Name ID

Claim rule name: Group
User's group: VVP/admins # In this case "VVP" was the domain.
Outgoing Claim Type: groups
Outgoing Claim Value: vvp-admins

Claim rule name: Group
User's group: VVP/fraud-detection # In this case "VVP" was the domain.
Outgoing Claim Type: groups
Outgoing Claim Value: fraudsters

Verifying User authentication and RBAC in VVP

We’ll start with testuser1 because we’ll need admin privileges in order to create the VVP logical namespace “fraud-detection” that testuser2 will later have access to.

Proceed to the login via SSO using the VVP endpoint url.

Now that we’ve logged in, we’ll create a new fraud-detection namespace and remove `owner:system-authenticated` from the members of the default namespace. 

This is so that only users under vvp-admins will be able to see `default` and that our other user “testuser2” will be confined to the “fraud-detection” namespace.

Members of “default” VVP namespace:

Members of “fraud-detection” VVP namespace:

Let’s verify the access restrictions are in-place by logging out of testuser1’s account and into testuser2’s!

As you can see above, testuser2 only has access to view and switch to the intended namespace. Testuser2 also is not an admin, so they lack privileges to add or modify any of its members or create API tokens!