Based on Debian 11 "Bullseye" environment.
This article will be updated to Debian 11 version.
These configuration examples are based on the article "Use nginx to Add Authentication to Any Application" with some updates and additionals.
In this way, you can enable the OpenID Connect (OIDC) authentication with NGINX and Vouch Proxy. You don't need to implement the login mechanism to each application running behind the NGINX reverse proxy. In addition, user management can be completed in the ID management provider side (not within each application).
Vouch Proxy is compatible with many kinds of ID providers, such as GitHub and Google. This page will help you work with such providers.
Please have a look at the official examples.
Okta offers the developer account for testing (free of charge up to 1,000 monthly active users). Visit developer.okta.com to start testing with this account.
The application should be set up according to the blog post.
The easiest way to start Vouch Proxy is the docker image. To use the image, you'd better use NGINX as a reverse proxy.
Make a site configuration in /etc/nginx/sites-available and enable it. This will work as a reverse proxy to pass the connection to Vouch Proxy
Make /etc/vouch/config directory and store the following sample. This is based on the config example on the official site.
(keep the filename as config.yml)
Pull the docker image and run it with the prepared config file.
# docker run -d -p 9090:9090 --name vouch-proxy -v /etc/vouch/config:/config voucher/vouch-proxy
Once the image is started with the command above, the image can be handled with the name "vouch-proxy"
# docker stop vouch-proxy # docker start vouch-proxy
If you change config.yml, then you need to restart the image to reload it.
When you want to upgrade, remove the image before pulling the latest docker image.
# docker rm vouch-proxy # docker rmi voucher/vouch-proxy
Then redo the initial docker run command above to pull the latest image and run.
Set the NGINX as a reverse proxy, and let it redirect to the Vouch Proxy using the auth_request module.
To reuse in the multiple sites, prepare a snippet in /etc/nginx/snippets
Set up a site for "app.example.com" in /etc/nginx/sites-available
Reload NGINX to enable the site configurations.
# systemctl reload nginx
There should be some hints on the logs.
NGINX logs are located in /var/log/nginx/
Vouch Proxy logs are available with the following command.
# docker logs vouch-proxy
The default configuration offers to specify the domains. Here is the difference.
Specifying the domains.
With the above situation, the configuration should look like as below.
vouch: domains: - example.com - example.jp
If the users' mail addresses have a variety of domains, you have to list up all of them to permit the access.
This can be used to restrict the users with the specific mail domains by extracting them in the configuration, but that kind of management should be controlled in the OIDC provider side.
Instead of listing the domains, use "allowAllUsers: true" to accept anybody who is allowed in the OIDC provider side.
Even if you prefer this type, you still need to specify which domain to be used for the cookies. This will be the domain to be protected, i.e. callback and application domain.
vouch: allowAllUsers: true cookie: domain: example.com
With the configuration explained in this page, any access will be checked. This means the batch jobs from the localhost will be redirected to the check.
For example, if a cronjob accesses the protected site with the headless chromium, it will still be redirected to the authentication (and probably that job will fail).
I couldn't find the good way to set the exception of accesses on NGINX nor Vouch Proxy, this can be realized simply opening another port for the HTTPS service.
Port 443 for the any inbound HTTPS access
Port 1443 for the HTTPS only from the localhost
Both ports redirect to the backend application, but 1443 doesn't require the authentication and only available for the local loopback access.
Directly connecting to the backend port is another solution, only if the application is using the tcp port. (This is useful if the backend is running on the docker, but many native applications may be using Unix sockets...)
If you feel there are too frequent redirection to the OIDC provider, you can extend the expiration of jwt.
Extend vouch.jwt.maxAge as well as vouch.cookie.maxAge.
In my case, it's 900 minutes (15 hours) to aim for the "once a day on the business hours" frequency.
vouch: cookie: maxAge: 900 jwt: maxAge: 900