Introduction:

With the release of NetIQ Advanced Authentication 5.5, the AA server can act as a SAML 2.0 Identity Provider where user credentials are validated. Any Service Provider that can talk SAML 2.0, such as the NetIQ Access Manager (NAM) server, can integrate with this so that users after having successfully authenticated with the AA server, can single sign on to the back end Service Provider. This document will show how the AA and NAM servers can be setup to achieve this goal.

Note too that NAM can also be setup as an Identity Provider where it validates the users credentials by making REST calls into the AA server. This integration is built into NAM but does does not use SAML 2.0 protocol. It’s the default and most convenient setup for environments where NAM already exists as the Identity Provider. For more information on this setup, check out https://www.netiq.com/documentation/advanced-authentication-53/nam-aa-plugin-installation-guide/data/bookinfo.html.

Configuration details:

As with any SAML 2.0 federation, the Identity Server (AA) and Service Provider (NAM) must echange key information about itself to build the trust relationship. We will outline the steps needed on both sides, starting with AA.

Before we start the configuration changes, there's one pre-requisite needed. The AA admin will need to contact the admin of the NAM SAML 2.0 Service Provider to export it's SAML metadata. This is done by accessing the /nidp/saml2/metadata URL on your NAM Identity Server eg. https://nam43sba.dub.novell.com/nidp/saml2/metadata. NAM can act as both a SAML 2.0 Service Provider as well as a SAML 2.0 Identity Server, and therefor the metadata URL above include both. We will need to view the source and save only the SP metadata information into a local file. To do this

• Open metadata URL link and view source

• Cut and paste the EntityDescriptor tag into a file as shown below
  
  

  <?xml version="1.0" encoding="UTF-8" ?>
  <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="idEbxNm2OPW8cPHx5PFZrrbZlofJk" entityID="https://nam43sba.dub.novell.com/nidp/saml2/metadata">

  
  
  

• Search for the start of the md:SPSSODescriptor tag and cut and paste the contents starting from this tag until the end of the NAM SAML 2.0 metadata e.g.
  

  <md:SPSSODescriptor ID="idGOP-f2aJk8ST3APia82vR9eJYKw" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
  <md:KeyDescriptor use="signing">
  <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <ds:X509Data>
  <ds:X509Certificate>
  :
  </md:SPSSODescriptor>
  <md:Organization>
  <md:OrganizationName xml:lang="en">nam43sba.dub.novell.com</md:OrganizationName>
  <md:OrganizationDisplayName xml:lang="en">nam43sba.dub.novell.com</md:OrganizationDisplayName>
  <md:OrganizationURL xml:lang="en">https://nam43sba.dub.novell.com/nidp</md:OrganizationURL>
  </md:Organization>
  <md:ContactPerson contactType="other"/>
  </md:EntityDescriptor>

  
  

• Save the XML file with the metadata contents

You are now ready to start…

1. AA Server changes

   
   
   
   
   
   1. Enable the SAML 2.0 event: The event defines how the user will authenticate to the AA server. With AA 5.5, a new option exists to define SAML 2.0 style authentication using a drop down menu. Simply create a new event using the 'add' option under 'Events' and
      
      
      1. Give it a logical name e.g SAML2 Event.
      
      
   2. Make sure it is enabled.
   
   
2. Select SAML2 as the event type from the drop down menu.

• Add the authentication chain you will use to authenticate users. In my case below, we added the LDAP password chain indicating that users will be asked to authenticate using the LDAP password. You can add whatever authentication chain (including multifactor) you want users to use when the AA server needs to single signing users to SAML Service Providers.

• Import the SAML 2.0 metadata provided by the NAM SAML 2.0 Service Provider. This is the information from the pre-requisite stage mentioned above. You can simply paste the metadata, or import it from file if the file is available.
  

This metadata defines a number of key URLs that the AA server needs e.g. where to send the SAML assertion when a user has successfully authenticated; where to send a logout request; what binding to use; etc.

• Enable SAML 2.0 Options: Because of the extra resources required to run a SAML Identity Server, the SAML protocol is disabled by default. To enable it, simply go to the Server 'Options' in the admin UI and enable the WebAuth service. When enabled, the AA server can act as a SAML Identity and OAuth provider.
  
  Once enabled, it should remain so until manually disabled, and the options screen will look as follows:
  
  
  
  Note: Additional RAM (min 4GB) is required when enabled.
  

