keycloak · ahus1 · Jul 11, 2024 · Jul 8, 2024 · Jul 8, 2024
@@ -174,8 +174,8 @@ jobs:
           tar xfvz keycloak-999.0.0-SNAPSHOT.tar.gz
           keycloak-999.0.0-SNAPSHOT/bin/kc.sh start-dev --features=transient-users,oid4vc-vci &> ~/server.log &
         env:
-          KEYCLOAK_ADMIN: admin
-          KEYCLOAK_ADMIN_PASSWORD: admin
+          KC_BOOTSTRAP_ADMIN_USERNAME: admin
+          KC_BOOTSTRAP_ADMIN_PASSWORD: admin
 
       - name: Install Playwright browsers
         run: pnpm --fail-if-no-match --filter ${{ env.WORKSPACE }} exec playwright install --with-deps
@@ -268,8 +268,8 @@ jobs:
           tar xfvz keycloak-999.0.0-SNAPSHOT.tar.gz
           keycloak-999.0.0-SNAPSHOT/bin/kc.sh start-dev --features=admin-fine-grained-authz,transient-users &> ~/server.log &
         env:
-          KEYCLOAK_ADMIN: admin
-          KEYCLOAK_ADMIN_PASSWORD: admin
+          KC_BOOTSTRAP_ADMIN_USERNAME: admin
+          KC_BOOTSTRAP_ADMIN_PASSWORD: admin
 
       - name: Start LDAP server
         run: pnpm --fail-if-no-match --filter ${{ env.WORKSPACE }} cy:ldap-server &

@@ -19,13 +19,13 @@ image:images/initial-welcome-page.png[Welcome page]
 
 === Creating the account remotely
 
-If you cannot access the server from a `localhost` address or just want to start {project_name} from the command line, use the `KEYCLOAK_ADMIN` and `KEYCLOAK_ADMIN_PASSWORD` environment variables to create an initial admin account.
+If you cannot access the server from a `localhost` address or just want to start {project_name} from the command line, use the `KC_BOOTSTRAP_ADMIN_USERNAME` and `KC_BOOTSTRAP_ADMIN_PASSWORD` environment variables to create an initial admin account.
 
 For example:
 [source,bash]
 ----
-export KEYCLOAK_ADMIN=<username>
-export KEYCLOAK_ADMIN_PASSWORD=<password>
+export KC_BOOTSTRAP_ADMIN_USERNAME=<username>
+export KC_BOOTSTRAP_ADMIN_PASSWORD=<password>
 
 bin/kc.[sh|bat] start
 ----
@@ -71,3 +71,7 @@ If you are migrating from previous versions where any of the following settings
 * `connectionPoolingDebug`
 
 For more details, see link:{adminguide_link}#_ldap_connection_pool[Configuring the connection pool].
+
+= Admin Bootstrapping
+
+The environment variables `KEYCLOAK_ADMIN` and `KEYCLOAK_ADMIN_PASSWORD` have been deprecated. You should use `KC_BOOTSTRAP_ADMIN_USERNAME` and `KC_BOOTSTRAP_ADMIN_PASSWORD` instead. These are also general options, so they may be specified via the cli or other config sources, for example `--bootstrap-admin-username=admin`.
@@ -51,8 +51,8 @@ oc new-project keycloak
 [source,bash,subs="attributes+"]
 ----
 oc process -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/openshift/keycloak.yaml \
-    -p KEYCLOAK_ADMIN=admin \
-    -p KEYCLOAK_ADMIN_PASSWORD=admin \
+    -p KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+    -p KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
     -p NAMESPACE=keycloak \
 | oc create -f -
 ----

@@ -4,7 +4,7 @@ From a terminal, enter the following command to start {project_name}:
 
 [source,bash,subs="attributes+"]
 ----
-{containerCommand} run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:{version} start-dev
+{containerCommand} run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:{version} start-dev
 ----
 
 This command starts {project_name} exposed on the local port 8080 and creates an initial admin user with the username `admin`

