Collect the SSH username, server domain, SSH port, private key, and optional key passphrase.
ssh -p 22 user@keycloak.example.comDIRECT DEVICE-TO-SERVER ACCESS
Your server.
Your key.
No relay.
Use the native Android app to open your Keycloak administration console through SSH. This field guide helps identify the right ports, verify trust, and troubleshoot safely.
01 / PRE-FLIGHT
Six checks to reach admin
Run one of these on your server. The service port is separate from the SSH port.
sudo ss -lntp
docker ps --format 'table {{.Names}}\t{{.Ports}}'
sudo systemctl status keycloakSSH PORT22
KEYCLOAK PORT9092
BASE PATH/id
Example: connect to domain:22, forward to 127.0.0.1:9092, then open /id/admin/. Use / when Keycloak is mounted at the root.
Compare the app fingerprint with your provider console or administrator. Do not trust a value obtained only through the same untrusted path.
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pubEnter the profile, Keycloak port, and base path in Android. Leave Advanced off, import the key, approve the verified fingerprint, and open Keycloak admin.
SSH provides the network route. Keycloak still requires its administrator account, MFA, roles, and session controls.
02 / CHOOSE A PATH
Standard first. Connector by choice.
SSH tunnel
No installation on the server. Android forwards a loopback-only local port to the Keycloak port you enter, then opens the embedded Keycloak console at the selected base path. Use a private HTTP listener behind SSH. This console permits changes according to your Keycloak account roles; only advanced snapshots are read-only.
- Zero ASL infrastructure
- Normal Keycloak login remains
- Best general-purpose path
Remote connector
For servers that already expose the keycloak-console-connector command. Android requests bounded JSON and displays read-only realm data natively.
- Explicit opt-in
- Credentials stay server-side
- No automatic installation
03 / OPTIONAL SERVER SETUP
Enable only the forward you need
Restricted OpenSSH drop-in
Most OpenSSH servers already allow local forwarding. If yours does not, this script enables it for one existing SSH user and restricts the destination to 127.0.0.1 at the selected Keycloak port.
sudo bash enable-keycloak-ssh-forwarding.sh keycloak-tunnel 9092Protect server access
Use a dedicated SSH account where possible. Run the script from a second administrator session, keep the current session open, and test a new connection before closing it. The script validates SSHD before reload and restores the previous drop-in on failure.
- No public Keycloak exposure
- No user or key creation
- No Keycloak configuration changes
04 / OPTIONAL LOOPBACK PROXY
Keep admin private behind Nginx
Separate private listener
Nginx is unnecessary when SSH can reach Keycloak directly. If Keycloak must remain behind Nginx, create a separate listener on 127.0.0.1 and ::1 instead of removing admin-path blocks from a public virtual host.
sh configure-keycloak-nginx-loopback.sh \
--listen-port 19092 \
--upstream-port 9092 \
--base-path /id \
--upstream-base-path /idWhat the script does
Without --apply, it prints configuration and changes nothing. Explicit apply mode installs one file, runs nginx -t, reloads only after validation, and restores the previous file on failure.
- No firewall changes
- No public listener
- No Keycloak or SSHD changes
- No connector installation
Enter the generated listener port and client base path in the Android app. Advanced mode still requires a separately installed keycloak-console-connector.
05 / DIAGNOSTICS
When the tunnel does not open
SSH connection refused
Check the domain, SSH port, firewall, security group, and whether sshd is listening. The Keycloak port does not replace the SSH port.
Public-key authentication failed
Confirm the SSH username owns the matching authorized_keys entry. Confirm the imported file is the private key and its passphrase is correct.
No service at 127.0.0.1 on the entered port
Use ss, container mappings, or Kubernetes services to find Keycloak. If it is reachable only at a container address or another host, the standard loopback tunnel is insufficient.
The tunnel opens a not-found page
Verify the base path. Use / for a root installation, /id for ASL, or the path configured by the server owner. Enter only the path, not a domain or full URL.
Certificate or hostname warning
Use an HTTP listener on server loopback, such as 8080 or 9092, encrypted between devices by SSH. TLS-only targets are unsupported; ports 443 and 8443 are rejected. Never bypass certificate verification.
Keycloak redirects away from the tunnel
Review Keycloak hostname and frontend URL configuration. The app blocks redirects and resources outside its active SSH origin. External identity providers, domain-bound passkeys, downloads and pop-up flows require your normal trusted browser through an established secure network.
Advanced mode says setup required
Turn Advanced off for standard mode, or intentionally install a compatible least-privilege connector on the customer server.
06 / PRIVACY BY ARCHITECTURE
What stays where
ON YOUR DEVICE
Android: encrypted private key, passphrase, server profile and pinned fingerprint. This browser: an unencrypted, non-sensitive setup checklist.
ON YOUR SERVER
SSH logs, Keycloak login, roles, sessions, audit records, and optional connector credentials.
AT ASL
No SSH key, no Keycloak token, no administration data, and no connection relay.
07 / SUSTAINABILITY
Pay once, connect directly
Android purchase
The recommended release is a one-time paid download through Google Play. There is no ASL subscription because ASL does not operate the connection service.
Optional contribution
A contribution never unlocks features or changes support priority.
Open contribution pageNo hidden service
Payments support software development. They do not buy hosting, Keycloak access, SSH access, or administration rights.