• Enable SAML policy and export metadata: Before the NAM admin can start configuring the AA SAML relationship on the NAM service provider, one must export the AA SAML metadata. This is done by going to the Policy option in the AA admin UI and selecting SAML 2.0 options.
  
  The external URL is the URL that users will access the AA SAML 2.0 Identity Provider on. The URL specified in this field is used to build the AA SAML 2.0 metadata, which will eventually be imported on the NAM side. In the example below, I added https://aaf53.lab.novell.com/, and the resulting metadata will have endpoints built around this e.g. the single sign on URL that the NAM SP will send a SAML AuthnRequest to will be https://aaf53.lab.novell.com/osp/a/TOP/auth/saml2/sso; the Single Logout Service the NAM SP will use to log user out of AA server will be https://aaf53.lab.novell.com/osp/a/TOP/auth/saml2/slo. After adding the external URL, 'download' the IDP SAML 2.0 metadata as highlighted below. Note the location of the saved file.
  
  
  
  This is all that is needed on the AA side. Now let's configure the NAM side.
  
  

• NAM Server changes

  
  
  
  
  
  1. Add new SAML 2.0 Identity Server to NAM configuration: Logging into NAM using iManager, select the IDP cluster configuration -> SAML 2.0 and add the AA server as a new SAML 2.0 Identity Provider. You will need to give the AA SAML 2.0 Identity server a logical name eg. aaf55-idp and cut and paste the metadata we exported in 1c above.
     
     
     
     
  2. Add the trusted root from the AA metadata to the NAM IDP trust store: By default AA includes a self-signed certificate as part of its metadata. Cut and paste the contents of the <x509Certificate> tag from 1c above into a file and save it with the DER extension.
     
     Using the NAM iManager admin UI, go to Security -> Trusted roots and import the above file including the AA self-signed certificate. After successfully importing it, add the certificate to the NIDP-Truststore keystore (only needed if not using NAM appliance).
     
     
  3. Configure the SAML Authentication Request details that NAM will send to AA. Selecting the aaf55-idp SAML 2.0 Identity server we created above, navigate to the 'Authentication Request' tab and make the following changes:
     
     
     
     
  4. Change Name Identifier format from default 'persistent' to either 'unspecified' or 'transient'
     
  
  
• Change 'Response Protocol binding' from default (which uses SAML artifact profile) to specify the 'Post' binding. Artifact will work fine but some extra firewall ports may need opening.
  
  The screenshot below shows what the configuration should look like:
  
  
  
  

• To handle the assertion coming back from the AA SAML 2.0 Identity Provider, so that the NAM SAML SP can single sign on and identify a local user, a few additional steps are required. Note that we do not have to identify a local user but doing so will give us access to additional attributes that may be used for NAM Access Gateway policies.
  
  
  
  
  1. Need to retrieve attribute from SAML assertion that includes unique identifier that we can use to map to a local user. In our case, we will take the 'mail' attribute sent by AA and map it to the local mail attribute from the LDAP credential profile. Create a new Attribute Set (e.g. aaf55-attrset) under Shared Settings for IDP and create one attribute using the following mapping – make sure remote format set to basic too, and that the case for mail is correct.
     
     
     
  
  
  
  
• Define user matching expression referencing users email address: Remaining under the NAM Identity Provider 'Shared Settings' tab, go and create a new 'User Matching' configuration.
  
  
  

• Now that we have the user matching expression created, we need to enable it for the aaf55-idp trust relationship. We must go back to into the NAM admin UI and select IDP -> SAML2 -> aaf55-idp server, and enable the attribute set we just created (aaf55-attrset). Drag the available ldap attribute mail from available to 'obtain at authentication' as shown below.
  
  
  

• Moving to the 'User Identification' tab, enable 'Attribute matching' and disable the 'prompt for password on successful match' to make the single sign on more transparent.
  
  
  
  

• Now select the 'Attribute Matching settings' option highlighted above and
  
  
  
  • Add the local LDAP user store to search for a matching user and
  
  
