Add login and SSO to your app with Keycloak on Railway
Short answer: to add login and single sign-on to your app with a server you control, deploy an identity provider such as Keycloak and have your app sign users in through OpenID Connect or SAML. The Tracklayer template runs Keycloak 26 on Railway with Postgres, an optimized build and a generated admin password, so your users, realms and sessions stay in your own database.
Deploy Keycloak on RailwayWhen this makes sense
Hosted login services are quick to start, but you may want users and credentials in your own Postgres, or one login across several internal tools. Per the template documentation, Keycloak is used for:
- single sign-on for internal tools, dashboards and SaaS products over OpenID Connect or SAML,
- social login (Google, GitHub, Microsoft) and federation with LDAP, Active Directory or external identity providers,
- protecting APIs with OAuth 2.0 access tokens,
- multi-factor authentication (OTP, WebAuthn and passkeys) in front of existing apps.
Keycloak is a full identity server, so it is heavier than a login library inside your app. If you only need simple email-and-password login for one app, a library may be enough.
Authentication templates people deploy on Railway
| Template | Creator | Deployments | Services |
|---|---|---|---|
| Keycloak | beuz's Projects | 754 | 2 |
| Authorizer | Lakhan Samani's Projects | 652 | 3 |
| Authorizer | Lakhan Samani's Projects | 622 | 2 |
| Keycloak 26 Identity and SSO Server | Tracklayer | 1 | 2 |
Railway marketplace data as of 2026-11-19. Full ranking: Best authentication and SSO templates on Railway.
Deploy Keycloak, step by step
These steps use Tracklayer’s Keycloak 26 Identity and SSO Server template.
- Pick the Hobby plan or higher. The template names Hobby as the minimum. On Trial, each service has 1 GB and the template sizes the Java heap to 640 MB, which leaves little room.
- Deploy the template. It creates Keycloak 26.8.1 (an optimized build, started with
start --optimized) and Postgres 18 with a volume. The hostname comes from Railway’s public domain. - Wait for the first start. Keycloak creates its database schema, which takes one to three minutes.
- Open the admin console. Go to
https://<your-domain>/adminand sign in asadminwithKC_BOOTSTRAP_ADMIN_PASSWORDfrom the Keycloak service’s Variables tab. No setup page is exposed. - Replace the temporary admin. Create a permanent admin in the master realm (Users, then Role mapping:
admin), sign in with it, delete the temporary account, and turn on OTP and brute-force detection for the master realm. - Create a separate realm for your applications. Keep the master realm for administration.
Connect your app
Your app needs the realm’s issuer URL: https://<your-domain>/realms/<realm>. Register your app as a client in that realm using Keycloak’s documentation, and give your OpenID Connect or SAML library the issuer or discovery URL.
Apps in the same Railway project can call http://keycloak.railway.internal:8080/realms/<realm> for discovery, tokens and keys over the private network. Browser redirects always use the public domain.
Railway’s healthcheck uses /health/ready, so the /health endpoints answer on the public domain too, showing status only. Prometheus metrics stay on the private port: http://keycloak.railway.internal:9000/metrics.
What it costs
Railway bills usage, so cost follows memory and CPU. The template’s figures are estimates, not measurements: they are based on Keycloak’s sizing guidance, the template’s heap settings and typical Postgres idle use. The template estimates about 0.8 GB of RAM in total at idle and about $9 a month, and about 1.35 GB and $17 a month for a few apps with hundreds of daily logins. Three replicas with the clustered cache are estimated at about $45 to $50 a month. The Java heap is capped by default at 1024 MB (JVM_HEAP_MAX_MB), so raise it together with the service’s resources for large installations.
Scaling and upgrades
The template runs one replica with local caches. Sessions live in Postgres, so restarts do not log users out. For several replicas, set KC_CACHE=ispn first. Keep KC_DB_POOL_MAX_SIZE times the number of replicas below Postgres’ 100 connections.
To upgrade, back up Postgres, change KEYCLOAK_VERSION and deploy.
Limitations and licence notes
- Email needs Railway Pro. Password reset and email verification use SMTP, which Railway allows only on Pro.
- Clustering is untested. The template’s notes say the multi-replica setup on Railway has not been tested.
- Client IPs. Railway does not publish its edge IP ranges, so the template does not set trusted proxy addresses. Per its notes, clients that reach port 8080 directly from inside your project could forge
X-Forwarded-For, which affects logged IPs and brute-force counters. - Admin recovery. If all admins are lost, recovery needs a one-off
kc.sh bootstrap-adminrun against the same database. The template does not script it. - Licence. Keycloak is Apache License 2.0. This is a community template, not affiliated with the Keycloak project. Identity servers hold sensitive data, so review your own security and compliance needs.
Other options
Compare more identity servers in the ranking of authentication templates on Railway, or browse all guides. If you want a login service bundled with a Postgres backend for an app, see the backend guide.
FAQ
How do I sign in to Keycloak for the first time?
Wait until the deployment is healthy, which takes one to three minutes on first start. Open https://<your-domain>/admin and sign in with KC_BOOTSTRAP_ADMIN_USERNAME (default admin) and the generated KC_BOOTSTRAP_ADMIN_PASSWORD from the Keycloak service's Variables tab. Keycloak marks this account as temporary, so create a permanent admin in the master realm and delete the temporary one.
Why do password reset and email verification not work?
Keycloak sends email over SMTP only, configured per realm under Realm settings, Email. Railway allows outbound SMTP on the Pro plan. On other plans these emails will not work until you upgrade or use a relay that is reachable from Railway.
Are users logged out when Keycloak restarts?
No. Sessions are stored in Postgres. The template runs one replica with local caches (KC_CACHE=local). Never run more than one replica in that mode; set KC_CACHE=ispn first if you want several.
How do I upgrade Keycloak?
The version is the KEYCLOAK_VERSION variable, default 26.8.1, used as a build argument. Back up Postgres, change the value and deploy. Keycloak migrates the schema on start.
What is the licence?
Per the template's NOTICE file, Keycloak is Apache License 2.0. The base image also contains Red Hat UBI 9 micro and OpenJDK 21 under their own terms. The template is a community template and is not affiliated with the Keycloak project.