Setup a Static IP for Ruby LDAP Authentication

Learn how to securely route Ruby LDAP authentication requests through a QuotaGuard Static IP proxy.

Prerequisites

# net-ldap Gem
gem install net-ldap

Instructions

Run example

Using Docker (Recommended)
# Build the image
docker build -t ruby-ldap-example .

# Run with your QuotaGuard Static URL
docker run -e QUOTAGUARDSTATIC_URL="your-quotaguard-static-url" ruby-ldap-example

Running locally
# Set your QuotaGuard Static URL
export QUOTAGUARDSTATIC_URL="your-quotaguard-static-url"

# Install dependencies
gem install net-ldap

# Run the script
ruby ldap.rb

Required Environment Variables
  • QUOTAGUARDSTATIC_URL: Your QuotaGuard Static URL (required)
    • Format: socks5://username:password@proxy-host:port
    • Example: socks5://user:pass@proxy.quotaguard.com:1080

Optional Environment Variables

  • QGTUNNEL_DEBUG: Set to true for debugging QGTunnel operations (optional, defaults to true)

About this example

This example demonstrates how to connect to an LDAP directory server through QuotaGuard Static using the QGTunnel proxy.

The example uses a publicly available LDAP test server (ldap.forumsys.com) provided by Forumsys for testing purposes. This server contains sample directory data that can be used for testing LDAP connections.

LDAP Server Details
  • Host: ldap.forumsys.com
  • Port: 389 (standard LDAP port)
  • Base DN: dc=example,dc=com
  • Bind DN: cn=read-only-admin,dc=example,dc=com
  • Password: password

QGTunnel Configuration Requirements

For this example to work properly, your QGTunnel configuration must include the following settings:

  • Remote Destination: tcp://ldap.forumsys.com:389
  • Local Port: 1389
  • Transparent Mode: enabled

This configuration allows the Ruby script to connect to localhost:1389, which QGTunnel will transparently forward to ldap.forumsys.com:389 through your QuotaGuard Static proxy.

What the example does
  1. Establishes a connection to the LDAP server through QGTunnel
  2. Authenticates using the read-only admin credentials
  3. Searches for all entries in the directory
  4. Displays common attributes for each entry (CN, UID, email, object classes)
  5. Performs a specific search for users with UID attributes
  6. Reports the total number of users found

Expected Output

The example should successfully connect to the LDAP server and display information about the test users and groups available in the Forumsys test directory.

Environment Variables
  • QUOTAGUARDSTATIC_URL: Your QuotaGuard Static URL (required)
  • QGTUNNEL_DEBUG: Set to true for debugging QGTunnel operations (optional)

Code Samples

ldap.rb
#!/usr/bin/env ruby

require 'net/ldap'

# Check for required environment variable
unless ENV['QUOTAGUARDSTATIC_URL']
  puts "✗ Error: QUOTAGUARDSTATIC_URL environment variable is required"
  puts "Please set your QuotaGuard Static URL:"
  puts "  export QUOTAGUARDSTATIC_URL='your-quotaguard-static-url'"
  puts "  or"
  puts "  docker run -e QUOTAGUARDSTATIC_URL='your-url' ruby-ldap-example"
  exit 1
end

puts "Using QuotaGuard Static URL: #{ENV['QUOTAGUARDSTATIC_URL'].gsub(/\/\/.*@/, '//***:***@')}"
puts

# Using a publicly available LDAP test server
ldap_host = 'ldap.forumsys.com' # This is a demo LDAP server provided by Forumsys for testing
ldap_port = 1389 # Local Port for QGTunnel
base_dn = 'dc=example,dc=com'

# Create LDAP connection
ldap = Net::LDAP.new(
  host: ldap_host,
  port: ldap_port,
  base: base_dn,
  auth: {
    method: :simple,
    username: 'cn=read-only-admin,dc=example,dc=com',
    password: 'password'
  },
  connect_timeout: 10,
  operation_timeout: 30
)

begin
  puts "Connecting to LDAP server: #{ldap_host}:#{ldap_port}"
  puts "Base DN: #{base_dn}"
  puts "Authentication: read-only-admin"
  puts

  # Test the connection
  if ldap.bind
    puts "✓ Successfully connected and authenticated to LDAP server"
    puts

    # Search for all entries (using a more appropriate filter)
    puts "Searching for all entries in the directory..."
    filter = Net::LDAP::Filter.present('objectClass')
    
    entry_count = 0
    ldap.search(filter: filter, size: 20) do |entry|
      entry_count += 1
      puts "Entry #{entry_count}: #{entry.dn}"
      
      # Display some common attributes
      if entry['cn'] && !entry['cn'].empty?
        puts "  Common Name (CN): #{entry['cn'].first}"
      end
      
      if entry['uid'] && !entry['uid'].empty?
        puts "  User ID (UID): #{entry['uid'].first}"
      end
      
      if entry['mail'] && !entry['mail'].empty?
        puts "  Email: #{entry['mail'].first}"
      end
      
      if entry['objectClass'] && !entry['objectClass'].empty?
        puts "  Object Classes: #{entry['objectClass'].join(', ')}"
      end
      
      puts
    end
    
    puts "Found #{entry_count} entries in the directory"
    puts

    # Search for specific users
    puts "Searching for users with uid attribute..."
    user_filter = Net::LDAP::Filter.present('uid')
    
    user_count = 0
    ldap.search(filter: user_filter, size: 10) do |entry|
      user_count += 1
      uid = entry['uid'] && !entry['uid'].empty? ? entry['uid'].first : 'unknown'
      puts "User #{user_count}: #{uid} (#{entry.dn})"
    end
    
    puts "Found #{user_count} users in the directory"

  else
    puts "✗ Failed to connect or authenticate to LDAP server"
    puts "Error: #{ldap.get_operation_result.message}"
    exit 1
  end

rescue => e
  puts "✗ Error occurred during LDAP operation:"
  puts "Error: #{e.message}"
  exit 1
end

puts "\n✓ LDAP test completed successfully!"

Docker File
FROM ruby:latest

WORKDIR /app/

# Update the package list
RUN apt-get update -qq && apt-get install -y curl

# Install net-ldap gem
RUN gem install net-ldap

# Download and extract QGTunnel software
RUN curl https://s3.amazonaws.com/quotaguard/qgtunnel-latest.tar.gz | tar xz

# Environment variables (can be overridden at runtime)
ENV QGTUNNEL_DEBUG=true

COPY ldap.rb ldap.rb

CMD ["bin/qgtunnel", "ruby", "ldap.rb"]