• Enable the previously created user matching expression so that NAM knows that LDAP attribute to key off

Note: If the user is redirected to the NAM Portal page after having successfully authenticated to the AA server, and not the Access Gateway protected resource that the user expected to be redirected to, a small change to the contract configuration on NAM may be required.

When the AA server sends the SAML assertion back to NAM, it includes information on how the user authenticated in the AuthnContextClassRef or AuthnContextDeclRef statements e.g.

<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
		<saml:AuthnContextDeclRef>idm:login:user:aa</saml:AuthnContextDeclRef>

NAM must map the users' authentication method on AA using the NAM contract. The NAM contract URI should match the AuthnContextDeclRef, or we can configure the 'Allowable Class' contract parameter to the AuthnContextClassRef statement. In the example above, I could modify the Secure Name/Password – Form contract and add the above “urn:oasis:names:tc:SAML:2.0:ac:classes:Password” string as shown below. This will allow the contract on Access to match and allow request through.

Testing the solution:

• Access the NAM system and select to authenticate using the aaf55-idp card.

• Verify that user is redirected over to AA server where following page is displayed.

• Enter the username at the AA server login prompt.

• Since the Chain associated with the SAML 2.0 event is LDAP password, the user will be prompted for their password.

• Once AA validates the credentials, the on box SAML 2.0 identity server will generate a SAML assertion to send back to the NAM SAML 2.0 service provider. This assertion will include the users email address (as well as some other attributes), which NAM will use to identify a local user. A sample snippet of an assertion is shown below
  
  

  <saml:Subject>
  	<saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
                           NameQualifier="https://aaf53.lab.novell.com/osp/a/TOP/auth/saml2/metadata"
                           SPNameQualifier="https://nam43sba.dub.novell.com/nidp/saml2/metadata"
                           >cqxiovRKryau2az9idqs94zYpPaI3q7wwqHlgQ==</saml:NameID>
  	<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
  		<saml:SubjectConfirmationData InResponseTo="idEZzVZFRSyoqKP3sf6yLpBbAgdeo"
                                                NotOnOrAfter="2016-12-12T16:01:25Z"
                                                Recipient="https://nam43sba.dub.novell.com/nidp/saml2/spassertion_consumer"
                                                />
  	</saml:SubjectConfirmation>
  </saml:Subject>
  <saml:Conditions NotBefore="2016-12-12T15:40:36Z"
                           NotOnOrAfter="2016-12-12T15:50:36Z"
                           >
  	<saml:AudienceRestriction>
  		<saml:Audience>https://nam43sba.dub.novell.com/nidp/saml2/metadata</saml:Audience>
  	</saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AuthnStatement AuthnInstant="2016-12-12T15:33:06Z"
                               SessionIndex="idbaonpGakXiPfNlp42s5YXHcTKsM"
                               >
  	<saml:AuthnContext>
  		<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
  		<saml:AuthnContextDeclRef>idm:login:user:aa</saml:AuthnContextDeclRef>
  	</saml:AuthnContext>
  </saml:AuthnStatement>
  <saml:AttributeStatement>
  	<saml:Attribute
  		xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              Name="mail"
                              NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                              >
  		<saml:AttributeValue xsi:type="xsd:string">ncashell@novell.com</saml:AttributeValue>
  	</saml:Attribute>
  	<saml:Attribute
  		xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              Name="mobile"
                              NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                              >
  		<saml:AttributeValue xsi:type="xsd:string"> 353868586999</saml:AttributeValue>
  	</saml:Attribute>
  	<saml:Attribute
  		xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              Name="DN"
                              NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                              >
  		<saml:AttributeValue xsi:type="xsd:string">cn=ncashell,ou=sa,o=system</saml:AttributeValue>
  	</saml:Attribute>
  	<saml:Attribute
  		xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              Name="CN"
                              NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                              >
  		<saml:AttributeValue xsi:type="xsd:string">ncashell</saml:AttributeValue>
  	</saml:Attribute>
         </saml:AttributeStatement>
       </saml:Assertion>
  		</samlp:Response>

  
  
  

• NAM will consume the assertion, identify a local user and user will now be logged in as that local user.