Introduction
The web.xml
now supports a number of context-param[s]
which allow you to control the value of the AssertionConsumerService URLs used by atacama-java
.
Typical examples of situations where you might wish to use this is where you are using a load balancer to receive the request, or the service is behind some form of proxy. This would result in problems with requests being re-written to the web server (rather than the load balancer) unless you set context parameters shown below. There is an example at the end of the page.
Context parameters
Use canonical hostname
Directive: OA_USE_CANONICAL_HOSTNAME
Value: True|False
Default: True
Description: When set to true the ServerModule will attempt to obtain the canonical hostname via DNS. When set to false the hostname will be obtained from the HOST header value contained in the client request.
(Will be overridden by OA_OVERRIDE_HOSTNAME
if set)
E.g:
<context-param> <param-name>OA_USE_CANONICAL_HOSTNAME</param-name> <param-value>false</param-value> </context-param>
Override hostname
Directive: OA_OVERRIDE_HOSTNAME
Value: text, e.g: overridden.com
Default: none
Description: When specified this value will be used as the hostname.
E.g:
<context-param> <param-name>OA_OVERRIDE_HOSTNAME</param-name> <param-value>overriden.com</param-value> </context-param>
Override schema
Directive: OA_OVERRIDE_SCHEME
Value: http|https
Default: none
Description: When specified this value will be used as the schema.
(The default port for the given schema will be applied unless the OA_OVERRIDE_PORT
has been specified)
E.g:
<context-param> <param-name>OA_OVERRIDE_SCHEME</param-name> <param-value>http</param-value> </context-param>
Override port
Directive: OA_OVERRIDE_PORT
Value: An integer between 1 and 65535
Default: none
Description: When specified this value will be used as the port.
E.g:
<context-param> <param-name>OA_OVERRIDE_PORT</param-name> <param-value>8080</param-value> </context-param>
Example use case
These directives are useful when Service Providers wish to run atacama-java behind a load balancer or proxy.
- The user makes a request to https://sp.example.com/oa/auth/rcv
- This request is handled by the load balancer which passes the request to one of the back end servers. This will normally result in the request being rewritten to the web server (e.g. http://10.0.0.1:8080/oa/auth/rcv). The change of host, port and schema will cause the response obtained from the users identity provider to be discarded.
This can be fixed by adding the following to the web.xml:
<context-param> <param-name>OA_OVERRIDE_HOSTNAME</param-name> <param-value>sp.example.com</param-value> </context-param> <context-param> <param-name>OA_OVERRIDE_SCHEME</param-name> <param-value>https</param-value> </context-param>
We don't need to override the port in this case because the default https port (443) will be assumed based on the schema override.