Controlling the Assertion Consumer Service URLs

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.

1. The user makes a request to https://sp.example.com/oa/auth/rcv
   
   
2. 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.