vestibule

README

Vestibule

** VESTIBULE IS BEING DEPRECATED AND SOON WILL NO LONGER BE MAINTAINED - PLEASE MIGRATE TO ATRIUM (https://github.com/nicolaspernoud/atrium) **

Alternate URL (on the Grand Lyon software forge) : https://forge.grandlyon.com/NPERNOUD/vestibule .

Vestibule is an HTTP server, reverse proxy and webdav server, with OIDC/OAuth2 and local users file authentication, and a Single Page Application GUI to configure everything.

Features

• Reverse proxy any website (internal or external), with GUI configuration
• Authenticate users against OIDC/OAuth2 server and fetch user roles based on /userinfo endpoint
• Expose any file system directory as webdav server with web explorer
• Allow opening and saving of documents with onlyoffice integration
• Automatic let's encrypt https

Screenshots

How does it works ?

Vestibules authenticates the users against a local user.json file or an OIDC/OAuth2 provider (with Open Id Connect userinfo endpoint). It issues an encrypted cookie for the global domain (say vestibule.io) containing the user roles gotten from the local user database or the "memberOf" claim of the OIDC/OAuth2 user gotten from the userinfo endpoint.

After, for every access to a proxied application or a webdav service (say myapp.vestibule.io), it checks the cookie to allow users based on their roles.

Applications and davs can be opened to everyone as well (no authentication).

Vestibule creates a subdomain for every services (apps and davs) and provide Let's encrypt certificates automatically.

Installation

Locally

Clone the repository. Alter the .env file with your configuration. Launch start.sh.

With docker

Alter .env and docker-compose.yml according to your needs. Launch with COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker-compose up. A production deployment example is also provided in the production-deployment-example.sh file. The mock ip geodatabase should be replaced with a real one from maxmind for real usefullness.

Usage

Configuration

Configuration is done through environment variables. The meaning of the different environment variables is detailed here :

Environment variable	Usage	Default
HOSTNAME	Vestibule main hostname : needed to know when to respond with the main GUI instead of an application on a webdav service	vestibule.127.0.0.1.nip.io
APPS_FILE	Apps configuration file path	"./configs/davs.json"
DAVS_FILE	Davs configuration file path	"./configs/davs.json"
LETS_CACHE_DIR	Let's Encrypt cache directory	"./letsencrypt_cache"
LOG_FILE	Optional file to log to	defaults to no file logging
HTTPS_PORT	HTTPS port to serve on	443
HTTP_PORT	HTTP port to serve on, only used for Let's Encrypt HTTP Challenge	80
DEBUG_MODE	Debug mode, disable Let's Encrypt, enable CORS and more logging	false
ADMIN_ROLE	Admin role	ADMINS
REDIRECT_URL	Redirect url used by the idp to handle the callback
CLIENT_ID	Client id to authenticate with the IdP for OAuth2 authentication
CLIENT_SECRET	Client id to authenticate with the IdP for OAuth2 authentication
AUTH_URL	IdP's authentication URL
TOKEN_URL	IdP's token URL
USERINFO_URL	IdP's userinfo URL
ISSUER	IdP's issuer for autoconfiguration of AUTH_URL, TOKEN_URL, USERINFO_URL if they are not already set
LOGOUT_URL	IdP's logout URL
ONLYOFFICE_TITLE	Title used on the OnlyOffice document editor window	VestibuleOffice
ONLYOFFICE_SERVER	Url of the OnlyOffice document server used to edit documents
INMEMORY_TOKEN_LIFE_DAYS	Lifetime of authentication tokens for local users	1
DISABLE_LETSENCRYPT	Disable Let's Encrypt certificates (in normal mode) and use development certificates (./dev_certificates/localhost.crt and .key) instead	false (true if HOSTNAME is not set)

OIDC/OAuth2 configuration

The OIDC/OAuth2 provider is configured with environment variables. The user is recovered with the /userinfo endpoint (part of the Open Id Connect standard) with a standard OAuth2 dance. Vestibule is compatible with most OpenIdConnect providers (including Keycloak), or OAuth2 providers with the /userinfo endpoint.

The users roles must be recovered in an "memberOf" claim array obtained when accessing the /userinfo endpoint. It can be configured to map any group/role configuration on most IdPs.

Mounting webdav share on your OS

Vestibule allow using the login with the password OR the authentication token in an basic auth header to allow mounting webdavs.

Override branding

Every branding asset is in web/assets/brand directory. They can be altered according to your needs.

Development

Update dependencies

go get -u -t ./...
go mod tidy

Register both remotes

git remote add forge https://forge.grandlyon.com/NPERNOUD/vestibule.git
git remote set-url --add --push origin https://forge.grandlyon.com/NPERNOUD/vestibule.git
git remote set-url --add --push origin https://github.com/nicolaspernoud/Vestibule.git

Get all branches

git fetch --all

## Update master from development and set development to follow master

git checkout master
git merge development --squash
# Alter commit message and commit
git checkout development
git reset --hard master

Credits

Loosely based on Webfront (https://github.com/nf/webfront), by Andrew Gerrand, Google (Apache License, Version 2.0).

Uses :

• Bulma : https://bulma.io/, https://github.com/jgthms/bulma (MIT Licence)
• Animate.css : https://daneden.github.io/animate.css/, https://github.com/daneden/animate.css (MIT Licence)
• Font Awesome : https://fontawesome.com, https://github.com/FortAwesome/Font-Awesome (Font Awesome Free License)
• Secure IO : https://secure-io.org, https://github.com/secure-io/sio-go (MIT Licence), lots of thanks to @aead (Andreas Auernhammer) who has been a great help in understanding the library and for his cryptography insights
• MaxMind DB Reader for Go : https://github.com/oschwald/maxminddb-golang (ISC License)
• HTTP Cache by Victor Springer : https://github.com/victorspringer/http-cache (MIT Licence), parts are included in pkg/cache directory (to avoid getting unwanted redis dependencies)
• Go-Glob by Ryan Uber : https://github.com/ryanuber/go-glob (MIT Licence)
• go-disk-usage by ricochet2200 : https://github.com/ricochet2200/go-disk-usage (The Unlicense)

Licence

The product is licenced under GNU AFFERO GENERAL PUBLIC LICENSE Version 3, it is made primarily by Nicolas Pernoud, a member of Métropole de Lyon, on professional time (some), and personal time (most). It is used on Métropole de Lyon "alpha" lab to allow quick prototyping and proof of concepts.

Beeing part of the project

Contributions of any kind welcome!