How to Configure LDAP SSO Support for a Customer-Managed Environment

Overview

This guide outlines configuring single sign-on support using a Lightweight Directory Access Protocol (LDAP) for a customer-managed installation.

📘
For assistance with configuring SSO support in the kinops hosted platform, see How to Configure LDAP SSO Support for a Hosted Environment.

Prerequisites

Before starting the configuration process, open your desired terminal emulator, access the command line interface (CLI), and run the command below that corresponds to your package manager. This is required to parse the JSON used during the installation process.

sudo yum install jq

sudo apt-get update
sudo apt-get install jq

sudo dnf install jq

Additionally, ensure you can access a code editor to create script files. The instructions in this document use the vim editor, but you can use any editor you like.

Workstation Setup

From the workstation communicating with the Kubernetes cluster, follow these steps to create the necessary working directories and back up the current state of your SSO configuration.

⚠️
IMPORTANT: The scripts used in this process write to to ~/[Home Directory] by default. To change the location, replace ~/ with the desired location (for example, /opt/) in each script.
From your CLI, navigate to a path where you have permission to create and run the scripts necessary to configure SSO using LDAP.

Run the following commands to create the script files:

touch init_backup.sh
chmod +x init_backup.sh
vi init_backup.sh

Open the init.sh script in your code editor and paste the following content into the file:

#!/bin/bash 

set -e

# Create working directories 
echo ""
echo "Creating Working Directory to unpack SSO config template. Note: This directory will be cleaned up after the task runs..."
echo ""
echo "Working DIR 1 Location: ~/working-directory"
mkdir -p ~/working-directory 
echo ""
echo "Working DIR 2 Location: ~/existing-customization-data"
mkdir ~/existing-customization-data

# Create backup of current Core 
echo ""
echo "Creating a backup of existing authentication configuration data..."
kubectl get secret -n kinetic \
  core-customization-secrets \
  -o yaml \
  > ~/existing-customization-data/core-customization-secrets.backup
echo "Backup Completed"

Run the init.sh script using the following command:
```
./init_backup.sh
```
Return to the working directory using the cd command.
```
cd ~/working-directory
```

Retrieving the Helm Chart

Follow these steps to download the helm chart required for the configuration process:

kinetic-core-customizations-job            kinetic-platform-application
kinetic-core-customizations-job-5.0.0.tgz

Navigate to your Installer Dashboard.
From the Application tab, select View Files.
Click Need to edit these files? Click here to learn how.
Click Copy command under Step 1, then paste the command into your CLI and run it.
Run the ls command to see the kinetic-platform directory
```
ls
```
You should receive the response below. If you do not, contact Kinetic Support.
```
kinetic-platform-application
```
Run the cd command to navigate to the core-customizations folder:
```
cd ~/working-directory/kinetic-platform-application/upstream
```
Run the ls command to find the "kinetic-core-customizations-job-5.0.0.tgz" .tar file.
```
ls
```

Copy the .tar file to your working directory.

cp kinetic-core-customizations-job-5.0.0.tgz ~/working-directory

Run the following commands to relocate to the working directory and untar the file:
```
cd ~/working-directory && tar xvf kinetic-core-customizations-job-5.0.0.tgz
```
Run the ls command to confirm the kinetic-core-customizations-job folder was created.
```
ls
```
You should receive the response below. If you do not, contact Kinetic Support.
```
kinetic-core-customizations-job            kinetic-platform-application
kinetic-core-customizations-job-5.0.0.tgz
```

Run the following command to move the "core-customizations" folder to your working directory.

cp -R ~/working-directory/kinetic-core-customizations-job/files/core-customizations ~/working-directory

Run the ls command to confirm the kinetic-core-customizations-job folder was moved correctly.
```
ls
```
You should receive the response below. If you do not, contact Kinetic Support.
```
core-customizations              kinetic-core-customizations-job-5.0.0.tgz
kinetic-core-customizations-job  kinetic-platform-application
```
Run the following command to remove the existing configuration files from the core customization folder:
```
rm -rf ~/working-directory/core-customizations/files/secrets/*
```

Run the following command to create the chart .yaml file:

mv ~/working-directory/core-customizations/Secret.yaml ~/working-directory/core-customizations/Chart.yaml

Retrieve Existing Configuration Files from the Environment

Run the command below to create get_files.sh. This script retrieves the existing configuration files from your environment.

touch ~/existing-customization-data/get_files.sh
chmod u+x ~/existing-customization-data/get_files.sh

vi ~/existing-customization-data/get_files.sh

Copy the following text into get_files.sh:

#!/bin/bash 

set -e 

#Retrive secrets from backup file
echo ""
echo "Retreive secrets in the environment"
echo ""


kubectl get secret -n kinetic core-customization-secrets -o json > core-customization-secrets.json

file='core-customization-secrets.json'
cat "$file" | jq -r '.data | keys[]' | 
while IFS= read -r value; do
    echo "$value"
    kubectl get secret -n kinetic \
        core-customization-secrets \
        -o jsonpath="{.data.${value//./\\.}}" \
        | base64 -d \
        > ~/working-directory/core-customizations/files/secrets/"$value"
done