@@ -496,13 +496,13 @@ spec:
         containers:
           - env:
               # We want to have an externally provided username and password, therefore, we override those two environment variables
-              - name: KEYCLOAK_ADMIN
+              - name: KC_BOOTSTRAP_ADMIN_USERNAME
                 valueFrom:
                   secretKeyRef:
                     name: keycloak-preconfigured-admin
                     key: username
                     optional: false
-              - name: KEYCLOAK_ADMIN_PASSWORD
+              - name: KC_BOOTSTRAP_ADMIN_PASSWORD
                 valueFrom:
                   secretKeyRef:
                     name: keycloak-preconfigured-admin

@@ -469,13 +469,13 @@ spec:
         containers:
           - env:
               # We want to have an externally provided username and password, therefore, we override those two environment variables
-              - name: KEYCLOAK_ADMIN
+              - name: KC_BOOTSTRAP_ADMIN_USERNAME
                 valueFrom:
                   secretKeyRef:
                     name: keycloak-preconfigured-admin
                     key: username
                     optional: false
-              - name: KEYCLOAK_ADMIN_PASSWORD
+              - name: KC_BOOTSTRAP_ADMIN_PASSWORD
                 valueFrom:
                   secretKeyRef:
                     name: keycloak-preconfigured-admin

@@ -49,7 +49,7 @@ However, there is also an auto build mode that makes Keycloak behave more or les
 The Keycloak Wildfly distribution contained scripts named `add-user-keycloak.sh` to add initial users to Keycloak.
 These are no longer included in the Quarkus distribution.
 
-To add the initial admin user, set the environment variables `KEYCLOAK_ADMIN` and `KEYCLOAK_ADMIN_PASSWORD` for the username and password of the user.
+To add the initial admin user, set the environment variables `KC_BOOTSTRAP_ADMIN_USERNAME` and `KC_BOOTSTRAP_ADMIN_PASSWORD` for the username and password of the user.
 Keycloak uses them at the first startup to create an initial user with administration rights.
 Once the first user with administrative rights exists, use the command line tool `kcadm.sh` (Linux) or `kcadm.bat` (Windows) to create additional users.
 

@@ -194,7 +194,7 @@ Before deploying {project_name} in a production environment, make sure to follow
 By default, example configuration options for the production mode are commented out in the default `conf/keycloak.conf` file. These options give you an idea about the main configuration to consider when running {project_name} in production.
 
 == Creating the initial admin user
-You can create the initial admin user by using the web frontend, which you access using a local connection (localhost). You can instead create this user by using environment variables. Set `KEYCLOAK_ADMIN=_<username>_` for the initial admin username and `KEYCLOAK_ADMIN_PASSWORD=_<password>_` for the initial admin password.
+You can create the initial admin user by using the web frontend, which you access using a local connection (localhost). You can instead create this user by using environment variables. Set `KC_BOOTSTRAP_ADMIN_USERNAME=_<username>_` for the initial admin username and `KC_BOOTSTRAP_ADMIN_PASSWORD=_<password>_` for the initial admin password.
 
 {project_name} parses these values at first startup to create an initial user with administrative rights.
 Once the first user with administrative rights exists, you can use the Admin Console or the command line tool `kcadm.[sh|bat]` to create additional users.

@@ -134,7 +134,7 @@ To start the image, run:
 [source, bash]
 ----
 podman|docker run --name mykeycloak -p 8443:8443 -p 9000:9000 \
-        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
+        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
         mykeycloak \
         start --optimized
 ----
@@ -155,7 +155,7 @@ If you want to expose the container using a different port, you need to set the
 [source, bash]
 ----
 podman|docker run --name mykeycloak -p 3000:8443 \
-        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
+        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
         mykeycloak \
         start --optimized --hostname-port=3000
 ----
