The purpose of this guide is to get you up and running as quickly as possible so that you can play with and test-drive various features that Keycloak has. It relies heavily on the default database and server configuration and does not cover any complex deployment options. If you want a more in-depth discussion of any features or configuration options, consult the various reference guides available.
This very short tutorial walks you through booting up the server in standalone mode, setting up the initial admin user, and logging into the Keycloak admin console.
The Keycloak Server is contained in one distribution file:
The 'keycloak-4.0.0.Final.[zip|tar.gz]' file is the server only distribution. It contains nothing other than the scripts and binaries to run the Keycloak server.
To unpack these files run the
To boot the Keycloak server, go to the bin/ directory of the server distribution.
To boot the server:
After the server boots, open your browser and go to the http://localhost:8080/auth URL. The page should look like this:
Keycloak does not have a configured admin account by default. You must create one on the Welcome page. This account will allow you to create an admin that can log into the master realm’s administration console so that you can start creating realms and users and registering applications to be secured by Keycloak.
You can only create an initial admin user on the Welcome Page if you connect using
After you create the initial admin account, you can log in to the Admin Console by completing the following steps:
At the bottom of the Welcome page click the Administration Console link. Alternatively you can go to the console URL directly at http://localhost:8080/auth/admin/Login Page
Type the username and password you created on the Welcome page. The Keycloak Admin Console page opens.Admin Console
If you are curious about a certain feature, button, or field within the Admin Console, hover your mouse
over the question mark
In this section you will create a new realm within the Keycloak admin console and add a new user to that realm. You will use that new user to log in to your new realm and visit the built-in user account service that all users have access to.
Before you can create your first realm, complete the installation of Keycloak and create the initial admin user as shown in Installing and Booting.
To create a new realm, complete the following steps:
From the Master drop-down menu, click Add Realm. When you are logged in to the master realm this drop-down menu lists all existing realms.
demoin the Name field and click Create.
When the realm is created, the main admin console page opens. Notice the current realm is now set to
demo. Switch between managing the
master realm and the realm you just created by clicking entries in the Select realm drop-down menu.
To create a new user in the
demo realm, along with a temporary password for that new user, complete the following steps:
From the menu, click Users to open the user list page.
On the right side of the empty user list, click Add User to open the add user page.
Enter a name in the
Usernamefield; this is the only required field. Click Save to save the data and open the management page for the new user.
Click the Credentials tab to set a temporary password for the new user.
Type a new password and confirm it. Click Reset Password to set the user password to the new one you specified.
|This password is temporary and the user will be required to change it after the first login. To create a password that is persistent, flip the Temporary switch from On to Off before clicking Reset Password.|
After you create the new user, log out of the management console by opening the user drop-down menu and selecting Sign Off.
Go to http://localhost:8080/auth/realms/demo/account and log in to the User Account Service of your
demorealm with the user you just created.
Type the username and password you created. You will be required create a permanent password after you successfully log in, unless you changed the Temporary setting to Off when you created the password.
The user account service page will open. Every user in a realm has access to this account service by default. From this page, you can update profile information and change or add additional credentials. For more information on this service see the Server Administration Guide.
This section describes how to secure a Java servlet application on the WildFly application server by: * Installing the Keycloak client adapter on a WildFly application server distribution * Creating and registering a client application in the Keycloak admin console * Configuring the application to be secured by Keycloak
Before you can secure a Java servlet application, you must complete the installation of Keycloak and create the initial admin user as shown in Installing and Booting.
There is one caveat: you must run a separate WildFly instance on the same machine as the Keycloak server to run your Java servlet application. Run the Keycloak using a different port than the WildFly, to avoid port conflicts.
To adjust the port used, change the value of the
jboss.socket.binding.port-offset system property when starting the server from the command line. The value of this property is a number that will be added to the base value of every port opened by the Keycloak server.
To start the Keycloak server while also adjusting the port:
$ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100
> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100
After starting Keycloak, go to http://localhost:8180/auth/admin/ to access the admin console.
Download the WildFly distribution and extract it from the compressed file into a directory on your machine.
Download the WildFly OpenID Connect adapter distribution from keycloak.org.
Extract the contents of this file into the root directory of your WildFly distribution.
Run the appropriate script for your platform:
$ cd bin $ ./jboss-cli.sh --file=adapter-install-offline.cli
> cd bin > jboss-cli.bat --file=adapter-install-offline.cli
$ cd bin $ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
> cd bin > jboss-cli.bat --file=adapter-elytron-install-offline.cli
This script will make the necessary edits to the
Start the application server.
You must have the following installed on your machine and available in your PATH before you continue:
Java JDK 8
Apache Maven 3.1.1 or higher
|You can obtain the code by cloning the Keycloak Quickstarts Repository repository at https://github.com/keycloak/keycloak-quickstarts. The quickstarts are designed to work with the most recent Keycloak release.|
Make sure your WildFly application server is started before you continue.
To download, build, and deploy the code, complete the following steps.
$ git clone https://github.com/keycloak/keycloak-quickstarts $ cd keycloak-quickstarts/app-profile-jee-vanilla $ mvn clean wildfly:deploy
During installation, you will see some text scroll by in the application server console window.
To confirm that the application is successfully deployed, go to http://localhost:8080/vanilla and a login page should appear.
If you click Login, the browser will pop up a BASIC auth login dialog. However, the application is not yet secured by any identity provider, so anything you enter in the dialog box will result in a
To define and register the client in the Keycloak admin console, complete the following steps:
Log in to the admin console with your admin account.
In the top left drop-down menu select and manage the
Clientsin the left side menu to open the Clients page.Clients
On the right side, click Create.
Complete the fields as shown here:Add Client
Click Save to create the client application entry.
Click the Installation tab in the Keycloak admin console to obtain a configuration template.
Select Keycloak OIDC JBoss Subsystem XML to generate an XML template. Copy the contents for use in the next section.Template XML
To configure the WildFly instance that the application is deployed on so that this app is secured by Keycloak, complete the following steps.
standalone/configuration/standalone.xmlfile in the WildFly instance that the application is deployed on and search for the following text:
Modify this text to prepare the file for pasting in contents from the Keycloak OIDC JBoss Subsystem XML template we obtained Keycloak admin console Installation tab by changing the XML entry from self-closing to using a pair of opening and closing tags:
<subsystem xmlns="urn:jboss:domain:keycloak:1.1"> </subsystem>
Paste the contents of the template within the
<subsystem>element, as shown in this example:
<subsystem xmlns="urn:jboss:domain:keycloak:1.1"> <secure-deployment name="WAR MODULE NAME.war"> <realm>demo</realm> <auth-server-url>http://localhost:8180/auth</auth-server-url> <public-client>true</public-client> <ssl-required>EXTERNAL</ssl-required> <resource>vanilla</resource> </secure-deployment> </subsystem>
<subsystem xmlns="urn:jboss:domain:keycloak:1.1"> <secure-deployment name="vanilla.war"> ... </subsystem>
Reboot the application server.