Kerberos Buildpack for VMware Tanzu Application Service for VMs (TAS for VMs)

Learn how to configure Kerberos on Linux, so that Kerberos and Integrated Windows Authentication (IWA) work natively in .NET and Java applications.

How it works

architecture diagram

This buildpack includes a sidecar process that manages the configuration of MIT Kerberos, which is used by the core libraries in apps to participate in Kerberos authentication (also known as Integrated Windows Authentication).

Configuring application credentials

Before using the Kerberos Buildpack for VMware Tanzu Application Service for VMs (TAS for VMs), you must determine how credentials will be configured for each application. There are several ways for this information to be provided to the buildpack:

Using environment variables
Using CredHub integration
Using user-provided services

Using environment variables

The simplest approach is to set the following environment variables for your app:

KRB_SERVICE_ACCOUNT: service account name (in [email protected] format)
KRB_PASSWORD: service account password
KRB_KDC: (optional) Kerberos Key Distribution Center (KDC) address. If not specified, the domain part of KRB_SERVICE_ACCOUNT will be used

Using CredHub integration

CredHub integration allows the safe administration and storage of credentials associated with an app inside of CredHub. With this integration, credentials will be injected as environment variables during container startup. Because this integration is activated during startup, the credentials will be only visible to the app process.

Prerequisite The [CredHub service broker](https://docs.vmware.com/en/CredHub-Service-Broker/index.html) must be installed

Create a file named credentials.json, with contents similar to this:

{
   "ServiceAccount": "[email protected]",
   "Password": "<secure-password>"
}

Create a CredHub service instance that carries the above credentials as following:

cf create-service credhub default CREDS_SERVICE_INSTANCE_NAME -c .\credentials.json -t kerberos-service-principal

Bind the credentials to the app
- Using the cf cli (if the app has already been pushed):
```
cf bind-service APP_NAME CREDS_SERVICE_INSTANCE_NAME
```
- Using a service reference in an application manifest:
```
---
    ...
    services:
    - name: CREDS_SERVICE_INSTANCE_NAME
```

Managing credentials via user-provided services

In order to use user-provided services, follow the CredHub integration steps, only changing the service instance creation:

cf create-user-provided-service CREDS_SERVICE_INSTANCE_NAME -p .\credentials.json -t kerberos-service-principal

Embedding Kerberos configuration into buildpack

By default, the buildpack will attempt to generate an MIT Kerberos configuration file (krb5.conf) using the combination of KRB_KDC and the realm portion of the service account (everything after @). This may not be sufficient in more complex environments, where greater control of the krb5.conf is required. Including location of the KDC in the manifest for every single application may also not be desirable.

In order to support these scenarios, krb5.conf should be embedded within the buildpack before deployment to the platform. This approach provides uniform application of configuration to all apps and places control over this file in the hands of central platform operator. In order for the buildpack to use your embedded krb5.conf, place the file within the buildpack zip file under /deps/.krb5/krb5.conf. One way to accomplish this task is by following these steps:

Creating a local directory structure that looks like this:

.
├── kerberos_buildpack-linux-x64-0.1.0.zip
├── deps
│   └── .krb5
│       └── krb5.conf

Run the following command to patch the zip file with config file:

PowerShell

Compress-Archive -Update -Path deps -DestinationPath kerberos_buildpack-linux-x64-0.1.0.zip

Linux shell

zip -ur kerberos_buildpack-linux-x64-0.1.0.zip deps

Configuring for multiple environments

If krb5.conf needs to change between environments, multiple krb5.conf files can be embedded into the buildpack by creating a folder structure similar to the following and applying the same steps as above:

.
├── kerberos_buildpack-linux-x64-0.1.0.zip
├── deps
│   └── .krb5
│       ├── prod
│       │   └── krb5.conf
│       └── qa
│           └── krb5.conf

You can control which krb5.conf is used by setting the environment variable KRB_ENVIRONMENT to match the folder name.

Using the buildpack

The Kerberos buildpack is an extension buildpack and is not capable of running applications by itself. Another buildpack, such as the .NET Core or Java buildpack must also be used.

Use multiple buildpacks from the command line:

cf push APP-NAME -b KERBEROS-BUILDPACK-NAME-OR-URL -b dotnet_core_buildpack

Use multiple buildpacks in an app manifest:

---
applications:
- name: KerberosDemo
  buildpacks: 
    - KERBEROS-BUILDPACK-NAME-OR-URL
    - dotnet_core_buildpack

Troubleshooting

Because the buildpack provides functionality via sidecar, the first place to check when issues arise will be the application logs. Please note that sidecar logs may be intermixed with app logs. If the logs do not include a message similar to Service authenticated successfully as 'iwaclient' or Now listening on: http://0.0.0.0:9090, it may mean that the worker sidecar has been unable to obtain ticket from your KDC.

If there is nothing useful in the logs, check these items:

Credentials are correct and specified in the right format
The KDC is accessible from the container. Use the sample app to test.
Increase the verbosity of Kerberos-related logs by setting the following environment variable for the app:
- Logging__LogLevel__Kerberos: Debug

Sample Application

If you are having trouble, or just getting started with the Kerberos Buildpack for VMware Tanzu Application Service for VMs (TAS for VMs), the sample app that ships alongside the buildpack can be used to test connectivity and validate or understand a variety of settings. Here is a partial list of functionality the sample includes:

Test that a connection can be established to a KDC server on port 88.
Test a connection to SQL Server, optionally specifying the connection string via query string for quick iteration.
Check the health of the sidecar process.

See the README included with the sample for additional functionality and greater detail.