Security Top

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:


Table of Contents

1. Overview

This article shows how to use Springs RestTemplate to consume a RESTful Service secured with Basic Authentication.

Once Basic Authentication is set up for the template, each request will be sent preemptively containing the full credentials necessary to perform the authentication process. The credentials will be encoded and will use the Authorization HTTP Header, in accordance with the specs of the Basic Authentication scheme. An example would look like this:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Further reading:

Spring RestTemplate Error Handling

Learn how to handle errors with Spring's RestTemplate

Using the Spring RestTemplate Interceptor

Learn about using interceptors in your Spring application with the RestTemplate.

Exploring the Spring Boot TestRestTemplate

Learn how to use the new TestRestTemplate in Spring Boot to test a simple API.

2. Setting up the RestTemplate

Bootstrapping the RestTemplate into the Spring context can be done by simply declaring a bean for it; however, setting up the RestTemplate with Basic Authentication will require manual intervention, so instead of declaring the bean directly, a Spring FactoryBean will be used for more flexibility. This factory will create and configure the template on initialization:

public class RestTemplateFactory
  implements FactoryBean<RestTemplate>, InitializingBean {
    private RestTemplate restTemplate;

    public RestTemplate getObject() {
        return restTemplate;
    public Class<RestTemplate> getObjectType() {
        return RestTemplate.class;
    public boolean isSingleton() {
        return true;

    public void afterPropertiesSet() {
        HttpHost host = new HttpHost("localhost", 8082, "http");
        restTemplate = new RestTemplate(
          new HttpComponentsClientHttpRequestFactoryBasicAuth(host));

The host and port values should be dependent on the environment – allowing the client the flexibility to define one set of values for integration testing and another for production use. The values can be managed by the first class Spring support for properties files.

3. Manual Management of the Authorization HTTP Header

The process of creating the Authorization header is relatively straightforward for Basic Authentication, so it can pretty much be done manually with a few lines of code:

HttpHeaders createHeaders(String username, String password){
   return new HttpHeaders() {{
         String auth = username + ":" + password;
         byte[] encodedAuth = Base64.encodeBase64( 
            auth.getBytes(Charset.forName("US-ASCII")) );
         String authHeader = "Basic " + new String( encodedAuth );
         set( "Authorization", authHeader );

Then, sending a request becomes just as simple:
 (uri, HttpMethod.POST, new HttpEntity<T>(createHeaders(username, password)), clazz);

4. Automatic Management of the Authorization HTTP Header

Both Spring 3.0 and 3.1 and now 4.x have very good support for the Apache HTTP libraries:

  • Spring 3.0, the CommonsClientHttpRequestFactory integrated with the now end-of-life'd HttpClient 3.x
  • Spring 3.1 introduced support for the current HttpClient 4.x via HttpComponentsClientHttpRequestFactory (support added in the JIRA SPR-6180)
  • Spring 4.0 introduced async support via the HttpComponentsAsyncClientHttpRequestFactory

Let's start setting things up with HttpClient 4 and Spring 4.

The RestTemplate will require an HTTP request factory – a factory that supports Basic Authentication – so far, so good. However, using the existing HttpComponentsClientHttpRequestFactory directly will prove to be difficult, as the architecture of RestTemplate was designed without good support for HttpContext – an instrumental piece of the puzzle. And so we'll need to subclass HttpComponentsClientHttpRequestFactory and override the createHttpContext method:

public class HttpComponentsClientHttpRequestFactoryBasicAuth 
  extends HttpComponentsClientHttpRequestFactory {

    HttpHost host;

    public HttpComponentsClientHttpRequestFactoryBasicAuth(HttpHost host) {
        super(); = host;

    protected HttpContext createHttpContext(HttpMethod httpMethod, URI uri) {
        return createHttpContext();
    private HttpContext createHttpContext() {
        AuthCache authCache = new BasicAuthCache();

        BasicScheme basicAuth = new BasicScheme();
        authCache.put(host, basicAuth);

        BasicHttpContext localcontext = new BasicHttpContext();
        localcontext.setAttribute(HttpClientContext.AUTH_CACHE, authCache);
        return localcontext;

It is here – in the creation of the HttpContext – that the basic authentication support is built in. As you can see, doing preemptive Basic Authentication with HttpClient 4.x is a bit of a burden: the authentication info is cached and the process of setting up this authentication cache is very manual and unintuitive.

And with that, everything is in place – the RestTemplate will now be able to support the Basic Authentication scheme just by adding a BasicAuthorizationInterceptor;

  new BasicAuthorizationInterceptor("username", "password"));

And the request:
  HttpMethod.GET, null, Foo.class);

For an in-depth discussion on how to secure the REST Service itself, check out this article.

5. Maven Dependencies

The following Maven dependencies are required for the RestTemplate itself and for the HttpClient library:



Optionally, if the HTTP Authorization header is constructed manually, then an additional library is required for the encoding support:


You will find the newest versions in the Maven repository.

6. Conclusion

Although the 3.x branch of development for Apache HttpClient has reached the end of life for a while now, and the Spring support for that version has been fully deprecated, much of the information that can be found on RestTemplate and security still doesn't account for the current HttpClient 4.x releases. This article is an attempt to change that through a detailed, step by step discussion on how to set up Basic Authentication with the RestTemplate and how to use it to consume a secured REST API.

To go beyond the code samples in the article with an implementation of both the consuming side, examined here, but also the actual RESTful Service, have a look at the project over on Github.

This is a Maven-based project, so it should be easy to import and run as it is.

Security bottom

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security 5:

Newest Most Voted
Inline Feedbacks
View all comments
rajan sellapan
rajan sellapan
5 years ago

Hello sir , where is the download link for the source code
please help

Eugen Paraschiv
5 years ago
Reply to  rajan sellapan

Hey Rajan – did you sign up through the link at the end of the article but haven’t received the code? Cheers,

marc smith
marc smith
4 years ago

Hi Eugen,
Can u pls share the source code for when i try to subscribe it sends me the ebook and not the source code…

Eugen Paraschiv
4 years ago
Reply to  marc smith

Hey Marc – to get the full project, sign-up via the link at the very end of the article – the one that says “check out the sample project…” – that should send you the zip. Or email me and I’ll send it over. Cheers,

4 years ago

I am consuming web service having token based authentication. how can I consume that one using Rest Template

Eugen Paraschiv
4 years ago
Reply to  satbir

Hey Satbir – I’m not entirely sure what you mean by “token basic authentication”. Are you talking about standard basic authentication or some token based solution? Cheers,

4 years ago

It is unbelievable how much boilerplate code is needed for just using basic authentication. I suggest using okhttp or unirest if you are free to use whatever library you want.

Chris L.
Chris L.
3 years ago

Please update to avoid deprecated types and methods. I am working on this, welcome expert guidance:

// Build a client with a credentials provider
CredentialsProvider credsProvider = new BasicCredentialsProvider();
new AuthScope(host, port),
new UsernamePasswordCredentials(user, pass));
HttpClientBuilder clientBuilder = HttpClientBuilder.create();
CloseableHttpClient httpClient = clientBuilder.setDefaultCredentialsProvider(credsProvider).build();

// Create request factory with our superpower client
final HttpHost httpHost = new HttpHost(host, port);
HttpComponentsClientHttpRequestFactoryBasicAuth requestFactory = new HttpComponentsClientHttpRequestFactoryBasicAuth(httpHost);

// Put the factory in the template
RestTemplate restTemplate = new RestTemplate();

Eugen Paraschiv
3 years ago
Reply to  Chris L.

Sure, thanks for the heads up – it’s on my list to update. Cheers,

Yvan Dupre
Yvan Dupre
3 years ago

cool will wait.

Ruslan Stelmachenko
Ruslan Stelmachenko
3 years ago

Since Spring 4.3.1 there is a simplier way using, which also is independent of underlying http client used in RestTemplate.

public class AppConfig {

public RestTemplate myRestTemplate(RestTemplateBuilder builder) {
return builder.basicAuthorization("login", "password").build();


But be careful to not use the same RestTemplage bean to send requests to foreign domains, because the interceptor will send basic authentication header with ANY http request sent using myRestTemplate bean. So if you need to send http requests without basic authentication, configure and use another RestTemplate bean configured without it.

Grzegorz Piwowarek
Grzegorz Piwowarek
3 years ago

Thanks, we will have a look and update the article!

Comments are closed on this article!