Application Delivery Management
Application Modernization & Connectivity
CyberRes by OpenText
IT Operations Management
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.
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.
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
$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
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.
<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:AuthenticationStatement AuthenticationInstant="2015-09-11T11:41:53Z" AuthenticationMethod="secure/name/password/uri">
<saml:Attribute AttributeName="emailaddr" AttributeNamespace="http://schemas.xmlsoap.org/ws/2005/05/identity/claims">
<saml:Attribute AttributeName="role" AttributeNamespace="http://schemas.xmlsoap.org/ws/2008/06/identity/claims/">
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:
****** HttpServletRequest Information:
Context Path: /nidp
Servlet Path: /wsfed
Query String: wa=wsignin1.0&wtrealm=urn:SharePoint:portal&wctx=https://sp2013.neil.com/sites/team/
Path Info: /ep
<amLogEntry> 2015-09-11T10:19:08Z DEBUG NIDS STS:
<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
<saml:Conditions NotBefore="2015-09-11T10:04:08Z" NotOnOrAfter="2015-09-11T10:34:08Z">
<saml:AuthenticationStatement AuthenticationInstant="2015-09-11T10:19:08Z" AuthenticationMethod="secure/n
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 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.ExecuteStep(IExecutionStep step, Boolean& completedSynchronously)