CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-apache-httpcomponents--httpclient

Apache HttpComponents Client is a library of components for building client side HTTP services

—

Pending
Overview
Eval results
Files

authentication.mddocs/

Authentication and Security

Apache HttpClient provides comprehensive authentication mechanisms including Basic, Digest, NTLM, and Kerberos authentication schemes, along with credential management and SSL/TLS support for secure communications.

Credentials and Authentication Scope

Credentials Interface

public interface Credentials {
    Principal getUserPrincipal();
    String getPassword();
}

Base interface for authentication credentials.

UsernamePasswordCredentials

public class UsernamePasswordCredentials implements Credentials {
    public UsernamePasswordCredentials(String userName, String password);
    public Principal getUserPrincipal();
    public String getPassword();
    public String getUserName();
}

Basic username/password credentials implementation.

UsernamePasswordCredentials credentials = new UsernamePasswordCredentials("username", "password");

NTCredentials

public class NTCredentials implements Credentials {
    public NTCredentials(String userName, String password, String workstation, String domain);
    public Principal getUserPrincipal();
    public String getPassword();
    public String getUserName();
    public String getDomain();
    public String getWorkstation();
}

Windows NT domain credentials for NTLM authentication.

NTCredentials ntCredentials = new NTCredentials("username", "password", "workstation", "domain");

KerberosCredentials

public class KerberosCredentials implements Credentials {
    public KerberosCredentials(GSSCredential gssCredential);
    public Principal getUserPrincipal();
    public String getPassword();
    public GSSCredential getGSSCredential();
}

Kerberos credentials for Kerberos authentication.

AuthScope

public class AuthScope {
    public static final AuthScope ANY;
    public static final String ANY_HOST;
    public static final int ANY_PORT;
    public static final String ANY_REALM;
    public static final String ANY_SCHEME;
    
    public AuthScope(String host, int port);
    public AuthScope(HttpHost host);
    public AuthScope(String host, int port, String realm);
    public AuthScope(String host, int port, String realm, String scheme);
    public String getHost();
    public int getPort();
    public String getRealm();
    public String getScheme();
    public int match(AuthScope that);
}

Defines the scope (host, port, realm, scheme) for which credentials are valid.

AuthScope authScope = new AuthScope("api.example.com", 443, "Protected Area", "basic");

Credentials Provider

CredentialsProvider Interface

public interface CredentialsProvider {
    void setCredentials(AuthScope authscope, Credentials credentials);
    Credentials getCredentials(AuthScope authscope);
    void clear();
}

Provider interface for managing authentication credentials.

BasicCredentialsProvider

public class BasicCredentialsProvider implements CredentialsProvider {
    public BasicCredentialsProvider();
    public void setCredentials(AuthScope authscope, Credentials credentials);
    public Credentials getCredentials(AuthScope authscope);
    public void clear();
}

Basic implementation of credentials provider.

CredentialsProvider credsProvider = new BasicCredentialsProvider();
credsProvider.setCredentials(
    new AuthScope("api.example.com", 80),
    new UsernamePasswordCredentials("user", "password")
);

CloseableHttpClient httpClient = HttpClients.custom()
    .setDefaultCredentialsProvider(credsProvider)
    .build();

SystemDefaultCredentialsProvider

public class SystemDefaultCredentialsProvider implements CredentialsProvider {
    public SystemDefaultCredentialsProvider();
    public void setCredentials(AuthScope authscope, Credentials credentials);
    public Credentials getCredentials(AuthScope authscope);
    public void clear();
}

Credentials provider that uses system properties and default credentials.

Authentication Schemes

AuthScheme Interface

public interface AuthScheme {
    void processChallenge(Header header) throws MalformedChallengeException;
    Header authenticate(Credentials credentials, HttpRequest request, HttpContext context) throws AuthenticationException;
    String getSchemeName();
    String getParameter(String name);
    String getRealm();
    boolean isConnectionBased();
    boolean isComplete();
}

Base interface for authentication schemes.

Authentication Scheme Registry

public final class AuthSchemeRegistry {
    public AuthSchemeRegistry();
    public void register(String name, AuthSchemeFactory factory);
    public void unregister(String name);
    public AuthScheme getAuthScheme(String name, HttpParams params) throws IllegalStateException;
    public List<String> getSchemeNames();
}

