minimal-oauth2-keycloak-example

This is a minimalist OAuth2 server built with Spring Boot and integrated with Keycloak. It allows users to securely access its features by using Keycloak as an identity provider. Keycloak verifies user identities and is responsible for managing user roles and groups.

Access to secure resources is redirected to Keycloak for authentication, while authorization is handled within the application.

It's important to note that this application acts as an OAuth2 client, not an OAuth2 resource server. It doesn't manage resources in terms of data or functionality; instead, it serves static HTML pages (which are session-secured).

Configuration

The application.yml file is the configuration file for this OAuth2 client application. It contains settings related to security, authentication, and other application-specific configurations. Below is an overview of the key sections within this file. oauth2-demo-realm and oauth2-demo-client represent the realm and the client created on the Keycloak server respectively. CLIENTNAME describes the configuration of the oauth2-server within the Spring Boot application.

Key	Description	Example
server.port	Specifies the port on which the application will run	8080
spring.security.oauth2.client.registration.CLIENTNAME.client-id	The client ID assigned to this client by the OAuth2 authorization server	oauth2-demo-client
spring.security.oauth2.client.registration.CLIENTNAME.authorization-grant-type	The type of authorization grant to be used	authorization_code
spring.security.oauth2.client.registration.CLIENTNAME.scope	The OAuth2 scopes required for access	openid
spring.security.oauth2.client.registration.CLIENTNAME.redirect-uri	The URI to which the authorization server will redirect after authentication	http://localhost:8080/login/oauth2/code/oauth2-demo-client
spring.security.oauth2.client.provider.CLIENTNAME.logout-url	The URL to which the application should redirect for logout	http://localhost:8180/realms/oauth2-demo-realm/protocol/openid-connect/logout
spring.security.oauth2.client.provider.CLIENTNAME.issuer-uri	The URI of the OAuth2 identity provider (Keycloak in this case)	http://localhost:8180/realms/oauth2-demo-realm
spring.security.oauth2.client.provider.CLIENTNAME.user-name-attribute	The attribute in the JWT token that represents the user's preferred username	preferred_username
spring.security.oauth2.client.provider.CLIENTNAME.authorities.roles	The attribute/attributes chain in the JWT token that represents the user's roles	resource_access.oauth2-demo-client.roles

Deployment

Prerequisites

1. Java Development Kit (JDK) 17 - Download and install the JDK.
2. Apache Maven - Download and install the Maven build tool.
3. Keycloak - Ensure that Keycloak is set up and running.
4. Keycloak Realm and Client - Configure the Keycloak Realm and Client according to your application's requirements. Alternatively, load and use the configuration file from /test/resources/realm.json.

Deployment Steps

1. Download the project: Obtain the project folder. This folder should contain the pom.xml file and the project's source code.

2. Configure application.yml: Edit the application.yml file to configure your application's settings. Ensure that the Keycloak configuration (client ID, issuer URI, etc.) matches your Keycloak setup.

3. Build the project: Run the following command to build and package the project: mvn clean package. This command will download the required dependencies, compile the project, and package it into an executable JAR file. The final JAR file will be located in the directory target, and its name will be oauth2-1.0-SNAPSHOT.jar.

4. Run the application: Execute the following command: java -jar target/oauth2-1.0-SNAPSHOT.jar. This will start the Spring Boot application, and it will be accessible locally.

5. Access the application: Once the application is up and running, you can access it by opening a web browser and navigating to: http://localhost:8080/home. Ensure that the port matches the one specified in your application.yml file.

6. Authenticate via Keycloak: Your application will redirect you to the Keycloak login page for authentication. Log in using the credentials you've configured in Keycloak. The default credentials for the user John are john:john and for the user Admin admin:admin.

7. Access Protected Resources: After successful authentication, you can access the protected endpoints based on the roles and permissions granted through Keycloak.