How to set up multiple DAUI instances

Let’s start at the beginning: what is the DAUI exactly?

The DAUI (Distributive Authentication User Interface) is basically a small subset of the OpenAM server UI containing simple login logic, which basically just receives authentication requests from the users and forwards those requests to the core OpenAM servers. For this the DAUI is using the ClientSDK, especially the underlying JAX-RPC interfaces. Now that we know this, let’s see the pros and cons for using DAUI.

Advantages:

  • Hides sensitive parts of the OpenAM server
  • Lowers the load on the actual core servers

Disadventages:

  • Adds one more component which could break
  • Has no federation capability

How to set up a DAUI instance

This tutorial requires that you have an OpenAM instance already deployed and configured on your favorite application server. If you’re not sure how to do that, please read Mark’s great article about it.
In order to install a DAUI instance you’re going to need to take the following steps:

  • Download the OpenAM zip distribution from the OpenAM download page and extract into ~/install directory.
  • Execute the following commands:
    cd ~/install/deployable-war
    mkdir temp # Create a temporary directory
    cp openam.war temp # Copy the WAR file into it
    cd temp
    jar xf openam.war # Extract the content of the WAR file
    rm openam.war # Remove the WAR file
    cd ..
    chmod +x createwar.sh # Add execution permission to the script
    ./createwar.sh -s temp -t distauth -w auth.war # Create a distauth war named auth.war based on the temp folders content
    
  • Deploy the auth.war onto a different application server than OpenAM is deployed.
  • Log on the admin console and go to Access Control -> / (Top Level Realm) -> Authentication -> 2.2 Agents then click on the New button. Create an agent user (you should use the same credentials on the DAUI config screen).
  • Open daui.example.com:8080/auth in your browser, where you should see a configuration screen.
  • Configure the DAUI instance parameters:
    Server Protocol http or https
    Server Host openam.example.com
    Server Port 8080
    Server Deployment URI /openam
    DistAuth Cookie Name AMDistAuthCookie – this cookie tracks which DAUI server the user belongs to
    OpenAM LB Cookie Name amlbcookie – this cookie tracks which AM server the user belongs to
    DistAuth LB Cookie Name DistAuthLBCookieName – additional cookie for LB routing purposes
    DistAuth LB Cookie Value DistAuthLBCookieValue – should be different for each DAUI server
    Debug directory /opts/openam/debug – where to store the debug logs
    Debug level off, message, warning or error
    Encryption Key This symmetric key to be used for passwordencryption
    Application user name An agent user
    Application user password Password for the agent user

    At the end click on the Configure button.

  • If you try now to follow the login link, then it is very likely that you’re going to see a No such Organization found. error message. This happens, because OpenAM does not recognize the daui.example.com as a valid domain. To solve this you need to add the DAUI URL to the Realm/DNS Aliases list by going to Access Control -> Realm -> General tab. The DNS alias will bind itself to the given realm, so usually the Top level realm is the best place to configure this.
    You only need to set the DNS Aliases for externally accessible URLs.
  • After setting up the DNS Alias the error message should disappear, so there is only one caveat left: on the Configuration -> System -> Platform page you have to make sure that the Cookie domain list contains all or part of the DAUI’s FQDN. If this is not the case the DAUI login page will not give access, and every time the form is submitted it will just render the first login page again.

After setting up the first DAUI instance setting up the second instance is a piece of cake. 🙂 Just follow the previous steps and you should be OK. However if you cannot implement sticky loadbalancing, then you can see a weird error message saying: http://daui2.example.com:8080/auth/UI/Login is not the trusted server. Internally the DAUI servers needs to know about each other, so they can safely forward authentication requests from one server to another.

How does the authentication request forwarding work?

Basically when you open the Login page your browser will store the AMDistAuthCookie identifying the DAUI server. When a subsequent request goes to a different server, DAUI will first check whether it can trust the server (value of the AMDistAuthCookie), then it will actually forward the request and render the response to the user. Such trust between the DAUI servers can be created by setting the following property in the DAUI configuration files (under ~/FAMDistAuth):

com.sun.identity.distauth.cluster=http://daui.example.com:8080/auth/UI/Login,http://daui2.example.com:8080/auth/UI/Login

Restart your servers and off you go. 😉

5 comments

  1. Great article, many thanks.
    Just a few points which may be of interest to other readers:
    Java Sun System Web Server url encodes the value of the AMDistAuthCookie cookie. Tomcat puts double quotes arround the value of the AMDistAuthCookie cookie. I could not get either of these to work with another GlassFish server. However I managed to get two instances of GlassFish, both configured with a FQDNs, to work.

  2. Using the 6/20/2012 nightly build of OpenAM the Agent Authenticators are here: Authentication -> Realm -> Agents -> Agent Authenticator.

    When I configured my DAS, it could not log in using the Agent Authenticator name and password, but worked if I used the user UrlAccessAgent established during the OpenAM setup process.

Join the Conversation

Your email address will not be published. Required fields are marked *