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:

• IDM authentication plug-ins and auth states
  • New configuration options:
    • httpclient.tls.hostnameVerification
    • httpclient.tls.keyObjectRef
    • httpclient.tls.trustStoreRef
• IdmRestClient in the ScriptState
  • New configuration options:
    • idm.httpclient.*
  • Initialization of the client changed: from new IdmRestClientFactory().getInstance() to IdmRestClientFactory.get(parameters). See example.
• FIDO auth states: OutOfBandFidoUafAuthState and FidoUafAuthState
  • Removed properties:
    • trustStoreRef
    • keyStoreRef
    • keyObjectRef
  • New configuration options
    • httpclient.*
• nevisAdapt auth states:
  • NevisAdaptAuthState, NevisAdaptSessionApprovalAuthState, NevisAdaptSessionTerminationAuthState, NevisAdaptRememberMeAuthState, RememberMeTokenDeletionAuthState
    • Removed properties:
      • http.client.keyStore
      • http.client.keyStorePassword
      • http.client.trustStore
      • http.client.trustStorePassword
    • New configuration options:
      • httpclient.*
• AccessTokenConsumer
  • Removed properties:
    • See the AuthHttpClient configurations
  • New configuration options:
    • httpclient.*
• AssertionRequestState
  • Removed properties:
    • soap.proxy
    • ... See the AuthHttpClient configurations
  • New configuration options:
    • soap.httpclient.*
• AuthorizationServer
  • Removed properties:
    • nevismeta.http.connection.timeout
    • nevismeta.http.socket.timeout
    • ... See the AuthHttpClient configurations
    • nevismeta.http.protocol.content-charset
  • Response parsing is done using UTF-8 instead of previous default ISO-8859-1.
  • New configuration options:
    • nevismeta.httpclient.*
• ConditionalDocumentProcessor
  • FTP support is removed
  • Removed properties:
    • See the AuthHttpClient configurations
  • New configuration options:
    • httpclient.*
• ConsentState
  • Removed properties:
    • nevismeta.http.connection.timeout
    • nevismeta.http.socket.timeout
    • ... See the AuthHttpClient configurations
  • New configuration options:
    • nevismeta.httpclient.*
• DocumentProcessor
  • FTP support is removed
  • Property parser.schema only support file system access.
  • Removed properties:
    • See the AuthHttpClient configurations
  • New configuration options:
    • httpclient.*
• IdentityProviderState
  • Removed properties:
    • soap.* See the AuthHttpClient configurations
  • New configuration options:
    • soap.httpclient.*
• MobileSignatureState
  • Removed properties:
    • service.proxy.*
    • service.ssl.*
  • New configuration options:
    • service.httpclient.proxy.host
    • service.httpclient.proxy.port
    • service.httpclient.tls.trustStoreRef
    • service.httpclient.tls.keyObjectRef
    • service.httpclient.tls.hostnameVerification
• OAuth2ClientState
  • New configuration options:
    • httpclient.*
• OIDCProviderMetadataFetcherState
  • New configuration options:
    • httpclient.*
• RelyingPartyState
  • New configuration options:
    • httpclient.*
• ScriptState
  • Apache HttpClient version 4 is removed from nevisAuth, ScriptStates using that will no longer compile, it is recommended to migrate to our new HttpClient Api.
  • New configuration options for on demand created HttpClients:
    • parameter.httpclient.*
• ServiceProviderState
  • Removed properties:
    • soap.* See the AuthHttpClient configurations
  • New configuration options:
    • soap.httpclient.*
• SecurityTokenServiceClient
  • Removed properties:
    • service.proxy.*
    • service.ssl.*
  • New configuration options:
    • service.httpclient.proxy.host
    • service.httpclient.proxy.port
    • service.httpclient.tls.trustStoreRef
    • service.httpclient.tls.keyObjectRef
    • service.httpclient.tls.hostnameVerification
• TanState - AspSmsOverSoapChannel
  • Deprecated
  • Removed properties:
    • proxyHost
    • proxyPort
    • nonProxyHosts
  • New configuration options:
    • httpclient.proxy.host
    • httpclient.proxy.port
    • httpclient.tls.trustStoreRef
    • httpclient.tls.keyObjectRef
    • httpclient.tls.hostnameVerification
• TanState - HTTPChannel
  • Removed properties:
    • See the AuthHttpClient configurations
  • New configuration options:
    • httpclient.*
• TanState - SwissphoneChannel
  • Removed properties:
    • trustStorePath
    • trustStorePassword
    • proxyHostname
    • proxyPort
    • proxyUsername
    • proxyPassword
    • proxyRealm
    • proxyWorkstation
    • http.socket.timeout
    • http.connection.timeout
    • http.connection-manager.max-per-host
    • http.connection-manager.max-total
  • New configuration options:
    • httpclient.*
• UserinfoClientState
  • New configuration options:
    • httpclient.*
• X509Login - HTTP and OCSP suppliers
  • Removed properties:
    • httpclient.*
    • ... See the AuthHttpClient configurations
  • New configuration options:
    • httpclient.*

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 property	Replacement
host	specify in the HTTP request
port	specify in the HTTP request
protocol	specify in the HTTP request
username	httpclient.authorization.basic.username
password	httpclient.authorization.basic.password
credType	none
realm	none
workstation	none
proxyHost	httpclient.proxy.host
proxyPort	httpclient.proxy.port
proxyUsername	httpclient.proxy.username
proxyPassword	httpclient.proxy.password
proxyCredType	none
proxyRealm	none
proxyWorkstation	none
http.socket.timeout	none
http.connection.timeout	httpclient.connection.timeout
http.connection-manager.max-per-host	httpclient.connection.pool.maxPerRoute
http.connection-manager.max-total	httpclient.connection.pool.maxTotal
truststore	httpclient.tls.trustStoreRef
truststorePasswd	none
truststoreType	none
keystore	httpclient.tls.keyObjectRef
keystorePasswd	none
keystoreType	none
checkHostname	httpclient.tls.hostnameVerification
token.userId	httpclient.authorization.basic.sectoken.userId
token.profileId	httpclient.authorization.basic.sectoken.profileId
token.roles	httpclient.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.