Stuck: understanding frontendurl/baseurl, and configuring registration pages

I’m a bit stuck, and I’ll freely admit I’ve managed to avoid Java-related systems for years. So my lack of experience with Java/JBoss/Wildlfy is contributing to my frustration.

I’m testing keycloak as an IdP for basic access/authorization to a backend object storage system and various web apps. Integrating the backend storage is not really an issue, but I was looking to leverage the existing account registration and management features of keycloak so I don’t have to write that myself.

I would like to use Keycloak URLs of a format:
registration: https://auth.example.com/register
login: https://auth.example.com/login
account: https://auth.example.com/manage-account

or something similar. Basically, abstract Keycloak from the URI structure.

My intent was to set up a simple www.example.com site to have links like “Register” and “Login” that simply forward to their respective keycloak pages for registration and login, with something like the URL structure above. Then, the account page template would probably have some simple access info based on the username variable until a more involved application is needed.

Figuring that part out is where I’m stuck.

My test env is HA Proxy doing SSL termination on a public IP, and passing HTTP requests to a private IP that is running a standalone instance of Keycloak. I access the admin console using the internal hostname/IP over VPN.

The Keycloak instance uses a hostname format like auth1.sys.example.com. The externally presented hostname in DNS and the SSL cert is in the format auth.example.com.