@@ -169,7 +169,7 @@ You use the `start-dev` command:
 [source,bash,subs="attributes+"]
 ----
 podman|docker run --name mykeycloak -p 8080:8080 \
-        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
+        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
         quay.io/keycloak/keycloak:{containerlabel} \
         start-dev
 ----
@@ -188,7 +188,7 @@ For example:
 [source,bash,subs="attributes+"]
 ----
 podman|docker run --name mykeycloak -p 8080:8080 \
-        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
+        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
         quay.io/keycloak/keycloak:{containerlabel} \
         start \
         --db=postgres --features=token-exchange \
@@ -208,10 +208,10 @@ This approach significantly increases startup time and creates an image that is
 [source, bash]
 ----
 # setting the admin username
--e KEYCLOAK_ADMIN=<admin-user-name>
+-e KC_BOOTSTRAP_ADMIN_USERNAME=<admin-user-name>
 
 # setting the initial password
--e KEYCLOAK_ADMIN_PASSWORD=change_me
+-e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me
 ----
 
 == Importing A Realm On Startup
@@ -221,7 +221,7 @@ The {project_name} containers have a directory `/opt/keycloak/data/import`. If y
 [source,bash,subs="attributes+"]
 ----
 podman|docker run --name keycloak_unoptimized -p 8080:8080 \
-        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
+        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
         -v /path/to/realm/data:/opt/keycloak/data/import \
         quay.io/keycloak/keycloak:{containerlabel} \
         start-dev --import-realm
@@ -250,7 +250,7 @@ For example, you can specify the environment variable and memory limit as follow
 [source,bash,subs="attributes+"]
 ----
 podman|docker run --name mykeycloak -p 8080:8080 -m 1g \
-        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
+        -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
         -e JAVA_OPTS_KC_HEAP="-XX:MaxHeapFreeRatio=30 -XX:MaxRAMPercentage=65" \
         quay.io/keycloak/keycloak:{containerlabel} \
         start-dev

