Identity and Access Management (IAM)

A WebSEAL chained attribute entitlement service using Advanced Access Control Authentication Policy

By Gianluca Gargaro posted Fri February 14, 2020 12:20 PM



WebSEAL supports several mechanisms to add attributes in the user credential.  A known built-in service is the registry attribute entitlement service that adds LDAP user attributes into the user credential during the authentication process.
This service can be also chained so that values retrieved from the execution of one instance of it can be used as input values for  the execution of the next instances of the same service.  This is useful when there are business requirements to add attributes from different LDAP objects. For example let’s suppose an ISAM user has the following registry LDAP object:

dn: cn=pippo,ou=engineering,dc=secsupport,dc=it
cn: pippo
sn: lino
manager: cn=giovannino,ou=engineering,dc=secsupport,dc=it
pager: +391233333333

where his manager LDAP object is :

dn: cn=giovannino,ou=engineering,dc=secsupport,dc=it
cn: giovannino
sn: pomposole
departmentNumber: 1234
employeeType: First Line Manager
telephoneNumber: +390987654321
secretary: cn=edeltrude,ou=backoffice,dc=secsupport,dc=it

and the manager's secretary LDAP object is :
dn: cn=edeltrude,ou=backoffice,dc=secsupport,dc=it 
cn: edeltrude 
sn: escribana 
facsimileTelephoneNumber: +39123456789

With such LDAP objects it is possible to include in  Pippo's WebSeal credential either attributes from his registry object but also from his Manager and something also from his Manager's  Secretary. This can be done chaining the registry entitlement service with the following WebSEAL configuration:


cred-attribute-entitlement-services = TAM_CRED_ATTRS_SVC
cred-attribute-entitlement-services = TAM2_CRED_ATTRS_SVC
cred-attribute-entitlement-services = TAM3_CRED_ATTRS_SVC


TAM_CRED_ATTRS_SVC = azn_ent_cred_attrs
TAM2_CRED_ATTRS_SVC = azn_ent_cred_attrs
TAM3_CRED_ATTRS_SVC = azn_ent_cred_attrs

person = azn_cred_registry_id

tagvalue_emailAddress = mail
tagvalue_pagerNumber = pager
tagvalue_managerdn = manager

manager = tagvalue_managerdn

tagvalue_manager_email = mail
tagvalue_manager_phone = telephoneNumber
tagvalue_secretarydn = secretary

secretary = tagvalue_secretarydn

tagvalue_secretary_fax = facsimileTelephoneNumber

The Pippo's credential , after a successful authentication to WebSeal will be populated in this way :

Despite this WebSEAL built-in service being available for many years, in the last release of the product the chaining is more difficult due to some restrictions with adding entries in the WebSEAL configuration file.

Currently, at the time of writing, in ISAM 9 you can only achieve a single invocation of the service,  that means you can only add attributes from Pippo  LDAP object into the credential. A further step can be done using an ad-hoc fix currently offered by support and chain a second instance of the service but no more than that.

However, this built-in service does not offer the flexibility to use a different attribute source, moreover for each service the source value for its invocation is limited to be in the form of an LDAP DN.

Following this blog article we will use a combination of components of AAC and Federation Runtime to achieve the same results with potentially more flexibility in terms of source  attributes as well as value used as input for the next "chained" attribute lookup.

Define attributes to add into the credential

  • Create a Server Connection:
In our example we are using a single LDAP server connection that matches the ISAM user registry, however here the first place where there is more flexibility , you can define different connections , also of different type :

  • Create Attribute Sources:
Each attribute  you want to add must be defined here, notice those are all the attributes, for the second and the third invocation of the service ( e.g attributes from the manager and the secretary LDAP object ) , while  the one from the ISAM user will be added during the authentication using the default AAC Username and Password authentication Mechanism that we will introduce  later.

Each attribute source definition has almost the same configuration (a note on the Base DN entry; content in the curly brackets is a macro that will be replaced at runtime with the value of the attribute named "searchDN" from the STSUU user object within the STS chain), the InfoMap mapping rule is where we define that value and push to the STS service

Create STS chains