Registry for authentication scheme factories.

Authentication Scheme Providers

public interface AuthSchemeProvider {
    AuthScheme create(HttpContext context);
}

Provider interface for creating authentication schemes.

Registry<AuthSchemeProvider> authSchemeRegistry = RegistryBuilder.<AuthSchemeProvider>create()
    .register("basic", new BasicSchemeFactory())
    .register("digest", new DigestSchemeFactory())
    .register("ntlm", new NTLMSchemeFactory())
    .build();

CloseableHttpClient httpClient = HttpClients.custom()
    .setDefaultAuthSchemeRegistry(authSchemeRegistry)
    .build();

Authentication Cache

AuthCache Interface

public interface AuthCache {
    void put(HttpHost host, AuthScheme authScheme);
    AuthScheme get(HttpHost host);
    void remove(HttpHost host);
    void clear();
}

Cache for storing authentication schemes by host.

BasicAuthCache

public class BasicAuthCache implements AuthCache {
    public BasicAuthCache();
    public void put(HttpHost host, AuthScheme authScheme);
    public AuthScheme get(HttpHost host);
    public void remove(HttpHost host);
    public void clear();
}

Basic implementation of authentication cache.

AuthCache authCache = new BasicAuthCache();
BasicScheme basicAuth = new BasicScheme();
authCache.put(new HttpHost("api.example.com", 80, "http"), basicAuth);

HttpClientContext context = HttpClientContext.create();
context.setAuthCache(authCache);

HttpGet httpGet = new HttpGet("http://api.example.com/protected");
CloseableHttpResponse response = httpClient.execute(httpGet, context);

SSL/TLS Support

SSLContext Configuration

public class SSLContextBuilder {
    public static SSLContextBuilder create();
    public SSLContextBuilder useProtocol(String protocol);
    public SSLContextBuilder setSecureRandom(SecureRandom secureRandom);
    public SSLContextBuilder loadTrustMaterial(KeyStore truststore, TrustStrategy trustStrategy) throws NoSuchAlgorithmException, KeyStoreException;
    public SSLContextBuilder loadTrustMaterial(File file, char[] storePassword, TrustStrategy trustStrategy) throws NoSuchAlgorithmException, KeyStoreException, CertificateException, IOException;
    public SSLContextBuilder loadTrustMaterial(URL url, char[] storePassword, TrustStrategy trustStrategy) throws NoSuchAlgorithmException, KeyStoreException, CertificateException, IOException;
    public SSLContextBuilder loadKeyMaterial(KeyStore keystore, char[] keyPassword, PrivateKeyStrategy aliasStrategy) throws NoSuchAlgorithmException, KeyStoreException, UnrecoverableKeyException;
    public SSLContextBuilder loadKeyMaterial(File file, char[] storePassword, char[] keyPassword, PrivateKeyStrategy aliasStrategy) throws NoSuchAlgorithmException, KeyStoreException, UnrecoverableKeyException, CertificateException, IOException;
    public SSLContext build() throws NoSuchAlgorithmException, KeyManagementException;
}

Builder for creating SSL contexts with custom trust and key material.

SSLContext sslContext = SSLContextBuilder.create()
    .loadTrustMaterial(new File("truststore.jks"), "password".toCharArray())
    .loadKeyMaterial(new File("keystore.jks"), "password".toCharArray(), "keypassword".toCharArray())
    .build();

CloseableHttpClient httpClient = HttpClients.custom()
    .setSSLContext(sslContext)
    .build();

SSL Connection Socket Factory

public class SSLConnectionSocketFactory implements LayeredConnectionSocketFactory {
    public static final String TLS;
    public static final String SSL;
    public static SSLConnectionSocketFactory getSocketFactory();
    public static SSLConnectionSocketFactory getSystemSocketFactory();
    
    public SSLConnectionSocketFactory(SSLContext sslContext);
    public SSLConnectionSocketFactory(SSLContext sslContext, HostnameVerifier hostnameVerifier);
    public SSLConnectionSocketFactory(SSLContext sslContext, String[] supportedProtocols, String[] supportedCipherSuites, HostnameVerifier hostnameVerifier);
}

