Installing and Configuring Load Balancer

Configuring a load balancer might be helpful when setting up multiple SCIMConnector instances to achieve high availability. The information below describes an example of using the free, open-source Nginx web server as a load balancer. However, you can configure any load balancer as per your requirements.

Installing NGINX

For Windows operating system, you can download the NGINX from the NGINX official website.

To install the NGINX:

  1. Download the nginx/Windows-x.xx.x.zip package from stable version.

  2. Unzip pakcage and go to the nginx-x.xx.x directory.

  3. Run the NGINX by using the following command for the drive C: root directory:

    Copy 
    cd c:\
    unzip nginx-1.27.0.zip
    cd nginx-1.27.0
    start nginx

  4. Run the tasklist command-line utility to see nginx processes:

    Copy 
    C:\nginx-x.xx.x>tasklist /fi "imagename eq nginx.exe"
    Image Name           PID Session Name     Session#    Mem Usage
    =============== ======== ============== ========== ============
    nginx.exe            652 Console                 0      2 780 K
    nginx.exe           1332 Console                 0      3 112 K

  5. One of the processes is the primary process, and the other is the worker process. If nginx does not start, look for the reason in the error log file logs\error.log.

  6. Once Nginx starts successfully, you can check it in the browser by entering http://localhost:80. You can also configure Nginx on a different port by making changes in the C: nginx-x.xx. xconfnginx.config file in case the default port is in use by another application.

NGINX/Windows runs not as a service but as a standard console application. You can manage it using the commands described in the table below.

Command Description
nginx -s stop Performs a fast shutdown.
nginx -s quit Performs a soft shutdown.
nginx -s reload Changing the configuration, starts a new worker processes with a new configuration, performs a soft shutdown of old worker processes.
nginx -s reopen Re-opens the log files.
nginx -t Checks a server status.

Configuring a Self-Signed Certificate with NGINX

To run NGINXNginx on an HTTPS port, you must provide SSL certificates. You can create a self-signed certificate using the NGINX.

Installing OpenSSL

To install the OpenSSL:

  1. Download the latest version of OpenSSL for Windows from the OpenSSL official website.

  2. Run an installer as Administrator to install OpenSSL.

  3. Once the installation is completed, find and edit the Path variable under the System Environment Variables to include the path to your OpenSSL bin directory (e.g., C:\Program Files\OpenSSL-Win64\bin).

Generating a Self-Signed Certificate via OpenSSL:

To generate a self-signed certificate using the OpenSSL:

  1. Open a PowerShell prompt and run the following script:

    Copy 
    param (
        [Parameter(Mandatory=$true)][string]$certificatename,
        [Parameter(Mandatory=$true)][SecureString]$certificatepassword
     )
    # setup certificate properties including the commonName (DNSName) property for Chrome 58+
    $certificate = New-SelfSignedCertificate `
        -Subject localhost `
        -DnsName localhost `
        -KeyAlgorithm RSA `
        -KeyLength 2048 `
        -NotBefore (Get-Date) `
        -NotAfter (Get-Date).AddYears(2) `
        -CertStoreLocation "cert:CurrentUser\My" `
        -FriendlyName "Localhost Certificate for .NET Core" `
        -HashAlgorithm SHA256 `
        -KeyUsage DigitalSignature, KeyEncipherment, DataEncipherment `
        -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.1") 
    $certificatePath = 'Cert:\CurrentUser\My\' + ($certificate.ThumbPrint)
    # create temporary certificate path

    $tmpPath = "C:\tmp"
    If(!(test-path $tmpPath))
    {
    New-Item -ItemType Directory -Force -Path $tmpPath
    }

    # set certificate password here
    $pfxPassword = $certificatepassword
    $pfxFilePath = $tmpPath + "\" + $certificatename + ".pfx"
    $cerFilePath = $tmpPath + "\" + $certificatename + ".cer"

    # create pfx certificate
    Export-PfxCertificate -Cert $certificatePath -FilePath $pfxFilePath -Password $pfxPassword

    Export-Certificate -Cert $certificatePath -FilePath $cerFilePath
    # import the pfx certificate
    Import-PfxCertificate -FilePath $pfxFilePath Cert:\LocalMachine\My -Password $pfxPassword -Exportable

    # trust the certificate by importing the pfx certificate into your trusted root
    Import-Certificate -FilePath $cerFilePath -CertStoreLocation Cert:\CurrentUser\Root

    # optionally delete the physical certificates (don’t delete the pfx file as you need to copy this to your app directory)
    # Remove-Item $pfxFilePath
    Remove-Item $cerFilePath

  2. Convert a PFX file to separate PEM and KEY files by tunning the following comand:

    Copy 
    openssl pkcs12 -in C:/tmp/localhost.pfx -clcerts -nokeys -out C:/tmp/pem/certificate.pem
    openssl pkcs12 -in C:/tmp/localhost.pfx -nocerts -nodes -out C:/tmp/pem/private.key

  3. Set the certificate file and the key file path in nginx.conf file as following:

    Copy 
    http {
       server {
          listen 8443 ssl;
            
          ssl_certificate C:/tmp/pem/certificate.pem;
          ssl_certificate_key C:/tmp/pem/private.key;
       }
    }

  4. Reload the NGINX using the command nginx -s reload and check server status using the nginx –t command.

  5. Enter https://localhost:8443 URL in a browser. Then NGINX default web page should be displayed.

Configuring SCIM Connector instances with NGINX

Configuring the SCIMConnector instances with NGINX requires running them in multi-instance mode.

To install a SCIMConnector in a multi-instance mode:

  1. Add SCIMConnector instances' IP addresses with the port number (on which SCIMConnector is running) as an upstream server in nginx.conf file as below.

    Copy 
    upstream backendssl {
                    server 10.00.00.000:8443 max_fails=2 fail_timeout=10s;
                    server 10.00.00.000:443 max_fails=2 fail_timeout=10s;
            }

  2. Configure a proxy server setting in nginx.config file to distribute requests between SCIMConnector instances as below.

    Copy 
    server {
            listen       8080 ssl;
            listen       8443 ssl;
            server_name  localhost;
        
            ssl_certificate      C:/tmp/pem/certificate.pem;
            ssl_certificate_key  C:/tmp/pem/private.key;

            location /SCIMConnector/ {
                proxy_pass https://backendssl/scimconnector/;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-Port $server_port;
                proxy_set_header X-Forwarded-Uri $request_uri;
                   
              # Configure retry behavior
            proxy_next_upstream error timeout http_500 http_502 http_503 http_504;
            proxy_next_upstream_timeout 5s;
            proxy_next_upstream_tries 3;
            
             #  Set connection timeout
             proxy_connect_timeout 1s;
           }
        }

  3. Set a retry behavior settings if required.

  4. Now, SCIMConnector should be accessible via https://localhost:8443/SCIMConnector. The port may vary according to the configuration in the Nginx.config file.