How to reference file in HQ config file in EC2 instance

General
1

Hello Lenses Support Team,

We would like to raise a request regarding the current setup for Lenses login and SAML/SSO integration.

At present, the SAML/SSO metadata file needs to be embedded directly within the configuration file. From an operational and formatting standpoint, this approach is not very convenient to manage or maintain. Our current SAML/SSO metadata is expired so we need to update.

We believe it would be more efficient if the SAML/SSO metadata could be stored in a separate file and referenced during the Lenses HQ service startup. This would improve readability, simplify certificate updates, and reduce the risk of formatting issues within the configuration.

Could you please advise if this approach is supported, or if there are any recommended best practices to achieve this?

We look forward to your guidance on this matter.

2

This is how to configure HQ to work with metadata.xml file on EC2 through env var

Configuration File (config.yaml)

The config file uses environment variable substitution with $(VAR_NAME) syntax:

auth:
  saml:
    enabled: true
    baseURL: https://your-hq-domain.com
    entityID: https://your-hq-domain.com
    metadata: $(SAML_METADATA)
    userCreationMode: sso
    groupMembershipMode: sso
    uiRootURL: /
    groupAttributeKey: groups
    authnRequestSignature:
      enabled: false

Setting Up SAML Metadata on EC2

Step 1: Save your IdP metadata to a file
# Create the metadata file. Please make sure that your metadata.xml file is correctly indented

cat > /etc/lenses-hq/saml-metadata.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ...>
  <!-- Your full SAML IdP metadata XML here -->
</md:EntityDescriptor>
EOF

Step 2: Export the environment variable
# Load the file content into an environment variable

export SAML_METADATA="$(cat /etc/lenses-hq/saml-metadata.xml)"

Step 3: Start Lenses HQ
# Start HQ with the config file - it will substitute $(SAML_METADATA)

Systemd Service Example

For persistent configuration with systemd, create an environment file:
/etc/lenses-hq/env

LENSESHQ_LICENSE=your-license-key
LENSESHQ_PG_USERNAME=postgres
LENSESHQ_PG_PASSWORD=your-db-password

/etc/systemd/system/lenses-hq.service

[Unit]
Description=Lenses HQ
After=network.target

[Service]
Type=simple
User=lenses
EnvironmentFile=/etc/lenses-hq/env
ExecStartPre=/bin/bash -c 'echo "SAML_METADATA=$(cat /etc/lenses-hq/saml-metadata.xml)" >> /run/lenses-hq/env'
ExecStart=/opt/lenses-hq/bin/lenses-hq /etc/lenses-hq/config.yaml
Restart=on-failure

[Install]
WantedBy=multi-user.target

Or use a wrapper script:
/opt/lenses-hq/bin/start-hq.sh

#!/bin/bash
set -e

# Load SAML metadata from file into environment variable
export SAML_METADATA="$(cat /etc/lenses-hq/saml-metadata.xml)"

# Load other environment variables
source /etc/lenses-hq/env

# Start Lenses HQ
exec /opt/lenses-hq/bin/lenses-hq /etc/lenses-hq/config.yaml

Verifying the Setup

# Verify the metadata file exists and is valid XML
cat /etc/lenses-hq/saml-metadata.xml | head -5

# Verify the environment variable is set correctly
export SAML_METADATA="$(cat /etc/lenses-hq/saml-metadata.xml)"
echo "SAML_METADATA length: ${#SAML_METADATA} characters"

# Test the first 100 characters
echo "$SAML_METADATA" | head -c 100

Hope this helps!

Kind regards,
Ivan