Category: DAS

How to use Certificate module with DAS

Previously I have described how to install the DAS properly. Today’s entry is all about using the Certificate authentication module in a deployment where you have a DAS instance. So here are the steps required to make this work:

  • Follow the DAS install guide, but with the only difference being that you install the DAS on a HTTPS URL (OpenAM can keep running on HTTP). Since you are now using HTTPS, you need to make sure that the OpenAM server trusts the DAS’s certificate, otherwise OpenAM won’t be able to send notifications to the DAS, which could result in strange situations when a given session remains valid for a short period of time even though the user has logged out on a different DAS instance.
  • Go to Access Control – realm – Authentication page and Add a new Module Instance called cert with type Certificate
  • Open the Certificate module configuration, and change the followings:
    • Set the LDAP Server Authentication User/Password to correct values
    • For evaluation purposes set the Trusted Remote Hosts to “all”
  • Generate a new self signed certificate by following this guide, but make sure that in the CSR you set the CN to “demo”.
  • Create PKCS#12 keystore for the freshly generated private key and certificate:
    openssl pkcs12 -export -inkey -in server.crt -out server.p12
  • Install the PKCS#12 keystore in your browser (Guide for Firefox)
  • Enable Client Authentication on the DAS’s container. For example on GlassFish 3.1.2 Admin Console you would have to go to Configurationsserver-configHTTP serviceHttp Listenershttp-listener-2 then open the SSL tab and check the Client Authentication option.
  • Install the public certificate into the container’s truststore, so the container will actually trust your certificate:
    keytool -import -keystore glassfish3/glassfish/domains/domain2/config/cacerts.jks -file server.crt -alias mycert

    You need to make sure that you install the certificate to the actually used truststore, some containers may use the JVM’s truststore instead having one on their own.

  • On the DAS enable the Request/Response serialization by setting the following property in the ~/FAMDistAuth/*.properties file:
  • Restart the DAS’s container
  • Open /auth/UI/Login?module=cert and choose your certificate
  • Profit

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.


  • 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 # Add execution permission to the script
    ./ -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 in your browser, where you should see a configuration screen.
  • Configure the DAUI instance parameters:
    Server Protocol http or https
    Server Host
    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 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: 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. 😉

New feature in DAS in OpenAM 9.5.1RC2

Sometimes there is a need, when you need to add an additional filter for the Distributed Authentication User Interface. For example if you want to set some extra request parameters, or just want to add/filter out some response HTTP headers, anything that fits your needs. The problem with this is, that you can not configure your webapplication to run the Filter init methods always in the exact same order, because this is not covered by the EE specs, you can only control the filter order for doFilter. When your custom filters initialization depends on the DAS filter, then OPENAM-229 comes into the picture.
The fix for this issue was to move the initialization code to a helper class, which can take care of initialization for everyone. So if you have an own filter you only have to put the following snippet at the beginning of your init:

if (!DistAuthConfiguratorFilter.isConfigured) {
    DistAuthConfiguratorFilter.isConfigured = 

And off you go, now the initialization order wouldn’t matter anymore, since the DistAuth will be always init’d first.