Above attributes are now available to be used within an STS Default Attribute Map module, so it is necessary to create two STS chains to include this map module

  • Create an STS chain template composed by STSUU ( validate ) ->Default Attribute Mapping ( Map ) -> STSUU modules ( issue ) modules

  • create two STS chains
the first chain has the following configurations:

where the Map module has the following attributes added

The second chain is almost similar with the exception of ws-trust lookup details and attributes to include in the mapping module :

and map attributes:

Configure the Username and Password AAC Authentication Mechanism

In our solution we are deferring the authentication to an external service via WebSEAL EAI interface. The EAI is implemented via AAC Authentication Service and we leverage the out-of-the-box Username and Password Authentication module to challenge the user for credential and verify them in the ISAM registry.

  • Configure the generic properties for the Username and Password Module: 
you need to specify the user registry and other options for the authentication process, more or less matching the way WebSEAL authenticates users

  • Defines attributes the module needs to pull from registry:
Although the main goal of this module is to verify username and password it also offers the capability, within the attributes tab, to define a list of the user's registry attributes to add into the credential. Notice that those attributes are limited to the user registry object only.

This module however only adds attributes into the session context ( as attributes of type "urn:ibm:security:authentication:asf:mechanism:password" ) so you will need later to add them into the credential.
We are doing this in the next InfoMap module. Alternatively, as last chance, it can be done in the AuthSvcCredential mapping rule. This rule is always executed at the end of all authentication modules defined in the authentication policy.

Create an InfoMap Authentication Mechanism

An InfoMap authentication mechanism is the most flexible mechanism we have in ISAM AAC to handle authentication and user credential manipulation. Despite in the same InfoMap mechanism we could have accomplished either the authentication and the attributes enrichment , we decided to leave the authentication ( username and password verification ) to the out of the box Username and Password Module above defined, while leaving the InfoMap mechanism to add the chained attributes.

  • Define a mapping rule :
In our solution the InfoMap will call sequentially the STS chains to retrieve attributes from the different sources defined earlier. The main part of the Infomap mechanism is a mapping rule, the source of the mapping rule can be found here

  • create an InfoMap Mechanism that use above rule

  • there is no need to create a template page as this InfoMap will not interact with the user for authentication but only add the attributes after that, so just add the mapping rule in the properties tab :

Define an Authentication Policy

An AAC authentication mechanism can't be invoked directly, it must be included in an Authentication Policy workflow. Authentication policies determine the order and conditions in which various authentication mechanisms are used to successfully authenticate a user.
In our scenario we only need the two authentication mechanisms above configured to be executed one after the other.

  • Create a new Authentication Policy: define an identifier for the policy , this is how the policy is invoked when using the authentication service.

  • Add the two modules in the workflow in the proper order

Test the solution

At this point , if not already done, configure a WebSeal instance for  Authentication and Context Based Access, in this way WebSEAL is ready  to use any AAC Authentication Policy.

It is enough to specify the identifier as part of the query string when invoking the authentication service through the /mga junction ( this is the default junction name offered during the WebSeal configuration for Authentication and Context Base access, of course you may use a different one ) like https://yourwebseal/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:chainent

After the username and password are verified, the InfoMap module will silently contact the two STS chains and enrich the user's credential.
There are several ways to see the content of an ISAM WebSeal credential, since we are now "expert" on AAC InfoMap you may use the WhoAmI  Credential viewer solution ( for those who are going to implement  that WhoAmI InfoMap on ISAM  add  @USER_CRED_JSON@ in the list of the "not escaped macros" , in the  AAC advanced configuration  ).

The credential view should be like this one.


We have documented an alternative and more flexible solution to replace the built-in WebSEAL attribute entitlement service also in a chained configuration mode. A few words about performance, although I've not done any real performance benchmarks it is probably true that the WebSEAL buit-in solution is faster, however considering all the flexible options that this solution brings into the architecture there is also the capability to have multiple AAC runtimes behind the same /mga junction. This will dramatically increase the scalability of the solution, offloading all the authentication effort from WebSEAL. With this in mind I believe it is valid architecture also for performance improvements.