Authentication via URL Parameters

The plg_authenticate_url plugin enables user to authenticate through specially crafted URLs. Such URL includes query parameters that act as attributes, which can be mapped or transformed onto storage configuration fields. This mechanism is useful in a variety of integration scenarios, such as generating deep links, embedding QR codes, or building custom integrations where authentication details are encoded directly in the URL.

The plugin supports several verification strategies, controlled by a single configuration parameter: strategy. The available strategies are:

Passthrough strategy

In passthrough mode, URL parameters are being passed through to the attribute mapping section without any kind of verification. The simplest example would be something like this:

In this scenario, anybody who use this link: http://localhost:8334/api/session/auth/?action=redirect&label=local&chroot=/home/ will enter the local storage and be chrooted into /home/.

While passthrough mode is simple and flexible, it also means anyone could modify the URL parameters. For instance, a user could change chroot=/home/ to gain access to other places. There are 2 main ways to mitigate this, the first one is to use another strategy (either signature_hmac or signature_std) but another option is to use a URL parameter which can be verified. Here are 2 examples of the second option:

1) Example using a JWT token: we will be using this link to have a concrete example of this method: http://localhost:8334/api/session/auth/?action=redirect&label=local&jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaHJvb3QiOiIvaG9tZS8ifQ.c8X-yfgpAsCZUDT0mhkro_rqKJv5pMdkiWMs9jW7qzg and instead of the attribute mapping section to bind using {{ .chroot }}, use instead: {{ .jwt | jwt "foobar" | jq ".chroot" }} which for the given jwt token will expand to /home/ and will error out if the token was signed with something else than “foobar”

2) Example using a AES-GCM Encrypted Payload: let’s use this link as an example: http://localhost:8334/api/session/auth/?action=redirect&label=local&payload=CwlTT2yZ/PNxRqKPZ4nMEvRfR1rkOy5D1imX7as/4bs60w== which we could decrypt using in the attribute section as a path: {{ .payload | decryptGCM "foobar0000000000" }} which will expand once again to our /home/.

protip: instead of hardcoding the keys in the attribute section, inject those as environment variable using this syntax: {{ .payload | decryptGCM .ENV_CONFIG_SECRET }} where you have as enviroment variable CONFIG_SECRET=foobar0000000000

Signature via HMAC

When using the signature_hmac strategy, each authentication URL must include a signature parameter that verifies the integrity of all other URL parameters. This signature is generated using HMAC with either SHA256 or SAHA512 following this algorithm:

1. get key from either the CONFIG_SECRET env variable or a derivation of the base secret key
   => eg: test
2. get the base URL
   => eg: http://localhost:8334/api/session/auth/?action=redirect&label=local&chroot=%2Fhome%2F
3. calculate signature = HMAC(baseURL, key)
   => 410f27bfc5f218203e122e3e4f2dacd27105e5e04123b2077d94bfc04800c5c9fcbc425ceb923adf305514840c53dad76af087946c1688df67537b56786f6bf5

If you set CONFIG_SECRET=test, the generated URL for our use case will be: http://localhost:8334/api/session/auth/?action=redirect&label=local&chroot=/home/&signature=410f27bfc5f…..88df67537b56786f6bf5

Signature via AES GCM

This is a variant of signature_hmac but instead of using HMAC, signature is calculated following this algorithm:

1. generate a string from the list of attribute, in our case "chroot[/home/]"
2. compress the string from 1 using zlib (to make it more space efficient)
3. encrypt the payload from 2 using AES GCM using as a key a derivate of the SECRET_KEY
   fyi: secret key is what is set in the settings pannel of the admin console
   the derivated key is calculated using SHA256("PLG_AUTHENTICATE_URL_"+SECRET_KEY)

We have various CLI tools running this, reach out to support if you need help with this method.