📘

Note: The Foxpass Cache is an add-on feature

To enable this feature, contact us at [email protected]. Once the add-on is enabled, we will create a Jfrog account for accessing the Foxpass cache docker image and send the credentials to you.

Overview

Foxpass provides SaaS-based access control to your infrastructure. We offer cloud hosted LDAP, RADIUS, and SSH key management. Our availability record is impressive, but, like any cloud service provider, we are not immune to downtime. We offer a local caching server for Foxpass that helps ensure that you will never be locked out when downtime happens or your systems have trouble reaching our servers. We distribute the cache as a Docker image that’s easy to setup and configure. As with any Docker image, there are no external dependencies. Just download and run!

📘

Cache is LDAP-only

Currently the cache supports LDAP only. We hope to add RADIUS support soon.

Prerequisites

The only requirement is a working installation of Docker. If you do not have Docker yet, you can install it by following the guide here:

https://docs.docker.com/engine/installation

Server Installation Guide

These steps detail how to install and run the Foxpass cache on one of your servers. Instructions for how to configure your hosts and other endpoints to integrate with the cache are here.

1. Generate a cache key

Visit this page and click “Add Cache Key”.

The cache container uses this cache key as an authentication mechanism when syncing with the Foxpass servers. This key can be used in as many containers as you want, but each key is rate limited, meaning that it has a finite amount of syncs over a preset span of time. You can generate a maximum of 2 keys for ease of use when you want to transition to a new key.

2. Pull the Foxpass Cache Image

Go to the host you’d like to run the cache on, and use Docker to pull the Foxpass Cache image:

docker pull foxpass.jfrog.io/foxpass/foxpass-cache

3. Run the container

docker run -d -p 389:389 -p 80:80 foxpass.jfrog.io/foxpass/foxpass-cache --cache-key <YOUR CACHE KEY> --cache-name <CACHE NAME>

This will run the Foxpass cache, listening on 389 for LDAP requests and 80 for SSH key requests.

The cache can run on its own, without any special keys or certs, but this mode should be used for testing. Without a key and cert, the cache exposes LDAP and HTTP endpoints as opposed to the secure and encrypted LDAPS, LDAP+STARTTLS, and HTTPS endpoints. Passwords and data will be sent in plaintext over LDAP and HTTP, so if someone was listening to the traffic between your clients and the cache they would be able to read the data unencrypted. It is highly recommended that you enable SSL and the more secure endpoints by mapping a certificate file and key to the Docker container. You can specify the mapping of these files from the Docker file system to the cache system by using the -c and -k arguments.

docker run -d -p 389:389 -p 443:443 -p 636:636 -v $PWD/mycert.cer:/cert.crt -v $PWD/mykey.pem:/key.pem foxpass.jfrog.io/foxpass/foxpass-cache --ldap-starttls-port 389 --ldaps-port 636 --https-port 443 -c /cert.crt -k /key.pem --cache-key <YOUR CACHE KEY> --cache-name <CACHE NAME>

The -v arguments map the cert and key from the server's filesystem to the Docker container, and the -c and -k arguments let the Foxpass process know where those files are within the container.

Command Line Options

Detailed port mapping explanation

If no port options are specified and no cert and key are provided, the cache server will run LDAP on port 389 and HTTP on port 80.

If no port options are specified but a key and certificate file are, the cache server will run LDAP+STARTTLS on port 389, LDAPS on port 636 and HTTPS on port 443.

If you would like to specify a specific port for a certain service, refer to the command line options table.

4. Check the cache status

Once your cache is up and running, it will automatically sync with Foxpass’s servers. You can see the status of that sync and more information about the cache on the 'Cache' page.

Third-Party Configuration

If your Foxpass account has enabled delegation authentication to Okta, the cache will send authentication requests to Okta directly. If you have MFA enabled in Okta, you will need to add an MFA exemption for the public IP address (or address of the NAT device) in your Okta account.