LS Price Increase Launch

The Price of all “Learn Spring” course packages will increase by $40 on next Friday:

>> GET ACCESS NOW

1. Overview

Keycloak is an open-source identity and access management server that secures our modern applications (like SPAs, mobile apps, APIs, etc.). Keycloak supports industry-standard protocols like Security Assertion Markup Language (SAML) 2.0, Single Sign-On (SSO), and OpenID Connect (OIDC).

Further, in this tutorial, we'll learn how to leverage Keycloak to authenticate and authorize SOAP web services using OIDC (OpenID Connect).

2. Develop a SOAP Web Service

Briefly, Let's learn how to build a SOAP web service using Spring Boot.

2.1. The Web Service Operations

Straightaway, let's define the operations:

  • getProductDetails: Returns product details for a given product ID. Also, let's assume that a user with a user role can request this operation.
  • deleteProduct: Deletes a product for a given product ID. Also, only a user with admin can request this operation.

We have defined two operations and an RBAC (Role-based access control).

2.2. Define XSD

Above all, let's define a product.xsd:

<xs:element name="getProductDetailsRequest">
    ...
</xs:element>
<xs:element name="deleteProductRequest">
    ...
</xs:element>
    ...
</xs:schema>

Also, let's add wsdl4j and Spring Boot Webservices dependencies:

<dependency>
    <groupId>wsdl4j</groupId>
    <artifactId>wsdl4j</artifactId>
    <version>1.6.3</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web-services</artifactId>
    <version>2.5.4</version>
</dependency>

2.3. Web Service

Further, let's develop a SOAP web service.

@PayloadRoot(namespace = "http://www.baeldung.com/springbootsoap/keycloak", localPart = "getProductDetailsRequest")
@ResponsePayload
public GetProductDetailsResponse getProductDetails(@RequestPayload GetProductDetailsRequest request) {
    ...
}
@PayloadRoot(namespace = "http://www.baeldung.com/springbootsoap/keycloak", localPart = "deleteProductRequest")
@ResponsePayload
public DeleteProductResponse deleteProduct(@RequestPayload DeleteProductRequest request) {
    ...
}

We can test this web service using several tools like cURL, Postman, SOAPUI, etc. Henceforth, let's see how to secure our SOAP web service.

3. Configuring Keycloak

To begin with, let's configure Keycloak to secure our web service using OpenId Connect.

3.1. Create a Client

Typically, a Client is an application that requires Keycloaks's authentication service. Also, while creating the client, choose:

  • Application URL as the Root URL
  • openid-connect as the Client Protocol
  • Confidential as Access Type
  • Turn on Authorization Enabled and Service Account Enabled

Furthermore, enabling Service Accounts allows our application (the client) to authenticate with Keycloak. Subsequently, it provides the Client Credentials Grant type flow to our authentication flow:

 

Finally, click Save and then click on the Credentials tab and make a note of the secret. Consequently, we'll need it as part of the Spring Boot configuration.

3.2. Users and Roles

Next, Let's create two users and assign them the roles and passwords:

 

Firstly, let's create the roles, admin and user. Keycloak allows us to create two kinds of roles – Realm Roles and Client Roles. First, however, let's create Client Roles.

Click on Clients, choose the client and click on the Roles tab. Then, create two roles, admin and user:

 

Though Keycloak can fetch the users from LDAP or AD (Active Directory), to keep things simple, let's manually configure the users and assign them the roles.

Let's create two users. First, we click on Users, then Add User :

 

Now, let's allocate roles to the users.

Again, click on Users choose the user and click on Edit, then click Role Mappings tab, select the client from the Client Roles, and select a role on Available Roles. Let's assign the admin role to one user and the user role to another use:

 

4. Spring Boot Configuration

Similarly, let's secure our SOAP web services.

4.1. Keycloak – Spring Boot Integration

Firstly, let's add Keycloak dependencies.

