keycloak · hmlnarik · Feb 13, 2024 · Dec 15, 2023 · Feb 13, 2024
diff --git a/.github/scripts/start-local-server.sh b/.github/scripts/start-local-server.sh
@@ -30,6 +30,7 @@ if [ "$1" = "extension" ]; then
     cp extension/user-storage-simple/target/user-storage-properties-example.jar $dist/providers
     cp extension/user-storage-jpa/conf/quarkus.properties $dist/conf
     cp extension/user-storage-jpa/target/user-storage-jpa-example.jar $dist/providers
+    cp extension/extend-admin-console-spi/target/extend-admin-ui.jar $dist/providers
   fi
 fi
 

diff --git a/extension/extend-admin-console-spi/README.md b/extension/extend-admin-console-spi/README.md
@@ -0,0 +1,50 @@
+## Extending the admin ui with SPI
+
+This example shows how you can extend the admin ui by implementing the SPI.
+You can either add a tab to an existing page or have a complete section in the menu.
+By implementing either:
+
+  * `org.keycloak.services.ui.extend.UiPageProvider` for a complete section
+  * `org.keycloak.services.ui.extend.UiTabProvider` for a tab
+
+For both options you need to describe the fields you want on the page by using the `org.keycloak.provider.ProviderConfigProperty`
+To specify where the tab will appear in the ui, you can add a path valid paths can be found in the `routes.ts` files in the admin-ui module of Keycloak project.
+
+This example contains an implementation of both these. `AdminUiPage` is a todo section that is added.
+And `ThemeUiTab` is an extra tab in the realm setting that let's you edit the realm attributes.
+
+### Running
+
+Run this example by compiling with maven:
+
+```bash
+mvn -Pextension clean install -DskipTests=true
+```
+
+Then copy the generated `extend-admin-ui.jar` into your <keycloak-server>/providers folder and run the server using `kc.[sh|bat] start-dev`.
+
+### Screenshots
+
+To illustrate how `getPath` method is used, check the `ThemeUiTab` class in this quickstart. The ThemeUi page can now be found when you navigate to _Realm settings_.
+![attribute ream tab](images/img.png, "Realm attributes tab")
+
+The `AdminUiPage` class illustrates how to introduce a new section into the main menu in admin console. It adds a Todo section as the last item in the side menu:
+![todo section](images/img_1.png, "Todo section")
+
+After you created an item you can view the details by clicking on it in the list:
+![todo detail screen](images/img_2.png, "Todo item details")
+
+### Integration test of the Quickstart
+Make sure you have a Keycloak server running with an admin user in the master realm and copy the generated jar file into the providers folder.
+Your Keycloak server should be listening on `http://localhost:8180`. You can achieve this by running:
+```
+./kc.sh start-dev --http-port=8180
+```
+
+You need to have Chrome browser installed and updated to the latest version. See the root README for additional details.
+```
+mvn clean install -Dextension
+```
+
+### Undeploy the quickstart
+Remove the `extend-admin-ui.jar` from your providers folder and restart the server.
diff --git a/extension/extend-admin-console-spi/images/img.png b/extension/extend-admin-console-spi/images/img.png
diff --git a/extension/extend-admin-console-spi/images/img_1.png b/extension/extend-admin-console-spi/images/img_1.png
diff --git a/extension/extend-admin-console-spi/images/img_2.png b/extension/extend-admin-console-spi/images/img_2.png
diff --git a/extension/extend-admin-console-spi/pom.xml b/extension/extend-admin-console-spi/pom.xml
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.keycloak.quickstarts</groupId>
+        <artifactId>keycloak-quickstart-parent</artifactId>
+        <version>999.0.0-SNAPSHOT</version>
+        <relativePath>../../pom.xml</relativePath>
+    </parent>
+
+    <groupId>org.keycloak.admin.ui</groupId>
+    <artifactId>extend-admin-ui</artifactId>
+    <name>Keycloak Quickstart: Extend Admin Console UI</name>
+    <description>Extend the admin UI with Java</description>
+    <packaging>jar</packaging>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.jboss.arquillian.graphene</groupId>
+            <artifactId>graphene-webdriver</artifactId>
+            <version>${arquillian-graphene.version}</version>
+            <type>pom</type>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.jboss.arquillian.extension</groupId>
+            <artifactId>arquillian-phantom-driver</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <finalName>extend-admin-ui</finalName>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>compile</id>
+                        <phase>compile</phase>
+                        <goals>
+                            <goal>compile</goal>
+                        </goals>
+                    </execution>
+                    <execution>
+                        <id>testCompile</id>
+                        <phase>test-compile</phase>
+                        <goals>
+                            <goal>testCompile</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>
diff --git a/extension/extend-admin-console-spi/src/main/java/org/keycloak/admin/ui/AdminUiPage.java b/extension/extend-admin-console-spi/src/main/java/org/keycloak/admin/ui/AdminUiPage.java
@@ -0,0 +1,76 @@
+/*
+ * Copyright 2024 Red Hat, Inc. and/or its affiliates
+ * and other contributors as indicated by the @author tags.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.keycloak.admin.ui;
+
+import org.keycloak.Config;
+import org.keycloak.component.ComponentModel;
+import org.keycloak.models.KeycloakSessionFactory;
+import org.keycloak.provider.ProviderConfigProperty;
+import org.keycloak.provider.ProviderConfigurationBuilder;
+import org.keycloak.services.ui.extend.UiPageProvider;
+import org.keycloak.services.ui.extend.UiPageProviderFactory;
+
+import java.util.List;
+
+/**
+ * Implements UiPageProvider so it will be a master detail view in the admin ui of TODO items
+ */
+public class AdminUiPage implements UiPageProvider, UiPageProviderFactory<ComponentModel> {
+
+    @Override
+    public void init(Config.Scope config) {
+    }
+
+    @Override
+    public void postInit(KeycloakSessionFactory factory) {
+    }
+
+    @Override
+    public void close() {
+    }
+
+    @Override
+    public String getId() {
+        return "Todo";
+    }
+
+    @Override
+    public String getHelpText() {
+        return "Here you can store your Todo items";
+    }
+
+    @Override
+    public List<ProviderConfigProperty> getConfigProperties() {
+        return ProviderConfigurationBuilder.create()
+                .property()
+                .name("name")
+                .label("Name")
+                .helpText("Short name of the task")
+                .type(ProviderConfigProperty.STRING_TYPE)
+                .add().property()
+                .name("description")
+                .label("Description")
+                .helpText("Description of what needs to be done")
+                .type(ProviderConfigProperty.TEXT_TYPE)
+                .add().property()
+                .name("prio")
+                .label("Priority")
+                .type(ProviderConfigProperty.LIST_TYPE)
+                .options("critical", "high priority", "neutral", "low priority", "unknown")
+                .add().build();
+    }
+}
diff --git a/extension/extend-admin-console-spi/src/main/java/org/keycloak/admin/ui/ThemeUiTab.java b/extension/extend-admin-console-spi/src/main/java/org/keycloak/admin/ui/ThemeUiTab.java
@@ -0,0 +1,87 @@
+/*
+ * Copyright 2024 Red Hat, Inc. and/or its affiliates
+ * and other contributors as indicated by the @author tags.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.keycloak.admin.ui;
+
+import org.keycloak.Config;
+import org.keycloak.component.ComponentModel;
+import org.keycloak.models.KeycloakSession;
+import org.keycloak.models.KeycloakSessionFactory;
+import org.keycloak.models.RealmModel;
+import org.keycloak.provider.ProviderConfigProperty;
+import org.keycloak.provider.ProviderConfigurationBuilder;
+import org.keycloak.services.ui.extend.UiTabProvider;
+import org.keycloak.services.ui.extend.UiTabProviderFactory;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+public class ThemeUiTab implements UiTabProvider, UiTabProviderFactory<ComponentModel> {
+
+    private KeycloakSession session;
+
+    @Override
+    public String getId() {
+        return "Attributes";
+    }
+
+    @Override
+    public String getHelpText() {
+        return null;
+    }
+
+    @Override
+    public void init(Config.Scope config) {
+    }
+
+    @Override
+    public void postInit(KeycloakSessionFactory factory) {
+    }
+
+    @Override
+    public void close() {
+    }
+
+    @Override
+    public void onCreate(KeycloakSession session, RealmModel realm, ComponentModel model) {
+        realm.setAttribute("logo", model.get("logo"));
+    }
+
+    @Override
+    public List<ProviderConfigProperty> getConfigProperties() {
        final ProviderConfigurationBuilder builder = ProviderConfigurationBuilder.create();
+        builder.property()
+                .name("logo")
+                .label("Set a logo")
+                .helpText("This logo will be shown on the account ui")
+                .type(ProviderConfigProperty.STRING_TYPE)
+                .add();
+        return builder.build();
+    }
+
+    @Override
+    public String getPath() {
+        return "/:realm/realm-settings/:tab?";
+    }
+
+    @Override
+    public Map<String, String> getParams() {
+        Map<String, String> params = new HashMap<>();
+        params.put("tab", "attributes");
+        return params;
+    }
+}
diff --git a/...rc/main/resources/META-INF/services/org.keycloak.services.ui.extend.UiPageProviderFactory b/...rc/main/resources/META-INF/services/org.keycloak.services.ui.extend.UiPageProviderFactory
@@ -0,0 +1 @@
+org.keycloak.admin.ui.AdminUiPage
diff --git a/...src/main/resources/META-INF/services/org.keycloak.services.ui.extend.UiTabProviderFactory b/...src/main/resources/META-INF/services/org.keycloak.services.ui.extend.UiTabProviderFactory
@@ -0,0 +1 @@
+org.keycloak.admin.ui.ThemeUiTab