How to Configure SAML Authentication with Kinetic v5.2

Instructions to complete a SAML authentication configuration for one or more spaces

  1. In this first step, you will be creating 4 scripts. Start by signing in to your server and then navigate to a working directory to create the required shell scripts.
    i. Create unpack.sh script:
nano unpack.sh

Copy and paste the below script into your new file.

#!/bin/bash 

# Create working directories 
echo ""
echo "Creating Working Directory to unpack gravity, note this directory will be cleaned up after task runs......"
echo ""
echo "Working DIR 1 Location: /working/kinetic-platform-charts"
mkdir -p /tmp/kinetic-platform-charts
echo ""
echo "Working DIR 2 Location: ~/core-customization"
mkdir ~/core-customization

# Unpack Gravity Charts
echo ""
echo "Unpack gravity to working dir 1"
echo "On prompt provide gravity install version"
read -r -p "Provide kinetic-platfrom version: " version
sudo gravity app unpack gravitational.io/kinetic-platform:"$version" /tmp/kinetic-platform-charts

# Prepare Working Directory Content
echo ""
echo "Copy relevant directory to working dir 2"
cp -r /tmp/kinetic-platform-charts/charts/platform/core-customization ~/core-customization
rm -rf ~/core-customization/files/secrets/*

# Create Backup of current Core 
echo ""
echo "Creating a backup"
kubectl get secret -n kinetic \
  core-customization-secrets \
  -o yaml \
  > core-customization-secrets.backup

Save the file.

ii. Now we are going to create the second script. Create get_files.sh:

nano get_files.sh

Copy and paste the below script into the created file get_files.sh

#!/bin/bash 

#Retrive secrets from backup file
echo ""
echo "Retrive secrets to be from the backup file created"
echo ""
echo "Provide secrete names to be retirved from core-customization-secrets.backup file"
read -r -p "Comma seperated list of secret names: " secret_names
IFS=', ' read -r -a secrets <<< "$secret_names"
echo "Looping through to create secret files from .backup file"
echo ""
for element in "${secrets[@]}"
do
export SECRET_NAME="$element"
kubectl get secret -n kinetic \
  core-customization-secrets \
  -o jsonpath="{.data.${SECRET_NAME//./\\.}}" \
  | base64 -d \
  > ~/core-customization/files/secrets/"$SECRET_NAME"
done


# Check  and View the newly created files 
echo ""
echo "Check created files"
ls ~/core-customization/files/secrets
echo ""
echo "Catting files to view files"
for element in "${secrets[@]}"
do
 echo ""
 file name: "$element"
 echo " "
 cat ~/core-customization/file/secrets/"$element" 
done
echo "file copy complete"
echo " Your next steps are: "
echo " "
echo "1. Update security.properties as seen in setup-saml.md"
echo ""
echo "2. Create secret.space-sug.properites for each spaceslug you wish to integrate saml in, ensure you have the correct values setup, see setup-saml.md"

Save the file.

iii. Now we are going to create the third script. Create config_specific.sh

nano config_specific.sh

Copy and paste the below script into the created file config_specific.sh

#!/bin/bash 

# Create security.space-slug.property for editing
echo ""
echo 'Createing security.space-slug.property file'
FILE=~/core-customization/file/secrets/security.Spaceslug.properties
if test -f "$FILE"; then
    echo "$FILE exists."
else
 echo ""
 echo "securit.Spaceslug.properites does not exist, please provide the approproiate file to copy"  
 echo ""
 ls ~/core-customization/file/secrets
 read -r -p "File name to be copied: " use_file
fi
echo ""
echo "Provoide comma seperated list of your space-slugs for implementation"
echo " "
read -r -p "Comma seperated list of space_slugs: " space_slugs
IFS=', ' read -r -a space_slug_list <<< "$space_slugs"
if test -f "$FILE"; then
    echo ""
    echo "Creating fies..."
    for element in "${space_slug_list[@]}"
    do
    echo ""
    cp "$FILE" ~/core-customization/file/secrets/"$element"
    echo " "
    done 
    echo ""
    echo "All done!"
    ls ~/core-customization/file/secrets
else
    echo ""
    echo "There is currently no template so we are duplicating an existing config as instructed"
    echo ""
    echo "Creating fies..."
    for element in "${space_slug_list[@]}"
    do
    echo ""
    cp ~/core-customization/file/secrets/"$use_file" ~/core-customization/file/secrets/"$element"
    echo " "
    done 
    echo ""
    echo "All done!"
    ls ~/core-customization/file/secrets
fi

Save the file.

iv. Now we are going to create the last script. Create integrate_saml.sh

nano integrate_saml.sh

Copy and paste the below script into the created file integrate_saml.sh

#!/bin/bash 

# Perform upgrade of core customizations 
echo ""
echo "Running the helm upgrade command........"
echo ""
sudo helm upgrade core-customizations ~/core-customization --namespace 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

Save the file and then check to confirm you have all 4 scripts.

ls

You can now make these scripts executable by running the following:

chmod u+x config_specific.sh
chmod u+x get_files.sh
chmod u+x integrate_saml.sh
chmod u+x unpack.sh
  1. After creating all 4 scripts above, you can now follow these next instructions to complete your SAML integration for your spaces.

i. You need to prepare your environment with the necessary files and working directions. Start by using the unpack.sh script.

./unpack.sh

ii. Prepare configuration files by running the get_files.sh script.

./get_files.sh

iii. These next couple steps are a manual processes.
a. Open security.properties file for edits

nano ~/core-customization/file/secrets/security.properties

b. Uncomment the following lines and ensure the values match

security.strategy=com.kineticdata.core.web.security.strategies.saml.SamlSecurityStrategy
security.keystore.path=/keystore.jks
security.keystore.password=changeit
security.keystore.defaultKey=defaultkey
    
#optionally: you could uncomment the below line if you are having issues with logging in some user
security.saml.maxAuthnAge=604800

iv. Run the config_specific.sh file to create the next files for manual changes.

./config_specific.sh

Make edits to your security.${space-slug}.properties files.

nano ~/core-customization/file/secrets/security.${space-slug}.properties (substitute space-slug with the working space-slug)

🚧

To Configure the Files

You will need to have information from your authentication provider to configured the files for each space_slug we have specified.

v. For each security.space_slug.properties file make the following changes:

Add the below lines to your file

security.saml.useForwardedForHeader=true
security.saml.loginPopup=true

Uncomment the below lines and make accurate substitutions on lines with notes

Note :
The security.saml.providers value has to match the the ${provider} for name, type and url.

security.autocreate=true 
security.autoupdate=true 
security.saml.enabled=true
security.saml.providers=urlbased (provide the value associated to the SAML provider)
security.saml.sp.entityid=com:acme:production:sp( set to the url of the space, can be same as security.saml.sp.url)
security.saml.sp.url=http://localhost:8080/kinetic/acme/app (example)
security.saml.idp.${provider}.name=Okta(saml provider name)
security.saml.idp.${provider}.type=url
security.saml.idp.${provider}.url=https://my-idp.acme.com/sso/saml/metadata

More Context :

security.saml.idp.${provider}.url should be an URL or path to your SAML metadata (provided by your SAML provider)

Here is an example of a security.${space-slug}.properties file for the space_slug saml-testing:

# The security system lets you choose whether the user details can auto-create and auto-update local user data.
# Not all configurers will necessarily support this behavior.
# NB: Successful authentications still require a valid User object within Core Edition.
security.autocreate=true
security.autoupdate=true

security.saml.useForwardedForHeader=true
security.saml.loginPopup=true

## Enable SAML support for this space.
security.saml.enabled=true
## Define the SAML attributes you'll map to email and display name.
security.saml.attributes.email=email
#security.saml.attributes.displayName=FullName
#security.saml.mappings.userAttribute.0.regexMatch=
#security.saml.mappings.userAttribute.0.regexReplace=
#security.saml.mappings.userAttribute.1.name=Office Location
#security.saml.mappings.userAttribute.1.mapping=Office Location
#security.saml.mappings.userAttribute.1.regexMatch=
#security.saml.mappings.userAttribute.1.regexReplace=

#security.saml.mappings.userAttribute.3.name=Site Location
#security.saml.mappings.userAttribute.3.mapping=Site Location


## SAML Service Provider Configuration

## Specify the base URL for the SAML service provider. This must be formatted like this:
## http[s]://hostname[:port]/context/[spaceSlug]/app
## The context will usually be "kinetic". Note that /app does not end in a trailing slash.
## Required: This is required for SAML to effectively build the automated metadata.
## The SP metadata URL is the URL specified plus: /saml/metadata/alias/space-slug
## Example SP Metadata URL: http://localhost:8080/kinetic/acme/app/saml/metadata/alias/acme
## This URL needs to be shared with the IdP.
security.saml.sp.url=https://saml-testing.kinops.io/app

## Specify a custom entity ID for this service provider.
## Optional. The default value is generated as "com:kineticdata:core:SPACESLUG:sp"
security.saml.sp.entityid=https://saml-testing.kinops.io/

## Advanced Service Provider settings:
## Profile used for verification of SSL/TLS connections.
## Values: "pkix" or "metaiop".
## Optional. Default "pkix"
#security.saml.sp.sslsecurityprofile=pkix

## The key used to sign interactions with the SP. This key must be in the keystore and it must
## contain both the public and private key.
#security.saml.sp.signingkey=defaultkey

## The key used to encrypt interactions with the SP. This key must be in the keystore and it must
## contain both the public and private key.
#security.saml.sp.encryptionkey=defaultkey

## Specify the keys for active IDPs.
security.saml.providers=ssocircle

## Example URL-based metadata.
## NB: You must ensure that the SSL certificate or trust certificate is in the global keystore.
security.saml.idp.ssocircle.name=SSO Circle
security.saml.idp.ssocircle.type=url
security.saml.idp.ssocircle.url=https://idp.ssocircle.com/meta-idp.xml

Note: you need to provide the correct mappings to display user information in your space.

vi. Execute the integrate_saml script.

./integrate_saml.sh

vii. After rollout restart is complete, check the state of your pods by running:

kubectl get pods -n kinetic

Ensure all pods are running and ready.

viii. Navigate to the following URL: https://${space-slug.example.com}/app/saml/metadata/alias/${space-slug}
to download the metadata needed. Remember to replace the URL with appropriate space-slug and domain information. Send this to your SAML provider and once the appropriate setting in configured by your SAML provider you can test your login.