This is a hello world project that demonstrates how to use Keycloak to provide authentication to an application.
Keycloak is a web application and client adapters which provide authentication and authorization services to applications. This demonstration uses the Keycloak server to provide authentication. The demo runs in a WildFly application server which has been configured with the Keycloak adapters.
This README will walk you through how to use Docker to set up Keycloak, set up Wildfly, and run the project.
We will be using Keycloak's Docker container.
# Run the Keycloak Container
docker run -h auth.localhost -p 8180:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin --name hello-world-keycloak jboss/keycloak:2.0.0.FinalIf everything ran correctly, we should be able to navigate to http://auth.localhost:8180/auth
Log into the Keycloak Administration Console using the username "admin" and the password "admin".
You will want to add the "Hello-World" Realm. You can do this by selecting "Add Realm" from the drop down that appears when you mouse over "Master".
Choose "Select File" and load the realm.json file in the root of this project. The "Name" field should populate with "Hello-world".
Now click "Create". Your realm is setup and we can continue to setting up the application.
Before we can compile the application, we need to load the "keycloak.json" file from the Keycloak Administration Console. You can either follow this link or navigate to the "Clients" section of the "Hello-World" realm in the Keycloak Administration Console, select "hello-world", and then navigate to the "Installation" tab. Either way, form the Intallation tab you will want to select the "Keycloak OIDC JSON" option from the "Format Options" menu and then click "Download" and save the keycloak.json file to the WEB-INF directory.
To compile the application we need to invoke maven from the command line in the project's root directory.
mvn clean installWe will again use Docker to launch the Wildfly server. Wildfly is a Java EE server which will run our application.
First we need to build the container from the docker directory.
docker build --tag keycloak-hello-world .You should see the message "Successfully built" if docker is built successfully.
Now we need to start the Docker container
docker run --net=host -d -p 8080:8080 -p 9990:9990 --name hello-world keycloak-hello-worldOnce the Docker container has started, we should be able to navigate to http://localhost:8080.
Finally, from the root of this project we will deploy the application to WildFly.
mvn wildfly:deploy -Dwildfly.username=admin -Dwildfly.password=admin
Once the deployment has finished, we can navigate to http://localhost:8080/keycloak-hello-world-1.0-SNAPSHOT/.
Click "Sign-in",
"Register" a user,
And voilà!
The web.xml file declares that the path /s/hello.jsp is restricted to only logged in sessions with the "user" role.
The "user" role is defined in the realm.json file and is set to be a default role for the realm. When a user browses to "/s/hello.jsp" the Keycloak adapter intercepts this request, prompts for a log-in if necessary, and then provides to the application the user's details.
The hello.jsp file displays the user's name. This is injected into the request by the Keycloak adapter which has been configured to be loaded by WildFly.
If you need assistance with this demo you can contact me via twitter @summerspittman or email secondsun@gmail.com.
We used Docker to speed up the process a lot. Namely we skipped configuring the Wildfly Client Adapter that the Hello World application uses to broker sessions between the application and the auth server. The official Keycloak docs have much more detailed steps for the process.
Also, as a point of note, when we started out application using Docker we used "--net=host". This is generally bad practice and I only used it to make the demonstration easier. In an ideal world we would link the containers or configure DNS to properly route between them.