kubectl get secret -n kinetic core-customization-secrets -o jsonpath="{.data.security\.servicecatalog-test\.properties}" | base64 -d > ~/working-directory/core-customizations/files/secrets/security.servicecatalog-test.properties
kubectl get secret -n kinetic core-customization-secrets -o jsonpath="{.data.security\.servicecatalog-dev\.properties}" | base64 -d > ~/working-directory/core-customizations/files/secrets/security.servicecatalog-dev.properties
kubectl get secret -n kinetic core-customization-secrets -o jsonpath="{.data.security\.properties}" | base64 -d > ~/working-directory/core-customizations/files/secrets/security.properties
kubectl get secret -n kinetic core-customization-secrets -ojsonpath="{.data.keystore\.jks}" | base64 -d > ~/working-directory/core-customizations/files/secrets/keystore.jks

# Check  and View the newly created files 
echo ""
echo "Check created files"
ls ~/working-directory/core-customizations/files/secrets
echo ""
echo "Catting files to view files"
for element in "${secrets[@]}"
do
 echo ""
 file name: "$element"
 echo " "
 cat ~/working-directory/core-customizations/files/secrets/"$element" 
done

echo "File copy complete"
echo "Your next steps are: "
echo " "
echo "1. Update security.properties as seen in the LDAP Configuration section of your guide."
echo ""
echo "2. Create secret.space-sug.properites for each Space slug you wish to integrate SAML in. Ensure you have the correct values set up. See setup-ldap.md for more information."

Run the cd command to navigate to the "existing-customization-data" directory.
```
cd ~/existing-customization-data
```
Run the following command to execute the "get_existing_configuration_files.sh" script:
```
./get_existing_configuration_files.sh
```

Update the Configuration File to Enable LDAP Strategy

Run the following command to navigate to the core customization configuration folder and view the files in the folder:
```
cd ~/working-directory/core-customizations/files/secrets && ls
```

Modify the security.properties file in the configuration folder to enable the LDAP strategy by uncommenting the specified properties.

ℹ️
Adding line one is what enables the LDAP strategy.

security.strategy=com.kineticdata.core.web.security.strategies.ldap.LdapSecurityStrategy
security.keystore.path=/keystore.jks
security.keystore.password=*******
security.keystore.defaultKey=defaultkey

Create a Space-level configuration file for the Space where you want to enable the LDAP strategy. Replace the word "EXAMPLE" with the space slug of the space you want to configure in the below command:
```
cp security.SPACESLUG.properties security.EXAMPLE.properties
```

Open the security.space-slug.properties file to meet your organization's specifications by following the pattern in the example below.
IMPORTANT: The following code is only an example of the security.space-slug.properties file and must be edited for your Space. If you need assistance configuring this file, contact Kinetic Support with your LDAP resource available for assistance.

security.ldap.enabled=true
security.autocreate=true
security.autoupdate=true
security.ldap.context.url=ldap://fake_ldap:389
security.ldap.context.baseDN=DC=corp,DC=fake_ldap_dc,DC=io
security.ldap.context.bindDN=CN=Admin,OU=Users,OU=CORP,DC=corp,DC=fake_ldap_dc,DC=io
security.ldap.context.bindPswd=rdWJL-YaGY2pzRns-G2*
security.ldap.user_search_base=
security.ldap.user_search_filter=(sAMAccountName={0})
#security.ldap.group_search_base=
#security.ldap.group_search_subtree=true
security.ldap.group_search_filter=(uniqueMember={0})
# security.ldap_group_role_prefix=ROLE_ # defaults to blank.
# security.ldap.group_role_attribute=ou # defaults to 'cn'
## These Attributes are used to map users looked up to the user table.
security.ldap.attributes.email=mail
security.ldap.attributes.displayName=displayName
#security.ldap.mappings.userAttribute.0.name=LDAP Department
#security.ldap.mappings.userAttribute.0.mapping=department
#security.ldap.mappings.userAttribute.0.regexMatch=
#security.ldap.mappings.userAttribute.0.regexReplace=
#security.ldap.mappings.userAttribute.1.name=LDAP Country
#security.ldap.mappings.userAttribute.1.mapping=co
#security.ldap.mappings.userAttribute.1.regexMatch=
#security.ldap.mappings.userAttribute.1.regexReplace=
#security.ldap.mappings.userAttribute.2.name=LDAP Manager Name
#security.ldap.mappings.userAttribute.2.mapping=manager
#security.ldap.mappings.userAttribute.2.regexMatch=CN=(.*?),(CN|OU)=.*
#security.ldap.mappings.userAttribute.2.regexReplace=$1
#security.ldap.mappings.profileAttribute.0.name=LDAP Phone number
#security.ldap.mappings.profileAttribute.0.mapping=ipPhone
#security.ldap.mappings.profileAttribute.0.regexMatch=
#security.ldap.mappings.profileAttribute.0.regexReplace=

Configure Core Customization Using configure.sh

From your CLI, run the following command:

touch ~/working-directory/configure.sh
chmod u+x ~/working-directory/configure.sh
vi ~/working-directory/configure.sh

Run the following command to update the configure.sh file:

#!/bin/bash 

# Perform upgrade of core customizations 
echo ""
echo "Running the helm upgrade command..."
echo ""
helm upgrade core-customizations ~/working-directory/core-customizations -n kinetic 

# Restart core deployment to apply new changes
echo ""
echo "Roll out Restart Core"
kubectl rollout restart deployment core -n kinetic
kubectl rollout status deployment core -n kinetic -w

Run the following command:
```
cd ~/working-directory/
./configure.sh
```

Test Your Configuration and Clean Up

Open your Kinetic login page. You should be signed in automatically if your LDAP SSO connection was configured correctly.
If the test is successful, run the following command to clean up the working directory you created:
```
rm -rf ~/working-directory
```
If the test is unsuccessful, contact Kinetic Support for assistance.