Add login and SSO to your app with Keycloak on Railway

By Tracklayer · Updated 2026-11-20

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 Railway

When 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:

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

TemplateCreatorDeploymentsServices
Keycloakbeuz's Projects7542
AuthorizerLakhan Samani's Projects6523
AuthorizerLakhan Samani's Projects6222
Keycloak 26 Identity and SSO ServerTracklayer12

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.

  1. 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.
  2. 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.
  3. Wait for the first start. Keycloak creates its database schema, which takes one to three minutes.
  4. Open the admin console. Go to https://<your-domain>/admin and sign in as admin with KC_BOOTSTRAP_ADMIN_PASSWORD from the Keycloak service’s Variables tab. No setup page is exposed.
  5. 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.
  6. 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

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.