Deploy and Host Authelia on Railway

Built for an LLM agent to deploy and use. There is no setup wizard and nothing to fill in: the admin password, the OIDC client secret and every Authelia secret are generated at deploy time, the admin user and one OIDC client exist from the first boot, and the contract below lists every URL, variable name and the one script that proves it works.

Authelia is an open-source (Apache 2.0) single sign-on and authorization server. It puts a login portal in front of web apps through forward-auth and auth-request (Traefik, Caddy, nginx, Envoy), and it is a certified OpenID Connect 1.0 provider for apps that speak OIDC. Machines authenticate with a bearer token from the client_credentials grant, so an agent can pass the same gate a person does.

About Hosting Authelia

This template runs one service, the official Authelia 4.39.28 image (ghcr.io/authelia/authelia, pinned by digest), with a volume at /config. On every boot the start command writes /config/configuration.yml from the service variables, so the config never drifts from them. The volume keeps the users file (users_database.yml), the SQLite database (sessions, OIDC state), the OIDC signing key and the filesystem notifier file (notification.txt, where password-reset and device-enrolment links are written because no mail server is attached). The first boot creates the user admin (group admins, password from ADMIN_PASSWORD) and the OIDC client agent (grant client_credentials, scope authelia.bearer.authz, secret from OIDC_CLIENT_SECRET, audience https://PUBLIC_DOMAIN/). The default access policy is one_factor. Allow about a minute for the first deploy to turn healthy.

Drop extra Authelia YAML files into /config/conf.d: they are merged over the generated config on every boot, which is where access-control rules, more OIDC clients, an SMTP notifier or an LDAP backend go. The generated config sets the cookie domain to the public domain of the service; to protect apps on your own domain, override session.cookies there.

Agent contract

Public URL: https:// plus the RAILWAY_PUBLIC_DOMAIN of the authelia service, also published as the variable AUTH_PUBLIC_URL; used below as AUTH_URL. The login portal is at /, the OIDC issuer is AUTH_URL itself with discovery at /.well-known/openid-configuration.
Private URL: http://authelia.railway.internal:8080 (also the variable AUTH_PRIVATE_URL), for forward-auth and auth-request calls from other services in the project
Credentials: ADMIN_PASSWORD (user admin) and OIDC_CLIENT_SECRET (client id agent). Both stay the same across redeploys.
Auth: the portal login is POST /api/firstfactor with JSON username and password. API clients use HTTP basic auth agent:$OIDC_CLIENT_SECRET on POST /api/oidc/token with grant_type=client_credentials, scope=authelia.bearer.authz and audience=$AUTH_URL/ (the audience must equal the resource being accessed, with the trailing slash), then present Authorization: Bearer $TOKEN to the protected route. A request with no or a bad token is redirected to the portal (302).
Health: GET /api/health returns 200 with no credentials

# run with AUTH_URL, ADMIN_PASSWORD and OIDC_CLIENT_SECRET set
FA="-H X-Forwarded-Proto:https -H X-Forwarded-Host:${AUTH_URL#https://} -H X-Forwarded-URI:/ -H X-Forwarded-Method:GET"
curl -s -o /dev/null -w 'health %{http_code}\n' "$AUTH_URL/api/health"
curl -s -o /dev/null -w 'admin-login %{http_code}\n' -X POST -H 'Content-Type: application/json' -d "{\"username\":\"admin\",\"password\":\"$ADMIN_PASSWORD\"}" "$AUTH_URL/api/firstfactor"
curl -s -o /dev/null -w 'wrong-password %{http_code}\n' -X POST -H 'Content-Type: application/json' -d '{"username":"admin","password":"wrong"}' "$AUTH_URL/api/firstfactor"
TOKEN=$(curl -s -u "agent:$OIDC_CLIENT_SECRET" -d grant_type=client_credentials -d scope=authelia.bearer.authz -d "audience=$AUTH_URL/" "$AUTH_URL/api/oidc/token" | sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p')
echo "token ${#TOKEN} chars"
curl -s -u "agent:$OIDC_CLIENT_SECRET" -d "token=$TOKEN" "$AUTH_URL/api/oidc/introspection" | grep -o '"active":true'
curl -s -o /dev/null -w 'forward-auth-with-token %{http_code}\n' -H "Authorization: Bearer $TOKEN" $FA "$AUTH_URL/api/authz/forward-auth"
curl -s -o /dev/null -w 'forward-auth-no-token %{http_code}\n' $FA "$AUTH_URL/api/authz/forward-auth"
curl -s "$AUTH_URL/.well-known/openid-configuration" | grep -o '"issuer":"[^"]*"'

A fresh deploy prints health 200, admin-login 200, wrong-password 401, a token length above zero, "active":true, forward-auth-with-token 200, forward-auth-no-token 302 and the issuer equal to AUTH_URL. In a reverse proxy, point forward-auth at http://authelia.railway.internal:8080/api/authz/forward-auth (Traefik forwardAuth, Caddy forward_auth) or /api/authz/auth-request (nginx auth_request).

Why Deploy Authelia on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Authelia on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Agent-ready - generated admin password and OIDC client secret, a contract block and one working script; no wizard before the first login or token.
OIDC and forward-auth in one service - the same server signs people in at the portal and issues bearer tokens to machines.
Login works from boot - the admin user and the agent client exist before the first request.
State survives redeploys - users, sessions, OIDC state and the signing key sit on a volume, so issued tokens stay valid.
Extendable - YAML dropped in /config/conf.d is merged on every boot.
Pinned image - pinned by digest, so a redeploy never changes the server version underneath you.

Common Use Cases

Single sign-on for self-hosted apps - put one login in front of dashboards and tools through a reverse proxy.
OpenID Connect provider - sign in to Grafana, Gitea, Nextcloud, Outline and any OIDC-capable app with one account.
Machine-to-machine access - give an AI agent a client_credentials token to pass the same gate as a user.

Dependencies for Authelia Hosting

Nothing else: Authelia keeps users, sessions and OIDC state in SQLite on the volume at /config.

Deployment Dependencies

authelia/authelia - upstream project
Authelia documentation - access control, OIDC clients and proxy integration