Language and Page Formatting Options
Chapter 7. Use of the public hostname
Red Hat Single Sign-On uses the public hostname for a number of things. For example, in the token issuer fields and URLs sent in password reset emails.
The Hostname SPI provides a way to configure the hostname for a request. The default provider allows setting a fixed URL for frontend requests, while allowing backend requests to be based on the request URI. It is also possible to develop your own provider in the case the built-in provider does not provide the functionality needed.
7.1. Default provider
The default hostname provider uses the configured
frontendUrl as the base URL for frontend requests (requests from user-agents) and uses the request URL as the basis for backend requests (direct requests from clients).
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://example.org/keycloak while internally its URL could be
This makes it possible to have user-agents (browsers) send requests to Red Hat Single Sign-On through the public domain name, while internal clients can use an internal domain name or IP address.
This is reflected in the OpenID Connect Discovery endpoint for example where the
authorization_endpoint uses the frontend URL, while
token_endpoint uses the backend URL. As a note here a public client for instance would contact Keycloak through the public endpoint, which would result in the base of
token_endpoint being the same.
To set the frontendUrl for Keycloak you can either pass add
-Dkeycloak.frontendUrl=https://auth.example.org to the startup or you can configure it in
standalone.xml. See the example below:
<spi name="hostname"> <default-provider>default</default-provider> <provider name="default" enabled="true"> <properties> <property name="frontendUrl" value="https://auth.example.com"/> <property name="forceBackendUrlToFrontendUrl" value="false"/> </properties> </provider> </spi>
To update the
frontendUrl with jboss-cli use the following command:
If you want all requests to go through the public domain name you can force backend requests to use the frontend URL as well by setting
It is also possible to override the default frontend URL for individual realms. This can be done in the admin console.
If you do not want to expose the admin endpoints and console on the public domain use the property
adminUrl to set a fixed URL for the admin console, which is different to the
frontendUrl. It is also required to block access to
/auth/admin externally, for details on how to do that refer to the Server Administration Guide.
7.2. Custom provider
To develop a custom hostname provider you need to implement
Follow the instructions in the Service Provider Interfaces section in Server Developer Guide for more information on how to develop a custom provider.