The Quarkus REST Client makes it easy to consume RESTful services with built-in support for authentication mechanisms like Basic Authentication. One of the annotations Quarkus provides to simplify this process is @ClientBasicAuth. Let us delve into understanding the Quarkus REST Client with @ClientBasicAuth.
1. Introduction
When interacting with external services through REST APIs, security is a crucial concern. Basic Authentication (Basic Auth) is a simple, yet widely used, mechanism to authenticate REST API requests. Quarkus simplifies the integration with Basic Auth by using @ClientBasicAuth, which automatically adds the required authentication headers to requests made by the REST client.
1.1 Benefits of @ClientBasicAuth annotation
- Simplifies Basic Authentication configuration for REST clients.
- Reduces boilerplate code by avoiding manual authentication setup.
- Enables secure communication with RESTful services by handling authentication automatically.
- Easy to integrate with Quarkus REST Client, providing seamless security.
- Improves code readability and maintainability with declarative authentication.
1.2 Where not to use @ClientBasicAuth annotation
- Non-Basic Authentication Scenarios: If your service requires more advanced authentication methods like OAuth2, JWT, or API keys, @ClientBasicAuth would not be suitable.
- Highly Sensitive Environments: In environments where Basic Authentication might not be secure enough (due to lack of encryption), it’s better to avoid @ClientBasicAuth unless used over HTTPS.
- Public or Open APIs: For public APIs that don’t require authentication or use token-based authentication, Basic Authentication is unnecessary and should be avoided.
- Complex Authentication Flows: If the authentication involves complex flows such as multi-factor authentication or token refresh, @ClientBasicAuth would not support these advanced requirements.
- Microservices Communication with Token Authentication: In microservices architectures, if communication happens via token-based authentication (e.g., OAuth2), Basic Authentication isn’t appropriate.
2. Setup Protected Services
To use @ClientBasicAuth, we need to interact with a service that is protected by Basic Authentication. Let’s assume we are building a client that interacts with a third-party service that requires a username and password for authentication.
2.1 Example Protected Service
GET /api/data
Authorization: Basic
Response: 200 OK
{
"message": "Protected data access successful"
}
The service expects an authorization header with the format Authorization: Basic <base64-encoded-credentials>, where the credentials are the Base64-encoded combination of the username and password.
3. RestClientBuilder and @ClientBasicAuth
Quarkus REST Client allows us to create an HTTP client with Basic Auth quickly using annotations. Here’s how to set it up:
3.1 Step-by-Step Code Example
First, define the interface for the REST client.
// MyServiceClient.java
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.eclipse.microprofile.rest.client.annotation.ClientBasicAuth;
import org.eclipse.microprofile.rest.client.annotation.ClientHeaderParam;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
@Path("/api")
@RegisterRestClient
@ClientBasicAuth
public interface MyServiceClient {
@GET
@Path("/data")
@Produces(MediaType.APPLICATION_JSON)
String getData();
}
In the above example, the @ClientBasicAuth annotation is applied at the interface level. This tells Quarkus to automatically include Basic Auth credentials when making requests to the service.
3.2 Setting up Configuration
We need to configure the username and password in the application.properties file. Quarkus will inject these credentials into the client automatically.
# application.properties quarkus.rest-client.\"com.example.MyServiceClient\".url=http://localhost:8080 quarkus.rest-client.\"com.example.MyServiceClient\".basic-auth.username=myuser quarkus.rest-client.\"com.example.MyServiceClient\".basic-auth.password=mypassword
Here, the username and password are specified for the MyServiceClient REST client. Quarkus will handle the Base64 encoding and automatically add the Authorization header to each request.
3.3 Using the Client in a Service
Now, let’s use the REST client in a Quarkus service.
// MyService.java
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import org.eclipse.microprofile.rest.client.inject.RestClient;
@Path("/consume")
public class MyService {
@Inject @RestClient MyServiceClient myServiceClient;
@GET
public String fetchData() {
return myServiceClient.getData();
}
}
Here, we’re injecting the REST client using @RestClient and calling the getData() method to fetch the protected data.
3.4 Code Output
When the /consume endpoint is accessed, the following request is made:
GET /consume
Response: 200 OK
{
"message": "Protected data access successful"
}
4. Conclusion
In this article, we covered how to use @ClientBasicAuth in Quarkus to handle Basic Authentication for REST clients. We set up a protected service, configured the REST client with Basic Auth, and demonstrated how to use it in a Quarkus application. Quarkus simplifies security by handling the heavy lifting, such as encoding credentials and adding headers, making it easy to interact with secure APIs.