If I use the internal hostname (http://auth1.sys.example.com:8080), everything works, everything works, meaning URLs like https://auth1.sys.example.com/auth/realms/Example/account function as expected.

If I configure a frontendURL in the realm settings (not in standalone.xml) to “https://auth.example.com/auth”, everything works similar to the above.

If I try to remove the /auth from the frontendURL (because it’s redundant with auth.example.com), everything breaks.

The pre-configured clients in the realm, such as “account” and “account-console” have Base URLs configured like “http://auth1.sys.example.com:8080/auth/realms/Example/account”, rather than using the new frontendURL configured in the realm.

Ultimately, I’d like to use the existing Keycloak template pages but with a different URL structure. If I try to change the Base URL for the “account” client application, everything breaks (I’m guessing this only changes the client app settings, rather than the included client app itself).

  • I suppose I could iframe the account/registration/login URLs.
  • I suppose adding a separate proxy instance (eg, Nginx) to proxy_path the URLs instead of just the hostname might work, too.
  • I suppose editing the included client apps directly requires modifying the java classes in $KEYCLOAK_DIR/bin/client (or creating new ones with the appropriate changes), but that’s a bit beyond my skill set.
  • For self-registration, I could just create a form to collect the username/password and POST it to the API, but I can’t find actual API info on that in the Server Developer docs (or in the Securing Apps docs). The docs show how to secure external apps with OAuth/SAML/etc, but that’s not really what I’m looking to do here.

What’s the best approach here?

Similar topics I checked, but didn’t have answers:

1 Like

To clarify a little bit, the storage system and existing applications authenticate against LDAP currently. I just didn’t have a self-registration page and was going to write one. But after thinking through the workflow and various anti-abuse requirements to prevent bots and spammers from filling up my LDAP server, I started looking for some boilerplate or existing systems that could create new identities and provide registration/login controls (hence, Keycloak).

I may still use LDAP as a backing store for user info, but just need to figure out the best approach to registration/account pages for now.

Hi,
I have the feeling you focus to much to customize things that are hard to adapt while you may oversee that other services you look for are ready to be leveraged.

Regarding the frontend URL: it is optional since keycloak analyzes the URL you use to access it and leverages that to generate links. Most links are relative anyway, but when email with links are being sent you can control the links based on the frontend url.
To my knowledge you cannot easily modify the /auth… part, just more the Hostname / protocol/ port part. So if possible stick with the (Multi-tenant) structure that uses /auth//… as this structure is well designed both functional as well as security wise.
For sure you can make changes but it requires both jboss and keycloak skills.

On the other hand, I am not sure if You saw that you just need to enable self-registration, password-reset etc as features on your realm (which you should create as first step).

I‘m not sure if this is helpful… just a try.

Keycloak supports both OpenID Connect (an extension to OAuth 2.0) and SAML 2.0.

See: Securing Applications and Services Guide

Keycloak provides the Register (Sign up):

And Login (Sign In) pages (which are theme-able):

Screen Shot 2020-09-03 at 07.50.23

Blog posts:

Forum posts:

vju42 writes:

I have the feeling you focus to much to customize things that are hard to adapt while you may oversee that other services you look for are ready to be leveraged.

I am not sure if You saw that you just need to enable self-registration, password-reset etc as features on your realm (which you should create as first step)

Actually, most everything else I’ve tested seems to work fine. Federation with existing identity stores (eg, FreeIPA) worked out-of-the-box; enabling self-service registration wasn’t a problem, and the theming/templating system looks straightforward enough.

Regarding the frontend URL: it is optional since keycloak analyzes the URL you use to access it and leverages that to generate links. Most links are relative anyway, but when email with links are being sent you can control the links based on the frontend url.

The tooltip for Frontend URL for a given realm says “Set the frontend URL for the realm. Use in combination with the default hostname provider to override the base URL for frontend requests for a specific realm”.

To me, that sounds like I could use “https://some.host.example.com/path/to/some/lengthy/URI/because/I/can”, and that should then be the root/baseurl for appending URIs like /realms/REALM/account. Indeed, this is what the docs imply in Server Installation -> Hostname -> Default Provider:

Frontend request do not have to have the same context-path as the Keycloak server. This means you can expose Keycloak on for example https://auth.example.org or https://example.org/keycloak while internally its URL could be https://10.0.0.10:8080/auth .

That’s a good start to what I’m trying to do, but it doesn’t actually work this way. The request URI /auth must be included in the frontend URL setting and nothing different, or everything goes all 404 (probably because of the separate web-context for /auth URI in standalone.xml and the meta-refresh in the welcome-content/index.html file, and maybe other things hard-coded elsewhere? I really don’t know at this point).

So this is more correctly a “change the frontend hostname if you want, but we’re going to force you to use the format ‘https://[yourhostname]/auth’ if you want it to actually function irrespective of what is listed in the documentation”.

To my knowledge you cannot easily modify the /auth… part, just more the Hostname / protocol/ port part. So if possible stick with the (Multi-tenant) structure that uses /auth//… as this structure is well designed both functional as well as security wise.

That’s the problem. I don’t need multiple realms. I’m not an enterprise with multiple subsidiaries that need separate identity systems managed by a central IT staff. I would like to adjust the URI scheme to reflect the single-realm nature of this project.

For sure you can make changes but it requires both jboss and keycloak skills.

Heard.

Thanks for the suggestions. It’s looking like Keycloak is not the right fit for my use case. :frowning:

2 Likes

Thanks Robinyo, but perhaps I wasn’t clear in what I’m trying to accomplish.

I was looking to customize the URI structure so that https://auth.example.com/account was used instead of https://auth.example.com/auth/realms/Example/account.

I thought frontendURL and the various related settings would accomplish this, but that doesn’t seem to be the case. Likewise, endpoints for OIDC and SAML would need a similar scheme (ie, no “/auth/realms/Example” in the URL since they aren’t needed for a single realm system) but the /auth/realms/REALM_NAME URI scheme doesn’t seem to be configurable

From what I’m seeing, there is not a suitable way to accomplish this in Keycloak itself.

Now that sheds some light. Still the final goal is unclear - this looks like an url shortening excercise (i actually like it).
Just thoughts:

Any reverse proxy could handle this (yes it’s a bit more work, not only one route as you point out).
It just means that for new realms you need to add a config

The wildfly Server itself can register for you easily the roots you look for and rewrite or just redirect

Keycloak let’s you Build your own endpoints - so so you possibly just extend keycloak a bit.

We have a use case we’re trying to accomplish that’s almost identical to this.

We’d like to shorten the URLs that customers are exposed to and instead use subdomains in order to map the requests to the proper realm.

Instead of
https://www.foo.com/auth/admin/master/console/#/realms/entry
We’d present to end-user and would respond to requests at
https://entry.foo.com/auth/admin/master/console/#

We’ve played around with reverse proxies, but this seems unworkable / needlessly complex. and we would prefer to code/configure this in Keycloak.

2 Likes

Hi Andrew, just wondering if you got anywhere with this? I am guessing not as looking through the js adapter the /…realm…/ part of the URL is baked into it, if not what was your alternative?

I was hoping for the same and had a brief look at hacking something in the proxy in front of Keycloak but it doesn’t seem feasible without getting messy and requiring edits in the Keycloak server too which is beyond my comprehension at the minute.

Steve