Add documentation for authentication

[Thomvh]

Is your feature request related to a problem? Please describe.
I can't figure out how the authentication setup for the web interface works.

Describe the solution you'd like
A little explanation/documentation about how the authentication mechanism works.

[cottley]

Not documentation, but I wrote a front end for this at https://github.com/cottley/wgui-front that uses a forked version of wg-ui.

[dmitrydvornichenko]

If someone is interersted in integrating this product with oauth2, this proxy works perfect with wg-ui just from the box.

[suom1]

If someone is interersted in integrating this product with oauth2, this proxy works perfect with wg-ui just from the box.

Pretty sure this is what we use also in our setup, might be worth writing a guide how to integrate these!

[dmitrydvornichenko]

Here is my ansible role for creating wg-ui container and populating config.json from vars/main.yml file, then creating oauth2 proxy container for the authentication. I think it might be useful for someone.
wgui.zip

[theseal]

This is a write-up how Stockholm University protected our Wireguard UI with a Shibboleth SP and Apache httpd. I will not cover how to configure shibd or the IdP part of this integration.

The Univerity is heavly in to Single sign-on and SAML so shibd is one of the more common tools we have and use. Together with apache it's easy to create SSO for application that can't speak native SAML. The combination shibd and apache handles all the authentication and in this case even a rough authorization (more on that later) and proxies the request to the service.

Most SAML attributes in the .edu world are based on LDAP attributes. eduPersonPrincipalName (or eppn as Shibboleth calls it) is our primary key to identify users so that is released from the IdP to the SP as a SAML attribute and then forward/proxied as request header to the application. The only thing that needs to be configured in the Wireguard UI end is that the application needs to be started with the --auth-user-header flag set to eppn.

The apache configuration

<VirtualHost *:443>
    <LocationMatch "/">
        AuthType Shibboleth
        Require shib-attr entitlement ~ ^urn:mace:swami.se:gmai:vpn:user$
        ShibRequireSessionWith idp.example.com
        ShibUseHeaders On
    </LocationMatch>

    SSLCertificateFile    /path/to/vpn.example.com.pem
    SSLCertificateKeyFile /path/to/vpn.example.com.key
    SSLCertificateChainFile /path/to/DigiCertCA-2024-11-18.crt

    ProxyPass "/" "http://127.0.0.1:8080/"
    ProxyPassReverse "/" "http://127.0.0.1:8080/"
</VirtualHost>

Configuration in depth

Require shib-attr entitlement ~ ^urn:mace:swami.se:gmai:su-vpn:user$

We have alot of users at the University and not all of them are eligible to use Wireguard UI. By default apache and shibd lets everyone through and since Wireguard UI has no knowlege about the user in beforehand we release another (eduPersonEntitlement) from the IdP to the SP and require a specific value on the user in order to be allowed to use the service.

ShibUseHeaders On

This enables shibd to publish SAML attributes to the application (in our case proxy) through request headers.

---

Thats is! I hope it could be useful someone else. The setup works flawless and big thanks to EmbarkStudios for a great application.

[suom1]

@theseal Awesome stuff, if you want you could create a PR with this documentation and create doc/auth-shibboleth.md. That way we will have this in a place which is much easier to find. If you feel that you don't have time, and you're fine with me doing that for you, it's fine for me! :)

I can then also create similar documentation for our Google SAML we use at Embark!

[theseal]

If you start with creating your documentation I can convert mine in to something matching for Shibboleth.

[suom1]

I have now added documentation for Google SSO with #79 :)

[theseal]

Did my part of the deal #80 👍

[suom1]

Awesome stuff, it's merged!