Setting up the SSO Connector using Linux

We recommend deploying the SSO connector on one of our pre-configured versions hosted on Azure or AWS. 

• Azure pre-configured SSO connector (recommended)
• AWS pre-configured SSO connector
• Linux (advanced use cases only, this article)

This article explains how to set up the SSO Connector on a Linux machine.

SSO Connector requirements

Linux/Docker

You will need a (virtual) machine running a Linux distro that supports Docker.

Networking

The SSO Connector leverages TCP/443 to communicate with the Dashlane Servers (*.dashlane.com) and end-user clients. For the end-user clients, the SSO Connector needs to be reachable via an HTTPS URL (such as https://ssoconnector.mycompany.com). If a proxy or load balancer is used, the Docker instance running the SSO Connector can use a different port than 443. For example, if a load balancer is used to run multiple instances of the SSO Connector, the load balancer should advertise itself on port 443, while the SSO Connector can advertise itself on any port (the default is 3000). If the SSO Connector is directly accessible, you will need the corresponding SSL certificate for the domain.

Config file

The config file downloaded from Dashlane's Admin Console is used to configure the SSO Connector. Information needs to be entered into the Admin Console so that the config file can be generated and then downloaded. This includes:

1. The SAML metadata of the identity provider
2. The SSO Connector endpoint, which is the endpoint that the SSO Connector can be accessed from (for example, https://ssoconnector.mycompany.com)
3. The SSO Connector key generated from the Dashlane Admin Console, which is the unique key that allows Dashlane to have a zero knowledge architecture. Note: If this key is lost, all user data will be lost. Make sure that the key is stored in a safe and memorable location.

Deploying the SSO Connector on a virtual machine

The high level steps to deploy the SSO Connector include:

1. Deploying a VM with a Linux distro that supports docker. Install Docker following Docker's installation guides. In our example we deployed an Ubuntu Linux VM.
2. Adding an A record to your DNS for the SSO connector (e.g. ssoconnector.mycompany.com).
3. Transferring over the SSO config file (and make any necessary modifications for the SSL set up).
4. Running a Docker command to instantiate the service.

Configure a Ubuntu Linux machine and install Docker

1. SSH into your Linux machine. This will require the machine and any networking configuration to open incoming traffic to port 22.
2. As the administrator of the machine, install Docker. For production environments using Ubuntu, you can follow the installation method using the repository as shown here. You can use any Linux user (or service account) for running Docker.
3. Configure your DNS and any networking layers to appropriately route traffic going to your SSO Connector endpoint (https://ssoconnector.mycompany.com) to the VM.

Set up the SSO Connector (with a proxy or load balancer present)

This setup assumes that the SSL encryption will be handled by another service, such as a load balancer. If there is no proxy or load balancer, see the next section.

1. Transfer the SSO Connector config file to your Linux machine.
2. Modify the following command appropriately and execute it to start the SSO Connector service
   1. Update <PORT USED BY PROXY> with the port number that the Proxy is listening to
   2. Update <PATH TO CONFIG FILE> with the local path to the SSO Connector config file that you transferred over

      docker run -p <PORT USED BY PROXY>:3000 --name dashlane-sso-connector --env-file=<PATH TO CONFIG FILE> --restart=always --privileged=false dashlane/sso-connector:1

      For example:

      docker run -p 8080:3000 --name dashlane-sso-connector --env-file=/home/usr/dashlane-sso-config.env --restart=always --privileged=false dashlane/sso-connector:1

      Option	Description	Link to Docker documentation
      -p	Used to bind the ports that the SSO Connector service will listen to. 3000 is the default port, and can be changed to any value	Reference link
      --name	Name given to the container	Reference link
      --env-file	The local path to the SSO Connector config file that has all of the necessary environment variables	Reference link
      --restart=always	The docker container will be restarted if the machine accidentally reboots	Reference link
      --privileged=false	Used to ensure that machine's privileged access is not used (as it is not necessary to run the SSO Connector)	Reference link
      dashlane/sso-connector:1	The image that is download from the official Docker repository that has the first (and latest) version of the package of the SSO Connector	Reference link

3. If running the command resulted in the SSO Connector running successfully, skip to the "Successful SSO Connector set up" section below. Otherwise skip to the "Troubleshooting the SSO Connector" section below. A successful output will look similar to:
   

Set up the SSO Connector (without a proxy or load balancer present)

If the SSO Connector will also manage the SSL certificate (done when a proxy or load balancer isn't being used), then do the following:

1. Transfer the SSO Connector config file to your Linux machine.
2. Copy the SSL certificate and its corresponding private key to the Linux machine.
3. Edit the SSO Connector config file and add the following two environment variables to the bottom of the file.

   DASHLANE_SSO_SSL_CERTIFICATE=/certificate.crt
   DASHLANE_SSO_SSL_PRIVATE_KEY=/private.key

   The file show look similar to the following:

   

4. Modify the following command appropriately and execute it to start the SSO Connector service:
   1. Update <PATH TO CONFIG FILE> with the local path to the SSO Connector config file that you transferred over.
   2. Update <PATH TO SSL CERTIFICATE> with the local path to the SSL certificate.
   3. Update <PATH TO SSL CERTIFICATE> with the local path to the SSL certificate's private key.

   docker run -p 443:3000 --name dashlane-sso-connector --env-file=<PATH TO CONFIG FILE> -v <PATH TO SSL CERTIFICATE>:/certificate.crt -v
   <PATH TO SSL CERTIFICATE PRIVATE KEY>:/private.key --restart=always --privileged=false dashlane/sso-connector:1

   For example:

   docker run -p 443:3000 --name dashlane-sso-connector --env-file=/home/usr/dashlane-sso-config.env -v /home/usr/certificate.crt:/certificate.crt -v /home/usr/private.key:/private.key --restart=always --privileged=false dashlane/sso-connector:1

   Option	Description	Link to Docker documentation
   -p	Used to bind the ports that the SSO Connector service will listen to. 3000 is the default port, and can be changed to any value. 443 is used for HTTPS	Reference link
   --name	Name given to the container	Reference link
   --env-file	The local path to the SSO Connector config file that has all of the necessary environment variables	Reference link
   -v	Mounts a read-only volume for the container so that the SSO Connector can access the files	Reference link
   --restart=always	The docker container will be restarted if the machine accidentally reboots	Reference link
   --privileged=false	Used to ensure that machine's privileged access is not used (as it is not necessary to run the SSO Connector)	Reference link
   dashlane/sso-connector:1	The image that is download from the official Docker repository that has the first (and latest) version of the package of the SSO Connector	Reference link

5. If running the command resulted in the SSO Connector running successfully, go on to the "Successful SSO Connector set up" section just below. Otherwise skip to the "Troubleshooting the SSO Connector" section below. A successful output will look similar to:

If in the future, you need to update the SSL Certificate, follow the steps below for maintaining and upgrading the SSO Connector. Make sure to use the new SSL Certificate and Private Key when running the set up instruction again. 

Successful SSO Connector set up

Downloading the SAML metadata of the SSO Connector

Once the SSO Connector is successfully running, you will be able to download the SSO Connector's SAML metadata. The link should be shown in the output, and will have the following format:

https://{SSO connector endpoint}/saml/.

You will need this to configure your identity provider. Navigating to the metadata URL will download the metadata file.

You can now return to the remaining portion of the setup guide for your identity provider.

Advanced option: Running multiple instances for high availability and scalability

The architecture of the SSO Connector is stateless. Multiple instances can be initiated to make the service highly available, and if needed, to increase its capacity.

In order to run more instances of the SSO Connector, you simply need to deploy the Docker image on a different machine and ensure that the SSO Connector Key within the config file is the same across all instances.

The SSO Connector key should have been securely saved after first generated at the time of deploying the first instance of the SSO Connector. If the key was not saved, you may be able to find the key in the config file downloaded during the set up of the first instance. If the initial config file is also not available, it will not be possible to create more instances of the SSO Connector.

Maintaining and upgrading the SSO Connector

We will continue to make updates to the SSO Connector. To ensure you get the latest updates, you will need to pull the latest image from the Docker hub, stop the running instance, remove it, and run the instance again. We recommend doing this once a month.

To upgrade the Docker image, run the following command:

docker pull dashlane/sso-connector

Run the following command to stop the container:

docker stop $(docker ps -a --filter "name=dashlane-sso-connector")

Run the following to remove the existing container:

docker rm $(docker ps -a --filter "name=dashlane-sso-connector")

Re-run the container for the configuration you have by following the set up steps, and this will now use the latest image. 

• Setup the SSO connector with a load balancer or proxy
• Setup the SSO connector with no load balancer or proxy

Troubleshooting the SSO Connector

Permission denied

Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.40/containers/json: dial unix /var/run/docker.sock: connect: permission denied

You need to elevate to admin to run the docker command. Add sudo before the command.

sudo docker <rest of the command>

Container in use

docker: Error response from daemon: Conflict. The container name "/dashlane-sso-connector" is already in use by container "container_id". You have to remove (or rename) that container to be able to reuse that name.

The container should first be stopped and then removed. You can use the following command to stop the container:

docker stop $(docker ps -a --filter "name=dashlane-sso-connector")

Run the following to remove the existing container:

docker rm $(docker ps -a --filter "name=dashlane-sso-connector")

Error codes