Keycloak provides an adapter that utilizes Spring Boot's auto-configuration and makes the integration easy. Now, let's update our dependencies to include this Keycloak adapter:

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-spring-boot-starter</artifactId>
    <version>15.0.2</version>			
</dependency>

Next, let's add the Keycloak configuration to our application.properties:

keycloak.enabled=true
keycloak.realm=baeldung-soap-services
keycloak.auth-server-url=http://localhost:8080/auth
keycloak.bearer-only=true
keycloak.credentials.secret=14da6f9e-261f-489a-9bf0-1441e4a9ddc4
keycloak.ssl-required=external
keycloak.resource=baeldung-soap-services
keycloak.use-resource-role-mappings=true

From the Keycloak documentation:

  • keycloak.enabled: Allow enabling of Keycloak Spring Boot adapter by configuration. The default value is true.
  • keycloak.realm: Keycloak realm name and is mandatory
  • keycloak.auth-server-url: The base URL is mandatory, and it's of the Keycloak server. Typically, this is of the form http(s)://host:port/auth
  • keycloak.bearer-only: While the default value is false, set it to true for the adapter to validate the tokens.
  • keycloak.credentials. secret: The mandatory client-secret as configured in Keycloak
  • keycloak.ssl-required: The default value is external. In other words, all the external requests (other than localhost) should be on the https protocol.
  • keycloak.resource: The mandatory client-id of the application
  • keycloak.use-resource-role-mappings: While the default is false, set it to true for the adapter to look inside the token for application-level role mappings for the user.

4.2. Enable Global Method Security

Besides the previous configurations, we need to specify security constraints to secure our web services. These constraints allow us to restrict unauthorized access. For instance, we should limit a user from admin actions.

There are two ways to set up the constraints:

  1. Declare security-constraints and security-collections in the application configuration file.
  2. Method-level security using @EnableGlobalMethodSecurity.

For SOAP web services, security-constraints fall short in providing fine-grained control. Moreover, declaring these constraints is verbose.

Henceforth, let's leverage the power of @EnableGlobalMethodSecurity to secure our SOAP web service operations.

4.3. Defining a KeycloakWebSecurityConfigurerAdapter

KeycloakWebSecurityConfigurerAdapter is an optional convenient class that extends WebSecurityConfigurerAdapter and simplifies security context configuration. Further, let's define a class KeycloakSecurityConfig that extends this adapter and makes use of @EnableGlobalMethodSecurity.

The class diagram that depicts this hierarchy:

Now, let's configure KeycloakSecurityConfig class:

@KeycloakConfiguration
@EnableGlobalMethodSecurity(jsr250Enabled = true)
public class KeycloakSecurityConfig extends KeycloakWebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        http
          .csrf()
          .disable()
          .authorizeRequests()
          .anyRequest()
          .permitAll();
    }
}

@KeycloakConfiguration defines all the required annotations for Keycloak's integration with Spring Boot:

4.4. Adding Authorization

Finally, let's use @RolesAllowed annotation (part of JSR-250) to authorize our SOAP web service operations.

Given that, let's configure our methods with access roles. To do this, let's use the @RolesAllowed annotation. Recall, we defined two different roles, user and admin, in Keycloak. Let's define each of our web services with a role:

@RolesAllowed("user")
@PayloadRoot(namespace = "http://www.baeldung.com/springbootsoap/keycloak", localPart = "getProductDetailsRequest")
@ResponsePayload
public GetProductDetailsResponse getProductDetails(@RequestPayload GetProductDetailsRequest request) {
    ...
}
@RolesAllowed("admin")
@PayloadRoot(namespace = "http://www.baeldung.com/springbootsoap/keycloak", localPart = "deleteProductRequest")
@ResponsePayload
public DeleteProductResponse deleteProduct(@RequestPayload DeleteProductRequest request) {
    ...
}

With this, we completed the configuration.

5. Test the Application

5.1. Check the Setup

Now that the application is ready, let's start testing our SOAP web services using curl:

curl -d @request.xml -i -o -X POST --header 'Content-Type: text/xml' http://localhost:18080/ws/api/v1

Eventually, if all the configurations are correct, we get an access denied response:

<SOAP-ENV:Fault>
    <faultcode>SOAP-ENV:Server</faultcode>
    <faultstring xml:lang="en">Access is denied</faultstring>
</SOAP-ENV:Fault>

As expected, Keycloak denies the request as the request does not contain an access token.

5.2. Acquiring Access Token

At this point, let's get an access token from Keycloak to access our SOAP web services. Typically, the flow involves:

 

  • Firstly, a user sends his credentials to the application
  • The application passes client-id and client-secret along with these credentials to the Keycloak server.
  • Finally, Keycloak returns an access token, refresh token, and other meta-data based on user credentials and roles.

Keycloak exposes a token endpoint for the clients to request access tokens.  Typically, this endpoint is of the form:

<PROTOCOL>://<HOST>:<PORT>/auth/realms/<REALM_NAME>/protocol/openid-connect/token

For example:

http://localhost:8080/auth/realms/baeldung/protocol/openid-connect/token

Now, let's obtain the access token:

curl -L -X POST 'http://localhost:8080/auth/realms/baeldung-soap-services/protocol/openid-connect/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=baeldung-soap-services' \
--data-urlencode 'client_secret=14da6f9e-261f-489a-9bf0-1441e4a9ddc4' \
--data-urlencode 'username=janedoe' \
--data-urlencode 'password=password'

In effect, we get an access token and refresh token along with meta-data:

{
    "access_token": "eyJh ...",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJh ...",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "364b8f3e-34ff-4ca0-8895-bfbdb8b466d4",
    "scope": "profile email"
}

Additionally, the configurable expires_in key defines the lifetime of this token. For instance, the above access token expires in 5 minutes (300 seconds).

5.3. Webservice Invocation with Access Token

In this example, let's use the access token we retrieved in the previous section. Let's invoke the SOAP web service with the access token as a Bearer Token.

curl -d @request.xml -i -o -X POST -H 'Authorization: Bearer BwcYg94bGV9TLKH8i2Q' \
  -H 'Content-Type: text/xml' http://localhost:18080/ws/api/v1

With the correct access token, the response is:

<ns2:getProductDetailsResponse xmlns:ns2="http://www.baeldung.com/springbootsoap/keycloak">
    <ns2:product>
        <ns2:id>1</ns2:id>
            ...
        </ns2:product>
</ns2:getProductDetailsResponse>

5.4. Authorization

Recall that we generated the access token for the user janedoe that has a user role. With the user access token, let's try to perform admin operations. That is, let's try to invoke deleteProduct:

curl -d @request.xml -i -o -X POST -H 'Authorization: Bearer sSgGNZ3KbMMTQ' -H 'Content-Type: text/xml' \
  http://localhost:18080/ws/api/v1

where contents of request.xml are:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:key="http://www.baeldung.com/springbootsoap/keycloak">
    <soapenv:Header/>
    <soapenv:Body>
        <key:deleteProductRequest>
            <key:id>1</key:id>
        </key:deleteProductRequest>
   </soapenv:Body>
</soapenv:Envelope>

Since a user is not unauthorized to access the admin operations, we get an access denied:

<SOAP-ENV:Fault>
    <faultcode>SOAP-ENV:Server</faultcode>
        <faultstring xml:lang="en">Access is denied</faultstring>
</SOAP-ENV:Fault>

6. Conclusion

This tutorial showed how to develop a SOAP web service, keycloak configurations, and secure our web services using Keycloak. The way we secure REST web services, we have to secure our SOAP web services from suspicious users and unauthorized access.

As always, the complete source code is available over on GitHub.

LS Price Increase Launch

The Price of all “Learn Spring” course packages will increase by $40 on next Friday:

>> GET ACCESS NOW
Security footer banner
guest
0 Comments
Inline Feedbacks
View all comments