📖
Build options
Options that can be passed to the
npx keycloakify
command.Do not invest time understanding this mode, it'll be removed in the next iteration of Keycloakify.
This is for performance optimisation.
Build the theme without bundling the assets (static js files, images ect). Keycloakify will read the
package.json
-> homepage
field to know from where the assets should be downloaded.This enables to you to levrage CDN and cache big resource files that are used by both the main app and the login pages.
Step to make
--external-assets
work:- Provide the url of your app in the
homepage
field ofpackage.json
example or in apublic/CNAME
file example. (Or usekeycloakify.areAppAndKeycloakServerSharingSameDomain=true
)
- (Optional) Enable long-term assets caching on the server hosting your app. This is how you would do it with Ngnix.
- Make sure not to build your app and the keycloak theme separately (run
yarn build-keycloak-theme
only once in your CI) and remember to update the Keycloak theme every time you update your app. - Be mindful that if your app is down your login pages are down as well.
Prevent the build command from generating outputs.
Tells Keycloakify to generate extra pages.
If you have in your
package.json
:package.json
{
"keycloakify": {
"extraPages": [
"my-extra-page-1.ftl",
"my-extra-page-2.ftl"
]
}
}
Keycloakify will generate
my-extra-page-1.ftl
and my-extra-page-2.ftl
alongside login.ftl
, register-user-profile.ftl
ect...By default the
theme.properties
files located in build_keycloak/src/main/resources/theme/<your app>/login/theme.properties
only contains:parent=keycloak
If, for some reason, you need to add extra properties like for example
env=dev
you can do it by editing your package.json
this way:package.json
{
"keycloakify": {
"extraThemeProperties": [
"env=dev",
"locales=en,ko",
"foo=bar"
]
}
}
You can then access this property in the
kcContext
(kcContext.properties.foo === "bar"
) even if you won't have type safety.Set to
true
it tels Keycloakify that you have configured your reverse proxy so that your app and your Keycloak server are under the same domain, example:- https://example.com/auth: Keycloak.
- https://example.com (or https://example.com/x/y/z): Your App
Example:
package.json
{
"keycloakify": {
"areAppAndKeycloakServerSharingSameDomain": true
}
}
When enabled you don't need to specify a
homepage
field in the package.json
Introduced in 6.11.4
Configure if you want Keycloakify to build the final
.jar
for you or not.package.json
{
"keycloakify": {
"bundler": "none"
}
}
Possibles values are:
"keycloakify"
(default): Keycloakify will build the .jar file."none"
: Keycloakify will not create a .jar file."mvn"
(legacy): Keycloakify will use Maven to bundle the .jar file. This option is to use only if you experience problem with "keycloakify". It require mvn to be installed. If you have to resort to this option please open an issue about it so we can see wha't wrong with our way of building the.jar
file.
You can also convigure this value using an environement variable:
KEYCLOAKIFY_BUNDLER=none npx keycloakify
Introduced in 6.11
Configure the
groupId
that will appear in the pom.xml
file.
package.json
{
"keycloakify": {
"groupId": "dev.keycloakify.demo-app-advanced.keycloak"
}
}
By default it's the package.json hompage field at reverse with .keycloak at the end.
You can overwrite this using an environement variable:
KEYCLOAKIFY_GROUP_ID="com.your-company.your-project.keycloak" npx keycloakify
Introduced in 6.11
Configure the
artifactId
that will appear in the pom.xml
file.
package.json
{
"keycloakify": {
"artifactId": "keycloakify-advanced-starter-keycloak-theme"
}
}
You can overwrite this using an environement variable:
KEYCLOAKIFY_ARTIFACT_ID="my-cool-theme" npx keycloakify
Default: 11.0.3
package.json
{
"keycloakify": {
"keycloakVersionDefaultAssets": "21.0.1"
}
}
Configure the version that will appear in the
pom.xml
file.
By default the version that is used is the one in the package.json of your project
package.json
{
"version": "1.3.4"
}
But you can overwrite this value using an environnement variable (Introduced in 6.11):
KEYCLOAKIFY_THEME_VERSION="4.5.6" npx keycloakify
Introduced in 7.4.0
This option it to use if when trying to use
kcContext.messagesPerField.existsError("your-custom-attribute")
you are getting the error message: There is no your-custom-attribute field

This means that you have defined user attribute thate aren't standard on your Keycloak realm.
customUserAttributes
enables you to let Keycloakify know about thoses fields:package.json
{
"keycloakify": {
"customUserAttributes": ["your-custom-attribute"]
}
}
Note that it is far preferable to use User Profile features (using `register-user-profile.ftl` instead `register.ftl`) since it enables to have a single source of truth and client side field validation. Checkout this section of the doc.
Introduced in 7.5.0
This is the name of the theme in the Keycloak admin select:

By default it's
package.json["name"]
package.json
{
"keycloakify": {
"themeName": "my-custom-name"
}
}

Cloud IAM - Keycloak Identity and Access Management as a Service
Feeling overwhelmed? Check out our exclusive sponsor's Cloud IAM consulting services to simplify your experience.
Last modified 19d ago