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.
- Hides sensitive parts of the OpenAM server
- Lowers the load on the actual core servers
- 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):
Restart your servers and off you go. 😉