Socket factory for SSL/TLS connections with configurable protocols and cipher suites.

SSLConnectionSocketFactory sslConnectionFactory = new SSLConnectionSocketFactory(
    sslContext,
    new String[]{"TLSv1.2", "TLSv1.3"},
    null,
    SSLConnectionSocketFactory.getDefaultHostnameVerifier()
);

Registry<ConnectionSocketFactory> socketFactoryRegistry = RegistryBuilder.<ConnectionSocketFactory>create()
    .register("http", PlainConnectionSocketFactory.getSocketFactory())
    .register("https", sslConnectionFactory)
    .build();

PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager(socketFactoryRegistry);
CloseableHttpClient httpClient = HttpClients.custom()
    .setConnectionManager(cm)
    .build();

Hostname Verification

public interface HostnameVerifier {
    boolean verify(String hostname, SSLSession session);
}

Interface for hostname verification in SSL connections.

HostnameVerifier hostnameVerifier = new HostnameVerifier() {
    @Override
    public boolean verify(String hostname, SSLSession session) {
        // Custom hostname verification logic
        return hostname.endsWith(".example.com");
    }
};

SSLConnectionSocketFactory sslSocketFactory = new SSLConnectionSocketFactory(
    sslContext,
    hostnameVerifier
);

Authentication Strategies

AuthenticationStrategy Interface

public interface AuthenticationStrategy {
    boolean isAuthenticationRequested(HttpHost authhost, HttpResponse response, HttpContext context);
    Queue<AuthOption> select(Map<String, Header> challenges, HttpHost authhost, HttpResponse response, HttpContext context) throws MalformedChallengeException;
    void authSucceeded(HttpHost authhost, AuthScheme authScheme, HttpContext context);
    void authFailed(HttpHost authhost, AuthScheme authScheme, HttpContext context);
}

Strategy interface for handling authentication challenges.

Target and Proxy Authentication

public class TargetAuthenticationStrategy implements AuthenticationStrategy;
public class ProxyAuthenticationStrategy implements AuthenticationStrategy;

Specific strategies for target server and proxy authentication.

Authentication Context

HttpClientContext

public class HttpClientContext extends HttpCoreContext {
    public static HttpClientContext create();
    public void setCredentialsProvider(CredentialsProvider credentialsProvider);
    public CredentialsProvider getCredentialsProvider();
    public void setAuthCache(AuthCache authCache);
    public AuthCache getAuthCache();
    public void setAuthSchemeRegistry(Lookup<AuthSchemeProvider> authSchemeRegistry);
    public Lookup<AuthSchemeProvider> getAuthSchemeRegistry();
}

HTTP context with authentication-specific properties.

HttpClientContext context = HttpClientContext.create();
context.setCredentialsProvider(credentialsProvider);
context.setAuthCache(authCache);

HttpGet httpGet = new HttpGet("https://api.example.com/protected");
CloseableHttpResponse response = httpClient.execute(httpGet, context);

Types

AuthOption

public final class AuthOption {
    public AuthOption(AuthScheme authScheme, Credentials creds);
    public AuthScheme getAuthScheme();
    public Credentials getCredentials();
}

Represents an authentication option with scheme and credentials.

AuthState

public class AuthState {
    public void reset();
    public void setState(AuthProtocolState state);
    public AuthProtocolState getState();
    public void update(AuthScheme authScheme, Credentials creds);
    public AuthScheme getAuthScheme();
    public Credentials getCredentials();
    public void invalidate();
    public boolean isValid();
}

Maintains the state of an authentication process.

Principal Classes

public class BasicUserPrincipal implements Principal {
    public BasicUserPrincipal(String username);
    public String getName();
}

public class NTUserPrincipal implements Principal {
    public NTUserPrincipal(String domain, String username);
    public String getName();
    public String getDomain();
    public String getUsername();
}

Principal implementations for different authentication types.

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-httpcomponents--httpclient

docs

authentication.md

client-configuration.md

connection-management.md

cookie-management.md

http-methods.md

index.md

response-handling.md

tile.json