Requirements and Setup
Requirements
In case you select Postman, then the provided Postman Collection might be helpful. Just import this Postman Collection (Version 2.1 format) into Postman.
IntelliJ
IntelliJ does not require any specific additional plugins or configuration.
Eclipse IDE
If you are an Eclipse user, then the usage of the Eclipse-based Spring ToolSuite is strongly recommended. This eclipse variant already has all the required gradle and spring boot support pre-installed.
In case you want to stick to your plain Eclipse installation then you have to add the following features via the eclipse marketplace:
BuildShip Gradle Integration (Version 3.x). This might be already pre-installed depending
on your eclipse variant (e.g. Eclipse JavaEE) installed.
Spring Tools 4 for Spring Boot (Spring Tool Suite 4).
Visual Studio Code
To be able to work properly in Visual Studio Code with this Spring Boot Java Gradle project you need at least these extensions:
Java Extension Pack
vscode-gradle-language
VS Code Spring Boot Application Development Extension Pack
Get the source code
Clone this GitHub repository (https://github.com/andifalk/secure-oauth2-oidc-workshop):
After that you can import the whole workshop project directory into your IDE as a gradle project:
IntelliJ: Open menu item "New project from existing sources..." and then select 'Gradle' when prompted
Eclipse or Spring ToolSuite: Open menu item "Import/Gradle/Existing gradle project"
Visual Studio Code: Just open the root directory in VS Code and wait until VS Code has configured the project
Run the java applications
All spring boot based java projects can either be run using your Java IDE or using the command line with changing into the corresponding project directory and issuing a gradlew bootRun command.
For other demo applications like the ones for Micronaut or Quarkus please consult written instructions there.
In this workshop we will use Keycloak by JBoss/RedHat as local identity provider. Keycloak is certified for OpenID Connect 1.0 and implements OAuth 2.0 and OpenID Connect 1.0.
Setup Keycloak
You need a compliant OAuth 2.0 / OpenID Connect provider for this workshop. Here we will use Keycloak by RedHat/JBoss.
To set up Keycloak you have 2 options:
Run Keycloak using Docker (if you have Docker installed)
Local Keycloak installation & configuration
Using Docker
If you have Docker installed then setting up Keycloak is quite easy.
To configure and run Keycloak using docker
Open a new command line terminal window
Change directory to subdirectory setup of the workshop repository
Open and edit the script run_keycloak_docker.sh or run_keycloak_docker.bat (depending on your OS) and adapt the value for WORKSHOP_HOME to your local workshop repository directory
Save and execute the script run_keycloak_docker.sh or run_keycloak_docker.bat (depending on your OS)
Wait until the docker container has been started completely. When you see the line Started 590 of 885 services, then Keycloak is configured and running. Now open your web browser and navigate to localhost:8080/auth/admin and login using the credentials admin/admin.
If you see errors importing the workshop configuration then please re-check the value of the WORKSHOP_HOME environment variable (step 2 above) so that the script can find the keycloak_realm_workshop.json file to import.
Local Installation
To set up Keycloak:
Extract the downloaded zip/tar file keycloak-x.x.x.zip/keycloak-x.x.x.tar-gz into a new local directory of your choice
(this directory will be referenced as in next steps)
This workshop requires a pre-defined configuration for Keycloak (i.e. some OAuth2/OpenID Connect clients, and user accounts).
To configure Keycloak you need to have checked out the GIT repository for this workshop. All you need to configure Keycloak is located in the subdirectory setup of the repository.
Change into the subdirectory setup of the workshop git repository
Open the file import_keycloak_realm.sh or import_keycloak_realm.bat (depending on your OS) in the setup subdirectory
and change the value of the environment variable KEYCLOAK_HOME to your of step 2 and save the file
Now open a new command-line terminal window, change into the subdirectory setup again and execute the provided script
import_keycloak_realm.sh or import_keycloak_realm.bat (depending on your OS).
This starts a standalone Keycloak instance and automatically imports the required configuration.
Wait until the import has finished (look for a line like Started 590 of 885 services) then
direct your web browser to localhost:8080/auth
Here you have to create the initial admin user to get started. Please use the value admin both as username and as password,
then click the button Create. Please note: In production you must use a much more secure password for the admin user!
Now you can continue to the Administration Console by clicking on the corresponding link displayed and login using the new credentials
If all worked successfully you should see the settings page of the Workshop realm and Keycloak is ready for this Workshop !
Startup Keycloak
Please note: You have to do the initial setup section for local install variant only once. If you have stopped Keycloak and want to start it again then follow the next lines in this section.
To startup Keycloak:
Open a terminal and change directory to subdirectory /bin and start Keycloak using
the standalone.sh(Linux or macOS) or standalone.bat (Windows) scripts
Wait until keycloak has been started completely - you should see something like this
...(WildFly Core ...) started in 6902ms - Started 580 of 842 services
Remap default port of Keycloak
In case port 8080 does not work on your local machine (i.e. is used by another process) then you may have to change Keycloak to use another port. This can be done like this (e.g. for remapping port to 8090 instead of 8080):
On Linux/macOS:
On Windows:
Note: Take into account that for all URL's pointing to Keycloak in the hands-on steps you always have to use the remapped port instead of default one (8080) as well.
Open Keycloak Admin UI
Independent of the setup type (docker or local install), to access the web admin UI of Keycloak you need to perform these steps:
Now direct your browser to localhost:8080/auth/admin
Login into the admin console using admin/admin as credentials
Now, if you see the realm workshop on the left then Keycloak is ready to use it for this workshop.
Further Information
If you want to know more about setting up a Keycloak server for your own projects then please consult the keycloak administration docs.
Last updated
