Keycloak Getting Started Guide

Translation: Baishi (https://github.com/wjw465150/KeycloakGuid)
Original address: https://www.keycloak.org/docs/latest/getting_started/index.html

1 Overview

This guide helps you get started with Keycloak. It covers server configuration and use of the default database. Does not include advanced deployment options. See other reference guides for more in-depth descriptions of features or configuration options.

2. Installation and start

This section describes how to start the Keycloak server in standalone mode, set up the initial admin user, and log into the Keycloak admin console.

2.1. Installing distribution files

Download the Keycloak server distribution file:

keycloak-6.0.1.[zip|tar.gz]

The file can be downloaded from Keycloak downloads .

The **keycloak-6.0.1.[zip|tar.gz]** file is a server-specific distribution. It just contains scripts and binaries to run the Keycloak server.

Place the file in a directory of your choice and use the unzipor tarutility to extract it.

Linux/Unix

$ unzip keycloak-6.0.1.zip

or

$ tar -xvzf keycloak-6.0.1.tar.gz

Windows

> unzip keycloak-6.0.1.zip

2.2. Starting the server

To start the Keycloak server, go to the directory where the server is distributed binand run standalonethe startup script:

Linux/Unix

$ cd bin
$ ./standalone.sh

Windows

> ...\bin\standalone.bat

2.3. Create an administrator account

After the server starts, open it in a web browser http://localhost:8080/auth. The welcome page will indicate that the server is running.

Enter a username and password to create an initial administrative user.

This account will be allowed to log into master(主)the realm's admin console, from which you will create realms and users, and register applications, which will be secured by Keycloak.

If using localhostconnections, only the initial admin user can be created on the welcome page. This is a safety precaution. You can use add-user-keycloak.sha script to create an initial admin user at the command line. See the Server Installation and Configuration Guide and Server Administration Guide for details .

2.4. Login to the management console

After creating the initial administrator account, log in to the Admin console using the following steps:

Click on the Administration Console link on the Welcome page or go directly to the console URL http://localhost:8080/auth/admin/
Open the Keycloak Admin Console by typing the username and password you created on the Welcome page .

Admin Console

3. Create Realms and Users

In this section, you will create a new realm in the Keycloak admin console and add new users to the realm. You will use this new user to log in to your new domain and access the built-in user account services that all users have access to.

3.1. Before you start

(https://www.keycloak.org/docs/latest/getting_started/index.html#_install-boot)

3.2. Creating a new field

To create a new realm, complete the following steps:

Go to http://localhost:8080/auth/admin/ and log into the Keycloak admin console with the account you created in Installation and Startup .
From the Master drop-down menu, click Add Realm . When you log into your primary domain, this drop-down menu lists all existing domains.
Enter it in the Name field demoand click Create .

After the realm is created, the main admin console page opens. Note that the current domain is now set to demo. Switch between the admin realm and the realm you just created by clicking on the entry in the Select realm drop-down menu.master

3.3. Create a new user

To democreate a new user in the domain, and a temporary password for the new user, complete the following steps:

From the menu, click Users to open the user list page.
To the right of the empty user list, click Add User to open the Add User page.
Enter a name in the Username` field; this is the only required field. Click Save to save the data and open the administration page for the new user.
Click the Credentials tab to set a temporary password for the new user.
Enter a new password and confirm it. Click Reset Password to set the user password to the new password you specified.

This password is temporary and needs to be changed by the user after first login. To create a persistent password, flip the Temporary switch from On to Off before clicking Reset Password .

3.4. User Account Services

After creating a new user, log out of the management console by opening the user drop-down menu and selecting Sign Out .
Go to http://localhost:8080/auth/realms/demo/account and log into your demodomain's user account service with the user you just created.
Enter the username and password you created. After successfully logging in, you will need to create a permanent password unless you changed the Temporary setting to Off when creating the password .

The User Account Services page opens. By default, every user in the realm can access this account service. From this page, you can update your profile information and change or add additional credentials. See the Server Administration Guide for details on this service .

4. Securing JBoss Servlet Applications

This section describes how to secure a Java servlet application on the WildFly application server by:

Install the Keycloak client adapter on the WildFly application server distribution
Create and register a client application in the Keycloak admin console
Configure the application to be protected by Keycloak

4.1. Before you start

Before securing your Java servlet application, you must complete the installation of Keycloak and create an initial administrator user, as shown in Installing and Bootstrapping .

One caveat: Although WildFly comes bundled with Keycloak, you cannot use it as an application container. Instead, you have to run a separate instance of WildFly on the same machine as the Keycloak server to run Java servlet applications. Run Keycloak on a different port than WildFly to avoid port conflicts.

To adjust the port used, change jboss.socket.binding.port-offsetthe value of the 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 each port opened by the Keycloak server.

To start the Keycloak server while adjusting the port:

Linux/Unix

$ cd bin
$ ./standalone.sh -Djboss.socket.binding.port-offset=100

Windows

> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100

After starting Keycloak, go to http://localhost:8180/auth/admin/ to access the admin console.

4.2. Installing the Client Adapter

Download the WildFly distribution and extract it from the zip file to a directory on your computer.

Download the WildFly OpenID Connect adapter distribution from keycloak.org .

Extract the contents of this file into the root directory of the WildFly distribution.

Run the appropriate script for your platform:

WildFly 10 and Linux/Unix

$ cd bin
$ ./jboss-cli.sh --file=adapter-install-offline.cli

WildFly 10 and Windows

> cd bin
> jboss-cli.bat --file=adapter-install-offline.cli

Wildfly 11 and Linux/Unix

$ cd bin
$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli

Wildfly 11 and Windows

> cd bin
> jboss-cli.bat --file=adapter-elytron-install-offline.cli

…/standalone/configuration/standalone.xmlThis script will make the necessary edits to the files distributed by your application server and may take some time to complete.

Start the application server.

Linux/Unix

$ cd bin
$ ./standalone.sh

Windows

> ...\bin\standalone.bat

4.3. Downloading, building and deploying the application code

You must have the following software installed on your machine and available in your PATH before proceeding:

Java JDK 8
Apache Maven 3.1.1 or higher
Git

You can get the code by cloning the Keycloak Quickstarts repository at https://github.com/keycloak/keycloak-quickstarts . The quickstart is designed to work with the latest Keycloak release.

Before proceeding, make sure the WildFly application server is started.

To download, build and deploy the code, complete the following steps.

clone project

$ git clone https://github.com/keycloak/keycloak-quickstarts
$ cd keycloak-quickstarts/app-profile-jee-vanilla
$ mvn clean wildfly:deploy

During the installation process, you will see some text scrolling in the application server console window.

To confirm that the application has been successfully deployed, go to http://localhost:8080/vanilla and the login page will be displayed.

If you click Login , the browser will pop up the BASIC auth login dialog. However, the application is not yet secured by any identity provider, so anything you enter in the dialog will cause the server to send a Forbiddenmessage back. web.xmlYou can confirm that the app is currently BASICsecured via authentication by looking for the setting in the app's files.

4.4. Creating and registering a client

To define and register a client in the Keycloak admin console, complete the following steps:

Sign in to the Admin console with your administrator account.
Select and manage DemoRealms . Click on the left menu Clientsto open the Clients page.

Clients
On the right, click Create .
Fill in the fields as shown below:

Add Client (add client)
Click Save to create the client application entry.
Click on the Installation tab in the Keycloak admin console to get the configuration template.
Select Keycloak OIDC JBoss Subsystem XML to generate an XML template. Copy the content for use in the next section.

TemplateXML

4.5. Configuring Subsystems

To configure a WildFly instance where an application is deployed so that Keycloak protects this application, complete the following steps.

Open the file in the WildFly instance where the application is deployed standalone/configuration/standalone.xml, and search for the following text:
```
<subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
```
Modify this text to prepare the file for pasting content from the Keycloak OIDC JBoss Subsystem XML template we get to the Keycloak Admin Console Installation tab by changing the XML entry from auto-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 into <subsystem>the element, as in the following 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>

willname change to vanilla.war:

<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
  <secure-deployment name="vanilla.war">
  ...
</subsystem>

Restart the application server.
Go to http://localhost:8080/vanilla and click Login . When the Keycloak login page opens, log in with the user you created in Create a new user .