Custom Auth module – Configuration basics

If you want to create a custom OpenAM auth module or a service, then you probably going to end up writing a configuration XML. This XML describes to OpenAM what kind of UI elements to render on the admin console, and what values should be stored in the configuration store for the given module.
Let’s take a look at the following sample XML:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ServicesConfiguration
PUBLIC "=//iPlanet//Service Management Services (SMS) 1.0 DTD//EN"
"jar://com/sun/identity/sm/sms.dtd">

<ServicesConfiguration>
    <Service name="sunAMAuthMyModuleService" version="1.0">
        <Schema
serviceHierarchy="/DSAMEConfig/authentication/sunAMAuthMyModuleService"
            i18nFileName="amAuthMyModule"
            revisionNumber="1"
            i18nKey="sunAMAuthMyModuleServiceDescription">

            <Organization>
                <AttributeSchema name="sunAMAuthMyModuleAuthLevel"
                                 type="single"
                                 syntax="number_range" rangeStart="0"
                                 rangeEnd="2147483647"
                                 i18nKey="a500">
                    <DefaultValues>
                        <Value>0</Value>
                    </DefaultValues>
                </AttributeSchema>

                <SubSchema name="serverconfig" inheritance="multiple">
                    <AttributeSchema name="sunAMAuthMyModuleAuthLevel"
                                     type="single"
                                     syntax="number_range" rangeStart="0"
                                     rangeEnd="2147483647"
                                     i18nKey="a500">
                        <DefaultValues>
                            <Value>0</Value>
                        </DefaultValues>
                    </AttributeSchema>
                </SubSchema>
            </Organization>
        </Schema>
    </Service>
</ServicesConfiguration>

What you should know about authentication module service XMLs:

  • According to this piece of code the service name HAS to start with either iPlanetAMAuth or sunAMAuth, and HAS to end with Service (like sunAMAuthMyModuleService in our case)
  • the serviceHierarchy attribute is /DSAMEConfig/authentication/<service-name>
  • in the i18nFileName attribute you need to add the name of a properties file, which is on OpenAM classpath (like openam.war!WEB-INF/classes). This internationalization file will be used by OpenAM to lookup the i18nKeys for the various items in the XML.
  • You should put the module options into an Organization Schema, this will make sure that the module will be configurable per realm.
  • All the attribute schema definitions should be also listed under a SubSchema element (this will allow you to set up two module instances based on the same module type with different configurations).

The AttributeSchema element contains informations about a single configuration item (what name should OpenAM use to store the parameter in the configstore, what kind of UI element needs to be rendered, what restrictions does the attribute have, etc).

Available types for an attribute:

  • single -> singlevalued attribute
  • list -> multivalued attribute
  • single_choice -> radio choice, only one selectable value
  • multiple_choice -> checkboxes, where multiple item could be selected
  • signature -> unknown, possibly not used
  • validator -> if you want to use a custom validator for your attribute, you need to include the validator itself (beware of OPENAM-974).

Available uitypes for an attribute:

  • radio -> radiobutton mostly for displaying yes-no selections
  • link -> this is going to be rendered as a link, where the href will be the value of the propertiesViewBeanURL attribute
  • button -> unknown, not used
  • name_value_list -> generates a table with add/delete buttons (see Globalization settings for example)
  • unorderedlist -> a multiple choice field in which you can dynamically add and remove values. The values are stored unordered.
  • orderedlist -> a multiple choice field in which you can dynamically add and remove values. The values are stored ordered.
  • maplist -> a multiple choice field in which you can add/remove key-value pairs
  • globalmaplist -> same as maplist, but it allows the key to be empty.
  • addremovelist -> basically a palette where you can select items from the left list and move them to the right list

Available syntaxes for an attribute:

  • boolean -> can be true or false
  • string -> any kind of string
  • paragraph -> multilined text
  • password -> this will tell the console, that it should mask the value, when it’s displayed
  • encrypted_password -> same as the password syntax
  • dn -> valid LDAP DN
  • email
  • url
  • numeric -> its value can only contain numbers
  • percent
  • number
  • decimal_number
  • number_range -> see rangeStart and rangeEnd attributes
  • decimal_range -> see rangeStart and rangeEnd attributes
  • xml
  • date

NOTE: Some of these syntaxes aren’t really used within the product, so choose it wisely.

Other than these, there is also the i18nKey attribute, which basically points to i18n keys in the referred i18nFile configured for the service. This is used when the config is displayed on the admin console.
This should cover the basics for authentication module service configuration I think. ;)

Session Quota basics

What is Session Quota?

Session Quota provides a way to limit the number of active sessions for a given user. Basically in the session service you can configure how many active sessions could a user have. For simplicity let’s say that the active session limit is set to 5. If a user would log in for the 6th time, then based on the session quota settings a QuotaExhaustionAction gets executed, which will decide what happens with the new and the existing sessions.

How session quota is evaluated?

When session quota is enabled, OpenAM tracks the user sessions mapped by universal IDs, hence it can easily detect the number of active sessions for a given user (this mapping is only available when session quota is enabled or SFO is being used). There is 3 way how the session quota can be evaluated:

  • Single Server Mode: if there is only one OpenAM node (with or without a site), then the quota will be evaluated per that one server.
  • Local Server Only Mode: When the advanced property “openam.session.useLocalSessionsInMultiServerMode” is set to true, OpenAM will only evaluate session quota per local server (so a user can end up having number of servers * number of allowed concurrent sessions). This option has been introduced to provide a certain level of support for multiserver environments without SFO (see OPENAM-875)
  • Session Failover Mode: In multiserver setup when using SFO it is possible to enforce deployment-wide session quota

So we now know how OpenAM detects if the session quota is being exceeded by a given user, but we don’t know yet what to do when that happens. Here comes QuotaExhaustionAction into the picture. This interface allows deployers to customize the behavior of OpenAM for these cases. To understand this a bit more let’s look at the built-in session quota exhaustion actions:

  • DENY_ACCESS: basically it will deny the access for the new session, but will keep the old session alive.
  • DESTROY_NEXT_EXPIRING: destroys the next expiring session (based on min(full, idle) for all the sessions), and lets the new session live.
  • DESTROY_OLDEST_SESSION: destroys the session with the lowest expiration time, and lets the new session live.
  • DESTROY_OLD_SESSIONS: destroys all the existing sessions, and lets the new session live.

As you can see there are many different ways to handle session quota exhaustion, and it really depends on the requirements, which method really fits. In case none of these are good for you, you can simply implement a custom QuotaExhaustionAction, for that you can find the built-in implementations here, but there is also a sample GitHub project.
Once you are ready with your custom implementation follow the installation steps on the GitHub project README.

How to enable session quota?

On the admin console go to Configuration -> Global -> Session page and:

  • Set the number of “Active User Sessions” to your choosen value.
  • Turn ON “Enable Quota Constraints”.
  • Select the preferred exhaustion action under the “Resulting behavior if session quota exhausted” option.

Quite possibly you need to restart OpenAM for the changes to take effect, but after then it should work just as you would want it to. ;)