Table of Contents:
The most common approach to integrating Microsoft SharePoint Servers with Access Manager involves accelerating the SharePoint Web Server with the Access Gateway and using Identity Injection or Formfill to single sign on (SSO) users. NetIQ Access Manager (NAM) documentation includes details on how to set this up https://www.netiq.com/documentation/access-manager-41/bestpractices/data/bz9vaoa.html. Whilst this works very well in a number of environments, there are some areas where this SSO may fail. For example, if a user logs into NAM and SSOs to SharePoint 2013 server from a browser, clicks on a doc to modify, another User-Agent (e.g. Microsoft Office App) is launched to edit the file. The new Microsoft User-agent does not share session information with the browser, and the user may need to login a second time to access the file. This typically appears as a nondescript pop-up dialog box prompting the user to login. Under the covers, Microsoft will attempt to perform its own SSO by leveraging Kerberos. When that fails, NTLM is attempted resulting in the nondescript dialog box.
To be able to handle these type of SSO problems when switching between User-agents, it is possible to use a claims-based federation trust between NAM Identity Server as a WS-Federation Claims Provider (also known as the Secure Token Service or STS) for the SharePoint 2013 Server. Almost every SharePoint document describes the need for ADFS when using Claims based federation, but this article will explain how to do this using NAM and SharePoint without ADFS.
A Claims-based identity is based on the user obtaining a security token that is digitally signed by a commonly trusted identity provider, NAM in this case, and contains a set of claims. Each claim represents a specific item of data about the user such as his or her name, group memberships, and role on the network. Claims-based authentication is user authentication that utilizes claims-based identity technologies and infrastructure. SharePoint 2013 supports claims-based authentication, obtaining the security token from the user and using the information within the claims to determine access to resources. No separate query to a directory service like Active Directory is needed or performed by SharePoint.
There are some high level references to how this can be done at https://www.netiq.com/products/access-manager/features/SharePoint-access.html, but no real detailed documentation on the steps required. This document will plug that hole and hopefully provide the steps required to get the integration going. We will also try and provide some troubleshooting tips and tools in the case where problems are encountered.
While this paper is written using SharePoint 2013 as the example, the concept is the same for SharePoint 2010.
The following is the sequence of events that will take place when the setup has been completed properly.
There are three major configuring steps needed when integrating Novell Access Manager and SharePoint 2013, and they are:
Each of these steps will be described in the sections below.
1. Export the token signing certificate from the Access Manager system
2. Export the Root (and intermediates if they exist) Certificate, if different from the token signing certificate. In this example this is the configCA certificate.
3. Export the Server Certificate from the SharePoint server.
1. Enable the STS and WS Federation Protocols
Access Manager 4.1 only enables SAML 1.1, Liberty, and SAML 2.0 Federation protocols by default. In order to use the WS Federation protocol, you must enable it on the Identity Server. Note that enabling the WS-Federation protocol enables the Secure Token Service (STS), which is used in requests from/responses to the SharePoint Server.
2. Creating an Attribute Set for WS Federation
Claims are really just specifically formatted name/value pairs. NAM uses its Attribute Set feature for this. It allows you to map attribute values from your configured LDAP user store to be sent to SharePoint as claims.
When using WS Federation, you need to decide which attributes you want to share during authentication and map those in an Attribute Set. SharePoint will consume these attributes and determine whether or not the user has permissions to access the Applications/Sites based on this. This scenario uses the LDAP mail attribute and the All Roles attribute (default attributes discussed in most SharePoint documents). To create an Attribute Set to use with WS Federation:
Set Name: Specify a name that identifies the purpose of the set, for example, SP2013-AttrSet.
Select set to use as template: Select None.
Local attribute: Select LDAP Attribute:mail [LDAP Attribute Profile].
Remote attribute: Specify emailAddr. This is the attribute that this scenario uses for user identification.
Remote namespace: Select the radio button by the text box, then select the following namespace from the dropdown list:
Local attribute: Select All Roles.
Remote attribute: Specify roles. This is the name of the attribute that is used to share roles.
Remote namespace: Select the radio button by the text box, then specify the following namespace:
3. Enabling the Attribute Set
Because the WS Federation protocol uses STS, you must enable the attribute set for STS in order to use it in an WS Federation relationship.
4. Creating a WS Federation Service Provider
A federation trust must be established between NAM and SharePoint where NAM is the Identity Provider and SharePoint is the Service Provider (a.k.a. Relying Party). The trust relationship allows the Service Provider to trust the Identity Server for user authentication credentials. This requires configuration on both NAM and SharePoint Server sides. Here we will configure NAM to define the SharePoint server as a Service Provider.
To create a Service Provider configuration on NAM:
Name: Specify a name that identifies the service provider, such as sp2013.
Provider ID: Specify the provider ID of the SharePoint server. This corresponds to the realm configured on the SharePoint server, and will be visible in incoming authentication requests from the SharePoint Server to NAM Identity Server. The example value is urn:SharePoint:portal but this can be any logical string. The key is that it is unique to this trust relationship e.g. if NAM is providing claims to multiple SharePoint environments, each SharePoint realm must be unique.
Sign-on URL: Specify the URL that the user is redirected to after login. The example value is https://sp2013.neil.com/_trust/. This corresponds to the Web Application that I have setup on SharePoint for this test.
Logout URL: (Optional) Specify the URL that the user can use for logging out. The default value is https://sp2013.neil.com/_trust/.
Service Provider: Specify the path to the signing certificate exported from the SharePoint server (see “Export the Certificates from both systems” above)
5. Configuring the Name Identifier Format
The Unspecified Name Identifier format is the default for a newly created WS Federation service provider, but this name identifier format doesn’t work with the SharePoint 2013 server and must be changed. Additionally, the roles Claims must be satisfied in order to gain access to the SharePoint server.
Attribute set: Select the WS Federation attribute set you created.
Send with authentication: Using the blue arrow, move the All Roles and Ldap Attribute:mail attributes from the ‘Available’ to the ‘Send with authentication’ list.
6. Setting Up Roles for SharePoint Claims
When users access resources on the SharePoint server, they are able to have different levels of access based on the roles assigned to them in Access Manager.
Roles in NAM are assigned to users through a role policy defined on the NAM Identity Server that contains a set of rules that when true “activates” the role for any user that meets these rules. Recall that the NAM Attribute Set example was configured to send “All Roles” as a claim so any role that activate will be sent to SharePoint as a claim.
The role policy defined in the example below is a very simple one that will evaluate true for all users that are able to successfully authenticate to NAM. Once you get your configuration working, you can experiment with more complex roles to provide Role Based Access Control for your SharePoint server.
With no conditions to match, this rule matches all authenticated users.
7. Importing the SharePoint Server Signing Certificate into the NIDP-Truststore
The NetIQ Identity Provider (NIDP) must have the trusted root of the SharePoint signing certificate (or the certificate itself in the case of self signed certificates) listed in its Trust Store. This is because the SharePoint signing certificate is validated by the NAM Identity server at initialization time, and this validation process must validate the issuer of the signing cert (or chain of certificates up to the root). Most SharePoint signing certificates (including the one in our example) are part of a certificate chain, and the certificate that goes into the metadata is not the same as the intermediate or trusted root of that certificate.
To import the SharePoint signing certificate’s trusted root (or the certificate itself) into the NIDP-Truststore:
NOTE: This option does not exist with the NAM appliance as all components (IDP, ESP, AG) share the same keystore and truststores.
This finishes the configuration that must be done on the Identity Server for the Identity Server to trust the SharePoint server. To complete our federation trust, the SharePoint server must now be configured to trust the Identity Server.
Almost all the claims based federation setup is done via Powershell command, and Windows PowerShell 3.0 is a prerequisite for installing SharePoint 2013. The following section describes each step in the process, as well as some tools to validate the configuration applied.
1. Create the NAM IDP STS that SharePoint will have a trust relationship with
c:\users\administrator.neil\downloads\nam41sba-tr.cer - this is the trusted root certificates. c:\users\administrator.neil\downloads\nam41sba-signing.cer - this is the token signing certificate.
$root = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("c:\users\administrator.neil\downloads\nam41sba-tr.cer") New-SPTrustedRootAuthority -Name "Token Signing Cert Parent" -Certificate $root
Create the cert parameter (to be used later) using the NAM IDP server signing certificate
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("c:\users\administrator.neil\downloads\nam41sba-signing.cer")
$map1 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" -SameAsIncoming $map2 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
$realm = "urn:SharePoint:portal"
$signinurl = https://nam41sba.lab.novell.com/nidp/wsfed/ep
$ap = New-SPTrustedIdentityTokenIssuer -Name "NAM41SBA-WSFED-IDP" -Description "NAM41 WSFED Federated Server" -Realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map1, $map2 -SignInUrl $signinurl -IdentifierClaim $map2.InputClaimType
2. Create or modify a SharePoint Application to use the claims based authentication
The following focusses on configuring a SharePoint Application for claims based authentication. It assumes that the reader knows how to create a SharePoint Application and site and provides no details on how to. If you are looking for this information, there are many web sites out that have extensive documentation on how to do this eg. https://technet.microsoft.com/en-us/library/ee806885.aspx
If this is a new application you may have to assign the server certificate to the Web Site binding in IIS (make sure that it is the server cert that we imported into NAM in the earlier section)
You will also need to create a Site Collection for this application if one does not already exist.
When the application is created as a secure application it creates the /_trust directory that is defined in Access Manager as the Service Provider’s login directory. This is the URL the NAM IDP server will send the claim when the users credentials are validated successfully.
To use the claims in SharePoint you must map the incoming claim to a SharePoint Application. In this example we will map the SharePointReader role from Access Manager to the SP2013 Application in SharePoint. To make this assignment:
Note that you could also grant permissions for all Users Authenticating via NAM at this point by typing in NAM41SBA and selecting the option ‘All Users (NAM41SBA-WSFED-IDP)’. This corresponds to the display name (-Name Powershell parameter) assigned to the NAM IDP server on the SharePoint Server configuration.
You can check what permissions you have to each by logging in as the Admin user for the site, going to Site Settings > Site Permissions > Select the site (SP2013-Neil-TeamSite Visitors in my example) and clicking Check Permissions. This will bring up the field below, where one can add the NAM role sent across to verify what permissions exist on the site.
Before testing the solution, it’s important to configure the browser to trust the site that you are going to. There are occasions when you open files from your SharePoint site and are asked to authenticate again. If you enter the right credentials, you can get to the page but it’s annoying having to do that after you have already authenticated to the NAM Identity Server and SSOd to the SharePoint Server. To avoid this, the SharePoint site(s) must be added to the Local Intranet zone or the trusted sites zone on the IE client browser.
Browser HTTP headers trace will confirm that a ws-federation login request is sent to NAM by SharePoint (via a browser redirect) – in the case above, the full request URL to the NAM IDP server looked as follows:
The wa parameter includes the signin1.0, indicating a login request; the wtrealm parameter defines the SharePoint realm we have a trust relationship with, and the wctx is the target URL we need to go back to after successfully authenticating. Assuming that we successfully have a trust relationship with the SharePoint server, the user will get prompted for his/her credentials.
In our setup, the following parameters were POSTed to the SharePoint server (removed cert related info) – the wa and wctx parameters will match that of the login request, but the wresult parameter includes the claim (RequestSecurityTokenResponse). Note the AttributeStatement and Subject NameIdentifier tags include what we defined on the NAM IDP authentication response and attribute fields.
wa=wsignin1.0&wresult= <wst:RequestSecurityTokenResponse+ xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"> <wst:RequestedSecurityToken+ xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"> <saml:Assertion+ xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"+AssertionID="idsfUKwa6e6SB0DxHqb3t9NGpD6as"+IssueInstant="2015-09-11T11:41:53Z"+Issuer="https://nam41sba.lab.novell.com/nidp/wsfed/"+MajorVersion="1"+MinorVersion="1"> <saml:Conditions+NotBefore="2015-09-11T11:26:53Z"+NotOnOrAfter="2015-09-11T11:56:53Z"> <saml:AudienceRestrictionCondition> <saml:Audience>urn:SharePoint:portal</saml:Audience> </saml:AudienceRestrictionCondition> </saml:Conditions> <saml:AuthenticationStatement+AuthenticationInstant="2015-09-11T11:41:53Z"+AuthenticationMethod="secure/name/password/uri"> <saml:Subject> <saml:NameIdentifier+Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">firstname.lastname@example.org</saml:NameIdentifier> <saml:SubjectConfirmation> <saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</saml:ConfirmationMethod> </saml:SubjectConfirmation> </saml:Subject> </saml:AuthenticationStatement> <saml:AttributeStatement> <saml:Subject> <saml:NameIdentifier+Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">email@example.com</saml:NameIdentifier> <saml:SubjectConfirmation> <saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</saml:ConfirmationMethod> </saml:SubjectConfirmation> </saml:Subject> <saml:Attribute+AttributeName="emailaddr"+AttributeNamespace="http://schemas.xmlsoap.org/ws/2005/05/identity/claims"> <saml:AttributeValue>firstname.lastname@example.org</saml:AttributeValue> </saml:Attribute> <saml:Attribute+AttributeName="role"+AttributeNamespace="http://schemas.xmlsoap.org/ws/2008/06/identity/claims/"> <saml:AttributeValue>Manager</saml:AttributeValue> <saml:AttributeValue>SharePointReader</saml:AttributeValue> <saml:AttributeValue>authenticated</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> <ds:Signature+ xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:SignedInfo> : : </ds:Signature> </saml:Assertion> </wst:RequestedSecurityToken> </wst:RequestSecurityTokenResponse>&wctx=https://sp2013.neil.com/sites/team/_layouts/15/Authenticate.aspx?Source=%2Fsites%2Fteam
Detailed troubleshooting steps are not part of this document, but the key log files to look at and tips are outlined. We will cover both the NAM and SharePoint sides.
1. NAM Identity Server:
From the NAM side, make sure that IDP logging is enabled and that Application, WS-Federation, Web Service Provider and Web Service Consumer components are set to DEBUG. Once done
<amLogEntry> 2015-09-11T10:07:52Z INFO NIDS Application: AM#500105038: AMDEVICEID#C136F71C6489AD8E: Loaded trusted provider urn:SharePoint:portal of protocol WSFederation </amLogEntry>
<amLogEntry> 2015-09-11T10:19:02Z DEBUG NIDS Application: Method: NIDPProxyableServlet.myDoGetWithProxy Thread: ajp-bio-127.0.0.1-9019-exec-3 ****** HttpServletRequest Information: Method: GET Scheme: https Context Path: /nidp Servlet Path: /wsfed Query String: wa=wsignin1.0&wtrealm=urn%3aSharePoint%3aportal&wctx=https%3a%2f%2fsp2013.neil.com%2fsites%2fteam%2f _layouts%2f15%2fAuthenticate.aspx%3fSource%3d%252Fsites%252Fteam Path Info: /ep
<amLogEntry> 2015-09-11T10:19:08Z DEBUG NIDS STS: Method: SAMLTokenGeneratorHandler.A Thread: ajp-bio-127.0.0.1-9019-exec-3 <wst:RequestedSecurityToken xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust"> <saml:Assertion AssertionID="idaMAN3AckYCbKvPG5jpJV1AOsfVQ" IssueInstant="2015-09-11T10:19:08Z" Issuer="http s://nam41sba.lab.novell.com/nidp/wsfed/" MajorVersion="1" MinorVersion="1" xmlns:saml="urn:oasis:names:tc:SAML:1.0 :assertion"> <saml:Conditions NotBefore="2015-09-11T10:04:08Z" NotOnOrAfter="2015-09-11T10:34:08Z"> <saml:AudienceRestrictionCondition> <saml:Audience> urn:SharePoint:portal </saml:Audience> </saml:AudienceRestrictionCondition> </saml:Conditions> <saml:AuthenticationStatement AuthenticationInstant="2015-09-11T10:19:08Z" AuthenticationMethod="secure/n ame/password/uri">
2. SharePoint 2013 Server:
SharePoint relies on IIS running correctly, and a good test before enabling Claim based authentication on your SharePoint 2013 server is to enable local (NTLM or basic) logins. Assuming that you can login as a local user without issues, you can be sure that the IIS and basic SharePoint server is setup correctly. Once this is done, the following checks can be performed:
Exception information: Exception type: SecurityTokenValidationException Exception message: ID4220: The SAML Assertion is either not signed or the signature's KeyIdentifier cannot be resolved to a SecurityToken. Ensure that the appropriate issuer tokens are present on the token resolver. To handle advanced token reso-lution requirements, extend Saml11TokenSerializer and override ReadToken. at Microsoft.IdentityModel.Tokens.Saml11.Saml11SecurityTokenHandler.ValidateToken(SecurityToken token) at Microsoft.IdentityModel.Tokens.SecurityTokenHandlerCollection.ValidateToken(SecurityToken token) at Microsoft.IdentityModel.Web.TokenReceiver.AuthenticateToken(SecurityToken token, Boolean ensureBearerToken, String endpointUri) at Microsoft.IdentityModel.Web.WSFederationAuthenticationModule.SignInWithResponseMessage(HttpRequest request) at Microsoft.IdentityModel.Web.WSFederationAuthenticationModule.OnAuthenticateRequest(Object sender, EventArgs args) at Microsoft.SharePoint.IdentityModel.SPFederationAuthenticationModule.OnAuthenticateRequest(Object sender, EventArgs eventArgs) at System.Web.HttpApplication.SyncEventExecutionStep.System.Web.HttpApplication.IExecutionStep.Execute() at System.Web.HttpApplication.ExecuteStep(IExecutionStep step, Boolean& completedSynchronously)
The message is clear – the NAM IDP certificate used to sign the claim was not imported into the SharePoint configuration. However, I had done this several times. In the end, I solved the issue by exporting the DER encoded signing cert and trusted roots from NAM, import them into IE and export as DER encoded format? Does not make sense but it worked.
eu2n Monitorable Trusted login provider ‘NAM41SBA-WSFED-IDP’ is not sending configured input identity claim type ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress’. 88532c9d-526f-f05b-24d0-97a63858d48e
It turns out that the NAM IDP was configured to send the emailaddress attribute within the claim, yet my SharePoint Server was setup to expect the emailaddr attribute. The message allowed me to narrow down the problem. It can also act as an educational tool as you can see the entire processing if the incoming claim, including the various checks being carried out.
Disclaimer: As with everything else at NetIQ Cool Solutions, this content is definitely not supported by NetIQ, so Customer Support will not be able to help you if it has any adverse effect on your environment. It just worked for at least one person, and perhaps it will be useful for you too. Be sure to test in a non-production environment.