Skip to main content
Version: 7.2405.x.x LTS

Appendix H - Migrating HTTP clients and auth states 4.38.0.12

All HTTP clients in nevisAuth have been replaced with a new http client implementation. The benefits of the new client are:

  • More configuration flexibility such as individual truststore configuration for each http client
  • Support for JVM default truststore containing root-CA signed certificates
  • Aligned configuration properties - all http client have the same configuration properties
  • Easier implementation of groovy script states and custom auth states with clear APIs

Affected AuthStates

The following auth states are affected by this change:

All auth states:

  • The Java default Root-CA certificates are now also loaded additionally.
caution

Where the new properties are listed precisely, only those are available. Some auth states are using the JAX-WS soap clients where not all httpclient.* properties are applicable.

Significant Changes

  • HTTP Content-type header - space between content type and charset

    Be aware that the Apache HTTP Client 5 used introduces a space in the HTTP content-type header between the content type and the charset which is allowed according to the HTTP header specification.

    Example HTTP content-type header
    application/json; charset=UTF-8
  • Http response decoding by default is done using UTF-8 charset.

  • Key- and truststore configurations based on files are no longer supported, only references configured in the esauth4.xml file are supported.

  • All properties support variable substitution (${...})

  • Groovy script states should migrate to the new http client, specifically for connections relying on the default JVM truststore / using root-CA signed certificates

    HTTP Clients
    ch.nevis.esauth.util.httpclient.api.HttpRequest#send() 
    ch.nevis.esauth.util.httpclient.api.HttpRequest#send(HttpClient httpClient)

Old AuthHttpClient & TokenAuthHttpClient configuration properties

Removed propertyReplacement
hostspecify in the HTTP request
portspecify in the HTTP request
protocolspecify in the HTTP request
usernamehttpclient.authorization.basic.username
passwordhttpclient.authorization.basic.password
credTypenone
realmnone
workstationnone
proxyHosthttpclient.proxy.host
proxyPorthttpclient.proxy.port
proxyUsernamehttpclient.proxy.username
proxyPasswordhttpclient.proxy.password
proxyCredTypenone
proxyRealmnone
proxyWorkstationnone
http.socket.timeoutnone
http.connection.timeouthttpclient.connection.timeout
http.connection-manager.max-per-hosthttpclient.connection.pool.maxPerRoute
http.connection-manager.max-totalhttpclient.connection.pool.maxTotal
truststorehttpclient.tls.trustStoreRef
truststorePasswdnone
truststoreTypenone
keystorehttpclient.tls.keyObjectRef
keystorePasswdnone
keystoreTypenone
checkHostnamehttpclient.tls.hostnameVerification
token.userIdhttpclient.authorization.basic.sectoken.userId
token.profileIdhttpclient.authorization.basic.sectoken.profileId
token.roleshttpclient.authorization.basic.sectoken.roles

New HttpClient Configuration

For documentation of the new HttpClient and it's configuration options check here.

New HttpClient API documentation

For documentation of the public APIs provided by the new HttpClient, see HttpClient API documentation.

Solutions to common issues

Certificate / TLS connection issues

  • Check whether your httpclient.tls.trustStoreRef and httpclient.tlskeyObjectRef settings are correct. Be aware that without specifying them, the HTTP client will use the default JVM truststore and certificate validation as well as hostname verification are enabled by default.
  • If you are relying on certificates you manually added to the default JVM truststore or have overridden the JVM default truststore with the -Djavax.net.ssl.trustStore property you may solve the issue by configuring a httpclient.tls.keyObjectRef in the auth state containing the certificate. For example in the Mobile Signature Auth State configuring the service.httpclient.tls.keyObjectRef property.

Custom AuthStates - compilation issues

In case your custom auth states rely on parts of the old Apache HTTP Client, you will likely experience compilation issues as the classpath has changed between the two major versions:

Apache HTTP Client 4 classpath
org.apache.http
Apache HTTP Client 5 classpath
org.apache.hc.httpclient5
caution

We urge you not to use any classes provided by Apache HTTP Client 5. Use the nevisAuth API provided under the package ch.nevis.esauth.util.httpclient.api.

Custom AuthStates - classpath conflicts

In the unlikely scenario that you experience classpath issues during nevisAuth startup (for example for custom AuthStates), we recommend supplying the necessary 3rd party libraries via the plugin directory and ensuring via auth state configuration that your dependencies are loaded before the nevisAuth dependencies by setting the auth state class loading strategy to PARENT_LAST, refer to the Developer Guide for details.