What is the use of vars handler in forward_auth?

1. The problem I’m having:

I don’t have any problems, I just have a question.

I am using Caddy with Authelia for authentication/authorization. My config is included below.

In this setup with Authelia, The authentication succeeds and authelia sends a 2xx response. Without the vars handler in handle_response`, Caddy does not forward the request to the actual service and the browser shows a page with just “200 OK” message.

With the vars handler added, every thing works fine.

I read the documentation of vars handler and it’s for accessing parameters on http.vars but in the generated forward auth config, It does not use these parameters anywhere so why is this needed ?

2. Error messages and/or full log output:

3. Caddy version:

v2.9.1

4. How I installed and ran Caddy:

Built with xcaddy running on debian with systemd

a. System environment:

Debian Bookworm

b. Command:

caddy run --config caddy.json

c. Service/unit/compose file:

d. My complete Caddy config:

nextcloud.example.com {
        forward_auth authelia:9091 {
                uri /api/authz/forward-auth
                ## The following commented line is for configuring the Authelia URL in the proxy. We strongly suggest
                ## this is configured in the Session Cookies section of the Authelia configuration.
                # uri /api/authz/forward-auth?authelia_url=https://auth.example.com/
                copy_headers Remote-User
        }

        reverse_proxy nextcloud:80
}

In JSON, It looks like this

{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [
            ":443"
          ],
          "routes": [
            {
              "match": [
                {
                  "host": [
                    "nextcloud.example.com"
                  ]
                }
              ],
              "handle": [
                {
                  "handler": "subroute",
                  "routes": [
                    {
                      "handle": [
                        {
                          "handle_response": [
                            {
                              "match": {
                                "status_code": [
                                  2
                                ]
                              },
                              "routes": [
                                {
                                  "handle": [
                                    {
                                      "handler": "vars"
                                    }
                                  ]
                                },
                                {
                                  "handle": [
                                    {
                                      "handler": "headers",
                                      "request": {
                                        "set": {
                                          "Remote-User": [
                                            "{http.reverse_proxy.header.Remote-User}"
                                          ]
                                        }
                                      }
                                    }
                                  ],
                                  "match": [
                                    {
                                      "not": [
                                        {
                                          "vars": {
                                            "{http.reverse_proxy.header.Remote-User}": [
                                              ""
                                            ]
                                          }
                                        }
                                      ]
                                    }
                                  ]
                                }
                              ]
                            }
                          ],
                          "handler": "reverse_proxy",
                          "headers": {
                            "request": {
                              "set": {
                                "X-Forwarded-Method": [
                                  "{http.request.method}"
                                ],
                                "X-Forwarded-Uri": [
                                  "{http.request.uri}"
                                ]
                              }
                            }
                          },
                          "rewrite": {
                            "method": "GET",
                            "uri": "/api/authz/forward-auth"
                          },
                          "upstreams": [
                            {
                              "dial": "authelia:9091"
                            }
                          ]
                        },
                        {
                          "handler": "reverse_proxy",
                          "upstreams": [
                            {
                              "dial": "nextcloud:80"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ],
              "terminal": true
            }
          ]
        }
      }
    }
  }
}

5. Links to relevant resources:

I’m sure you know more about Authelia than I do, because I had to do some research before typing this.

My limited understanding is that Authelia authenticates the user and sends a 2xx response with the Remote-User header. vars sets one or more variables to a particular value, to be used later in the request handling chain. So because Authelia sends Remote-User, Caddy needs to see that, and it does so by adding it to the HTTP header.

I don’t think the vars handler directly uses http.vars in its configuration. It’s the reverse_proxy that implicitly uses the headers captured by vars when forwarding the request.