Webfingo: Webfinger in Go for Keycloak

Webfingo: Webfinger in Go for Keycloak

Webfingo is a webfinger utility written in Go. I created it because Tailscale needs a webfinger endpoint to integrate with OIDC providers.

Webfingo Motivation

I want to use Tailscale, the network overlay. For this, I need an identity provider to authenticate. I have chosen Keycloak, the open source OIDC system.

Tailscale needs a webfinger endpoint at /.well-known/webfinger that it can use to get a ‘realm’ from Keycloak, for a given user email. Keycloak doesn’t provide this.

Some users have a local file server or hard-coded Caddy reverse proxy configuration, to provide the required JSON response for a small number of users. I preferred to get the necessary data out of Keycloak’s database and provide a dynamic endpoint.

Building Webfingo

My Webfingo endpoint is written in Go. It provides a basic webserver, and receives webfinger queries. It goes into the Keycloak database, looking for information about the user. If the email address is found, Webfingo responds with the user’s realm.

The relevant SQL to inspect Keycloak’s DB looks like this:

SELECT u.id, u.email, u.username, u.realm_id, r.name as realm_name
FROM user_entity u
INNER JOIN realm r ON u.realm_id = r.id
WHERE u.email = $1
LIMIT 1

My Keycloak instance is using Postgres.

Deploying Webfingo

Systemd

To deploy this service and keep it running, I’m using systemd. I wrote a config like this:

[Unit]
Description=Webfingo: Webfinger Responses for Keycloak
After=network.target

[Service]
Type=simple
User=webfingo
Group=webfingo
WorkingDirectory=/opt/webfingo/
ExecStart=/usr/bin/webfingo --config /opt/webfingo/config.json
Restart=always

[Install]
WantedBy=multi-user.target

Caddy

The basic Caddyfile setup initially looked a little like this:

https://example.com {

        handle /.well-known/webfinger {
                reverse_proxy http://localhost:8123 {
                        header_up Host {host}
                        header_up X-Real-IP {remote}
                        header_up X-Forwarded-For {remote}
                        header_up X-Forwarded-Proto {scheme}
                }
        }

        handle {
                respond "404 Not Found" 404
        }

        handle_errors {
                respond "{http.error.status_code} {http.error.status_text}" {http.error.status_code}
        }
}

I then added further functionality:

• Caddy handles the TLS certs, using a security token to authenticate with Cloudflare and make the necessary DNS changes
• Added rolling logfile
• Coraza web application firewall

Summary

Webfingo is now handing webfinger requests sent from Tailscale to my Keycloak server. After further testing and securing, it will be part of the toolchain that provides authentication for my secure network overlay.