The purpose of this Cool Solution is to inform our customers that it is possible to retrieve, manipulate, and send data in a SAML assertion that is not available from the configured user store in a SAML assertion - "external data".
Assertion data is most often readily available as a constant value, from trusted Identity Provider, or from an existing attribute on the user's object in your configured NAM User Store (LDAP). What do you do when the data you need is not in the LDAP User Store? Data that is stored in a secondary source such as a web service, an database, secondary LDAP directory, etc. This problem is typically solved by using NetIQ Identity Manager to synchronize the needed attributes into your configured NAM User Store. A sound and commonly used approach, but not the only one available. With a bit of knowledge, creativity and developer skill, this can be achieved in other ways. One option is to use new features in NAM 3.2 in conjunction with the NAM Policy Extension API. This Cool Solution will help guide you to the information exemplifies this method.
Most of the information herein is available in various guides and code sample docs, but can be difficult to find and follow. The intent of this Cool Solution is to help you "connect the dots", provide additional clarity, and serve as a reference to locate the various docs and sample code. With this information you can create your own NAM Data Extension to retrieve attributes from an external data source making them available to NAM to be passed to trusted federation partners using existing NAM features.
Note: The NAM developer kit docs have been moved and are now easier to find as a link from the main NAM documentation home page. The links in this document reflect this change.
The existing NAM java Policy Extension API is able to, among other things, retrieve data from an external data store using the Data Extension class and subsequently inject it into an HTTP header using an Identity Injection policy. Previously that data was not available to the NAM Attribute Set(s) for inclusion in a SAML assertion. Using NAM 3.2 this is now possible. Now your Data Extension class is called by a new "External Attribute Source" policy whereupon it is passed into a configurable NAM Shared Secret(s) which are available to NAM Attribute Set(s).
Using this method, when a user authenticates to a NAM Identity Server where this policy is enabled, your Data Extension is executed at runtime. The data retrieved by the extension is then injected into the current user session in the form of a NAM Shared Secret attribute of the authenticated user. If the data retrieved is in the exact format you would like then you can simply pass it into a Shared Secret. You also can also manipulate the data retrieved before it is stored in the Shared Secret. For example, perhaps the retrieved data is a long string like a DN such as CN=JasonRivers,OU=HQ,CN=Users,DC=mydomain,DC=com yet you only want to send "JASONRIVERS" in the assertion. Your extension can do this. The Shared Secret is then available for use in Access Gateway Policies but also Identity Server Attribute Sets so they can be mapped into your SAML assertions. Unlike typical Shared Secrets, the retrieved data is not stored permanently. Instead when the policy is executed the data is re-read from the source dynamically at execution.
This particular approach leverages several NAM 3.2 features including the External Attribute Source policy, Shared Secret, Policy Extension API, and Attribute Set(s). Again, this is only one way to achieve the goal. Stay tuned as other approaches are published through SDK sample code and/or Cool Solutions.
The NAM 3.2 SDK documentation includes several downloadable code samples. The "Data Extension Example for External Attribute Source Policy" sample is the closest example that meets our use case but will need to be enhanced before you use it. As is, the sample code will read the email attribute from the authenticated user's object in the user store that authenticated the user. It also includes an example of data transformation that strips off the user's name from the retrieved value. For example it would retrieve email@example.com, strip the @mycorp.com from the data and populate a Shared Secret with jdoe. If needed, you will need to add your own code to retrieve data from an external source such as a database, secondary LDAP directory, or web service.
Just to get a feel for the task ahead, a high-level list is below. Following this is a step by step list of tasks are additional details that include links to the source information for your reference:
Use the sample code or create your own Data Extension and compile the code. It is your Data Extension that determines what data is retrieved, how, and from what source.
Deploy using the NAM Administration Console to define, configure, and distribute an "Identity Server: External Attribute Source" policy. Your External Attribute Source policy executes your Data Extension which fetches the data.
Define a matching NAM Shared Secret to store the data retrieved by your Data Extension.
Enable your NAM External Attribute Source policy on your Identity Server.
Define or modify your Identity Server Attribute Set by mapping the respective Shared Secret so that the data can be added to assertions sent to trusted SAML Service Providers that use this Attribute Set.
Define a new "External Attribute Source" policy to be used by your Identity Server. The same process to create typical NAM policies (e.g. Roles, Authorization, Identity Injection, etc) is also used to create this policy. Instructions are in the NAM 3.2 Policy Guide > Creating External Attribute Source Policies > Creating External Attribute Source Policies. The following example values are those used in the referenced sample code:
Important: Proper naming is critical. Your policy name must match your "Secret Name" and the "External Attribute Name" in your policy must match your "Secret Entry Name" defined in step 3 below. Names must match so that NAM knows where to store and access the values retrieved by your Data Extension. Once stored as a Shared Secret, the data is mapped in an Identity Server Attribute Set mapping in step 4 below.
Define a NAM Shared Secret to store the data retrieved by your Data Extension
Instructions to define your Shared Secret are in the NAM 3.2 Identity Server Guide > Defining Shared Settings > Adding Custom Attributes > Creating Shared Secret Names. The following example values are those used in the referenced sample code:
Secret Name: ExternalAttrSource_EmailExample
Secret Entry Name: ExternalAttrSource_Email_Policy_Result Important: Proper naming is critical. The "Secret Name" must match your External Attribute Source policy name and the "Secret Entry Name" must match the "External Attribute Name" used in the policy created in step 2 above.
Modify or create your Identity Server Attribute Set
Add your new Shared Secret attribute to the set by mapping the "Local attribute" to the Shared Secret previously defined. You will find your Shared Secret among the "Local attributes" drop-down listed as part of the user session Credential Profile. For example:
Enable the new "External Attribute Source" policy on your Identity Server Cluster