@@ -37,8 +37,8 @@ async function startServer() {
   await downloadServer(scriptArgs.local);
 
   const env = {
-    KEYCLOAK_ADMIN: ADMIN_USERNAME,
-    KEYCLOAK_ADMIN_PASSWORD: ADMIN_PASSWORD,
+    KC_BOOTSTRAP_ADMIN_USERNAME: ADMIN_USERNAME,
+    KC_BOOTSTRAP_ADMIN_PASSWORD: ADMIN_PASSWORD,
     ...process.env,
   };
 

@@ -69,14 +69,14 @@ void testBuildAndStart(KeycloakDistribution dist) {
     }
 
     @Test
-    @WithEnvVars({"KEYCLOAK_ADMIN", "admin123", "KEYCLOAK_ADMIN_PASSWORD", "admin123"})
+    @WithEnvVars({"KC_BOOTSTRAP_ADMIN_USERNAME", "admin123", "KC_BOOTSTRAP_ADMIN_PASSWORD", "admin123"})
     @Launch({"start-dev"})
     void testCreateAdmin(KeycloakDistribution dist, LaunchResult result) {
         assertAdminCreation(dist, result, "admin123", "admin123", "admin123");
     }
 
     @Test
-    @WithEnvVars({"KEYCLOAK_ADMIN", "admin123", "KEYCLOAK_ADMIN_PASSWORD", "admin123"})
+    @WithEnvVars({"KC_BOOTSTRAP_ADMIN_USERNAME", "admin123", "KC_BOOTSTRAP_ADMIN_PASSWORD", "admin123"})
     @Launch({"start-dev"})
     void testCreateDifferentAdmin(KeycloakDistribution dist, LaunchResult result) {
         assertAdminCreation(dist, result, "admin123", "new-admin", "new-admin");
@@ -86,8 +86,8 @@ private void assertAdminCreation(KeycloakDistribution dist, LaunchResult result,
         assertTrue(result.getOutput().contains("Created temporary admin user with username " + initialUsername),
                 () -> "The Output:\n" + result.getOutput() + "doesn't contains the expected string.");
 
-        dist.setEnvVar("KEYCLOAK_ADMIN", nextUsername);
-        dist.setEnvVar("KEYCLOAK_ADMIN_PASSWORD", password);
+        dist.setEnvVar("KC_BOOTSTRAP_ADMIN_USERNAME", nextUsername);
+        dist.setEnvVar("KC_BOOTSTRAP_ADMIN_PASSWORD", password);
         CLIResult cliResult = dist.run("start-dev", "--log-level=org.keycloak.services:debug");
 
         cliResult.assertNoMessage("Added temporary admin user '");

@@ -50,8 +50,8 @@ void testFipsNonApprovedMode(KeycloakDistribution dist) {
     @Test
     void testFipsApprovedModePasswordFails(KeycloakDistribution dist) {
         runOnFipsEnabledDistribution(dist, () -> {
-            dist.setEnvVar("KEYCLOAK_ADMIN", "admin");
-            dist.setEnvVar("KEYCLOAK_ADMIN_PASSWORD", "admin");
+            dist.setEnvVar("KC_BOOTSTRAP_ADMIN_USERNAME", "admin");
+            dist.setEnvVar("KC_BOOTSTRAP_ADMIN_PASSWORD", "admin");
 
             CLIResult cliResult = dist.run("start", "--fips-mode=strict");
             cliResult.assertStarted();
@@ -65,8 +65,8 @@ void testFipsApprovedModePasswordFails(KeycloakDistribution dist) {
     @Test
     void testFipsApprovedModePasswordSucceeds(KeycloakDistribution dist) {
         runOnFipsEnabledDistribution(dist, () -> {
-            dist.setEnvVar("KEYCLOAK_ADMIN", "admin");
-            dist.setEnvVar("KEYCLOAK_ADMIN_PASSWORD", "adminadminadmin");
+            dist.setEnvVar("KC_BOOTSTRAP_ADMIN_USERNAME", "admin");
+            dist.setEnvVar("KC_BOOTSTRAP_ADMIN_PASSWORD", "adminadminadmin");
 
             CLIResult cliResult = dist.run("start", "--fips-mode=strict");
             cliResult.assertStarted();

@@ -39,7 +39,7 @@
 import static org.hamcrest.MatcherAssert.assertThat;
 
 @DistributionTest(keepAlive = true, enableTls = true, defaultOptions = { "--http-enabled=true", "--features=hostname:v1" })
-@WithEnvVars({"KEYCLOAK_ADMIN", "admin123", "KEYCLOAK_ADMIN_PASSWORD", "admin123"})
+@WithEnvVars({"KC_BOOTSTRAP_ADMIN_USERNAME", "admin123", "KC_BOOTSTRAP_ADMIN_PASSWORD", "admin123"})
 @RawDistOnly(reason = "Containers are immutable")
 public class HostnameV1DistTest {
 

@@ -35,7 +35,7 @@
 import static org.hamcrest.Matchers.containsString;
 
 @DistributionTest(keepAlive = true, enableTls = true, defaultOptions = "--features=hostname:v1")
-@WithEnvVars({"KEYCLOAK_ADMIN", "admin123", "KEYCLOAK_ADMIN_PASSWORD", "admin123"})
+@WithEnvVars({"KC_BOOTSTRAP_ADMIN_USERNAME", "admin123", "KC_BOOTSTRAP_ADMIN_PASSWORD", "admin123"})
 @RawDistOnly(reason = "Containers are immutable")
 public class ProxyHostnameV1DistTest {
 

@@ -35,7 +35,7 @@
 import static org.hamcrest.Matchers.containsString;
 
 @DistributionTest(keepAlive = true, enableTls = true)
-@WithEnvVars({"KEYCLOAK_ADMIN", "admin123", "KEYCLOAK_ADMIN_PASSWORD", "admin123"})
+@WithEnvVars({"KC_BOOTSTRAP_ADMIN_USERNAME", "admin123", "KC_BOOTSTRAP_ADMIN_PASSWORD", "admin123"})
 @RawDistOnly(reason = "Containers are immutable")
 public class ProxyHostnameV2DistTest {
 

@@ -249,7 +249,7 @@ private Theme getTheme() {
     }
 
     protected String getAdminCreationMessage() {
-        return "or set the environment variables KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD before starting the server";
+        return "or set the environment variables KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD before starting the server";
     }
 
     private boolean shouldBootstrap() {

@@ -13,9 +13,6 @@ public class EmbeddedKeycloakTestServer implements KeycloakTestServer {
 
     @Override
     public void start(KeycloakTestServerConfig serverConfig) {
-        serverConfig.adminUserName().ifPresent(username -> System.setProperty("keycloakAdmin", username));
-        serverConfig.adminUserPassword().ifPresent(password -> System.setProperty("keycloakAdminPassword", password));
-
         List<String> rawOptions = new LinkedList<>();
         rawOptions.add("start-dev");
 //        rawOptions.add("--db=dev-mem"); // TODO With dev-mem there's an issue as the H2 DB isn't stopped when restarting embedded server
@@ -24,6 +21,9 @@ public void start(KeycloakTestServerConfig serverConfig) {
         if (!serverConfig.features().isEmpty()) {
             rawOptions.add("--features=" + String.join(",", serverConfig.features()));
         }
+
+        serverConfig.adminUserName().ifPresent(username -> rawOptions.add("--bootstrap-admin-username=" + username));
+        serverConfig.adminUserPassword().ifPresent(password -> rawOptions.add("--bootstrap-admin-password=" + password));
 
         serverConfig.options().forEach((key, value) -> rawOptions.add("--" + key + "=" + value));
 

@@ -151,8 +151,8 @@ private Process startContainer() throws IOException {
         }
 
         if (!StoreProvider.JPA.equals(StoreProvider.getCurrentProvider())) {
-            builder.environment().put("KEYCLOAK_ADMIN", "admin");
-            builder.environment().put("KEYCLOAK_ADMIN_PASSWORD", "admin");
+            builder.environment().put("KC_BOOTSTRAP_ADMIN_USERNAME", "admin");
+            builder.environment().put("KC_BOOTSTRAP_ADMIN_PASSWORD", "admin");
         }
 
         if (restart.compareAndSet(false, true)) {

@@ -110,7 +110,7 @@
                     </div>
                   </form>
                 <#else>
-                  <p>To create the administrative user open <a href="${localAdminUrl}">${localAdminUrl}</a>, or set the environment variables <code>KEYCLOAK_ADMIN</code> and <code>KEYCLOAK_ADMIN_PASSWORD</code> when starting the server.</p>
+                  <p>To create the administrative user open <a href="${localAdminUrl}">${localAdminUrl}</a>, or set the environment variables <code>KC_BOOTSTRAP_ADMIN_USERNAME</code> and <code>KC_BOOTSTRAP_ADMIN_PASSWORD</code> when starting the server.</p>
                 </#if>
               </#if>
             </div>
-Original file line number
+Diff line change
@@ Expand Up / @@ -110,7 +110,7 @@ @@
                         </div>
                       </form>
                     <#else>
-                      <p>To create the administrative user open <a href="${localAdminUrl}">${localAdminUrl}</a>, or set the environment variables <code>KEYCLOAK_ADMIN</code> and <code>KEYCLOAK_ADMIN_PASSWORD</code> when starting the server.</p>
+                      <p>To create the administrative user open <a href="${localAdminUrl}">${localAdminUrl}</a>, or set the environment variables <code>KC_BOOTSTRAP_ADMIN_USERNAME</code> and <code>KC_BOOTSTRAP_ADMIN_PASSWORD</code> when starting the server.</p>
                     </#if>
                   </#if>
                 </div>
@@ Expand Down @@