Sitekit CMS Technical Guide. Authentication Methods. Ian Stewart, Sitekit Solutions Ltd 19/01/2017

Transcription

1 Sitekit CMS Technical Guide Authentication Methods Ian Stewart, Sitekit Solutions Ltd 19/01/2017

2 Address Company Department Author Document Type Document Title Version Number 1.4 Approved Version 1.0 Approved By Document Status Operations Centre Bloxham Mill Barford Road Banbury Oxfordshire 0X15 4FF Sitekit Solutions Ltd Development Ian Stewart Manual Authentication Methods Shaun Wilkinson Draft Created 16/06/2006 Last Modified 19/01/2017 Next Review Date Customer Code Job Number Document ID Publisher Rights [Next Review Date] SSS [Job] 2017 Sitekit Solutions Ltd This document is uncontrolled when printed Development Centre Sitekit House Broom Place Portree Isle of Skye IV51 9HL Change Log Version & date By Changes 26/5/2016 IS Substantial update of WIA 18/1/2016 IS Caveat on WIA in section 4.3 in wake of F & G

3 Table of Contents 1.0 Introduction Typical uses Who is this document for? Security Implementing Authentication Prerequisites Example Service Response required Implementing LDAP Authentication Prerequisites Download the LDAP Authentication web service Installing the LDAP Authentication web service Service Response required Configuring a Sitekit CMS site to use LDAP Authentication Sitekit Variables Configuration Notes Windows Integrated Authentication (WIA) Introduction Prerequisites Configuration Testing WIA Defining Trust Application of rights derived from WIA Considerations when using WIA Code sample Further information Disclaimer Copyright... 18

4 1.0 Introduction Sitekit CMS offers the ability to plug in additional authentication providers, enabling users other than Sitekit CMS Users to be authenticated and logged into the Sitekit Control Panel (or an extranet) as a member of a Sitekit CMS User Group. Additional authentication providers are implemented as web services. Sitekit CMS supports any 3 rd party authentication source as long as the right receptor for Sitekit to authenticate against is built. The most common of these is LDAP so it is LDAP that is cited in the examples A common requirement of many customers is for large numbers of their staff to be able to log into Sitekit CMS without them having to create large numbers of corresponding Sitekit CMS Users. To meet this requirement, Sitekit Solutions Ltd has made available an LDAP Authentication web service which can be downloaded and installed on customers servers. The LDAP Authentication web service uses LDAP (Lightweight Directory Access Protocol) to query a customer s Active Directory in order to authenticate a user. When a customer s Sitekit CMS site is configured to use the LDAP Authentication web service, users can log into Sitekit CMS by providing their Windows username and password. Differential levels of access and permission sets can be applied by associating different Sitekit CMS User Groups with corresponding Windows User Groups. This document describes the steps involved in setting up and configuring such authentication. This document comprises part of the Sitekit CMS Extensibility Framework. 1.1 Typical uses Existing system login Sitekit can be authenticated against any 3 rd party receptor section2 LDAP Authentication (Third Party Authentication) The LDAP Authentication web service is primarily used to enable users of a customer organisation to log into Sitekit CMS protected content or Sitekit CMS Admin using their Windows username and password. Login is NOT automatic. Section 3 Windows Integrated Authentication (WIA) Windows Integrated Authentication allows active directory users access to Sitekit CMS content automatically, based on the users current logged on credentials. There is no credential challenge to the user. However, the logged on credentials will not work with Sitekit Admin therefore standard Sitekit based usernames and password must be used for site administration. Section Who is this document for? This document is aimed at technical integration partners who are interested in integrating Sitekit CMS with existing corporate environments. It can also apply to corporate IT staff as it explains how and why the LDAP authentication API is set up this way. Such partners and staff should be experienced in web development as they will need to be familiar with the architectural concepts of web services (which can be written in any language though the examples here are in VB.net) and also familiar with Active Directory syntax and LDAP. 1.3 Security We advise that the authenticating web server should be exposed by SSL and if possible the IP's that can call the server should be restricted to the IP's of the authenticating Sitekit CMS server. Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 4 of 19

5 2.0 Implementing Authentication 2.1 Prerequisites The Sitekit Authentication system requires: An authentication service exposed by a URL (can be webservice) POST is used so the passwords are not logged in the server log on the authenticating web server.) 2.2 Example An example could be the following dummy web service If there are any other parameters hard coded in the POST data collection. then this other parameters will also be added to the This web service itself could be performing and LDAP query or could be authenticating against any 3 rd party database or system. 2.3 Service Response required Sitekit needs to receive the following <authenticated>true</authenticated> False or any other malformed string will not authenticate 3.0 Implementing LDAP Authentication 3.1 Prerequisites The Sitekit LDAP Authentication Web Service requires: Microsoft.Net Framework (v1.1 or 2.0) Microsoft Internet Information Services (IIS) v5 or higher Active Directory Domain Controller 3.2 Download the LDAP Authentication web service The Sitekit LDAP Authentication Web Service is available for download at The download is a single zip file, LDAPAuthv4.zip, which contains: LDAPAuthV4.asmx - a web service file (un-compiled code) web.config - a configuration file Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 5 of 19

6 The class library is a compiled part of the Microsoft.Net Framework, for use with active directories. The other 2 files are in plain text and can be viewed and edited. The source code for the web service (LDAPAuthv4.asmx) is provided so that it may be customised if desired. 3.3 Installing the LDAP Authentication web service To install the LDAP Authentication web service on your web server, follow these steps: 1. Unzip the files & folders in LDAPAuthentication.zip to the web root of IIS, e.g. c:\inetpub\wwwroot 2. Check there are 3 files present as follows: i) c:\inetpub\wwwroot\ldapauthentication\ldapauthv4.asmx ii) c:\inetpub\wwwroot\ldapauthentication\web.config iii) c:\inetpub\wwwroot\ldapauthentication\bin\system.directoryservices.dll 3. Open IIS Manager & navigate to "Web Sites/Default Web Site" 4. Right click on the LDAPAuthentication folder and select "Properties" 5. In the "Directory" tab, click the "Create" button next to the "Application Name" text box 6. Click "OK" 7. Open the "web.config" file in a text editor 8. Edit the 'value' attribute of the element beginning '<add key="ldapserver"' to hold the address of your LDAP server e.g. <add key="ldapserver" value="ldap://myldapserver" /> 9. Edit the 'value' attribute of the element beginning ' <add key="domainprefix"' to hold the domain name associated with the LDAP server set in step 8 e.g. <add key="domainprefix" value="mydomain" /> 10. Check that the LDAP Authentication Web Service has been installed successfully, by right clicking LDAPAuth.asmx in the right-hand pane, and select "Browse". The LDAPAuth web service introduction page should appear. Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 6 of 19

7 The first operation, GetActiveDirectoryEntry, accepts the following parameters IsAuthenticated - authenticates a user for a group in Active Directory Parameter UserName Password group Comments The username of the user to be authenticated The password of the user to be authenticated The name of a Windows User Group (defined in Active Directory) Note: If no group name is specified then the built in domain users group is assumed. 1. Click the "GetActiveDirectoryEntry" link and enter a Windows username, password & group and click the "Invoke" button to test the web service. An XML document should be displayed, containing "<authenticated>true</authenticated>" if correct login details were entered. 3.4 Service Response required As before Sitekit needs to receive the following <authenticated>true</authenticated> False or any other malformed string will not authenticate 3.5 Configuring a Sitekit CMS site to use LDAP Authentication Once the LDAP web service has been installed, Sitekit CMS can be configured to use it. This involves associating the LDAP Authentication web service with a Sitekit CMS User Group and a Windows User Group. 1. Login into Sitekit CMS Control Panel 2. Navigate to CMS->User Groups 3. Click "Add a New User Group" or select an existing user group and click "Edit Admin Rights" 4. Edit the "Group Name" and admin rights as appropriate 5. In the "Web Service Authentication URL" field below, enter the address of the LDAP Authentication web service, making sure to include the name of the Windows user group to which this Sitekit CMS user group corresponds, as the value of the "group" parameter, e.g.: Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 7 of 19

8 6. Save the group details 7. Check that it works by logging out and logging into Sitekit CMS admin using a Windows username & password 8. If you wish users in different Windows User Groups to be able to log in with different sets of permissions, configure a separate Sitekit CMS User Group for each corresponding Windows Group. 9. To set the order in which groups are checked to authenticate the user, use the Order User Groups for Alternate Authentication part of the User Group tab in the Control Panel, e.g.: 3.6 Sitekit Variables With the LDAP Authentication web service a number of Sitekit variables can be used. These pull their contents from the user details stored in active directory. They can be useful for personalizing pages where LDAP authentication is in use. Some example data is shown below: <userparam name="fullname">martyn Bradshaw</userparam> <userparam name="telephone"> </userparam> <userparam name="fax"> </userparam> <userparam name=" ">martyn.bradshaw@sitekit.net</ userparam> <userparam name="depart ment ">Sysadmin</userparam> <userparam name="job">systems Manager, MCSE</userparam> In addition it is possible to also map up to 6 additional custom fields to other active directory attributes. For a full list of Sitekit variables please see the Proprietary Sitekit CMS Syntax document. 3.7 Configuration Notes Sitekit CMS doesn't currently support multiple groups for users, so a user can only be logged in as a member of a single Sitekit CMS user group. Therefore, if there are several Sitekit CMS user groups set up, each configured for LDAP authentication with a different Windows user group, the user will be logged in as a member of the first Sitekit CMS user group whose LDAP authentication service returns true. (This only affects users who belong to more than one Windows user group). Extranet login pages feature a Forgot your username/password link. This feature only applies to users that are registered on the Sitekit CMS admin system and will not work when using LDAP authentication. It is possible to add multiple LDAP servers and domains to the LDAP authentication web.config file. In a well connected domain forest this allows the web service to authenticate users in other trusted domains. An example is given below: Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 8 of 19

9 <add key="ldapservers" value="ldap://ldapserver1, LDAP://ldapserver2" /> <add key="domainprefix" value="domain1, domain2" /> The order of the values in the keys above is important. Ldapserver1 is associated with domain1 only, ldapserver2 is associated with domain2 only etc. Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 9 of 19

10 4.0 Windows Integrated Authentication (WIA) 4.1 Introduction The requirement is to enable users logged in to a Windows active directory domain to automatically login to deployed restricted front-end pages on a Sitekit CMS-based Intranet. Back end users (site editors etc) will login using the normal Sitekit CMS login interface. Windows Integrated Authentication (WIA) will not work for Sitekit Admin logins. The feature will work by associating Sitekit CMS User Groups with Windows User Groups, so that an authenticated Windows user is automatically recognised as a member of the associated Sitekit CMS User Group, based on their Windows user credentials. The Windows user will then gain the access rights of that Sitekit User Group, and will be able to access those pages that are accessible to that Sitekit User Group. Note: this feature is only available on deployed Sitekit CMS servers, it is not be available on hosted accounts. WIA is implemented in two different ways in the CMS, the logic is described in a later section a) TryUnchallengedWindowsAuthentication this provides unchallenged WIA access in conjunction with a looks up of the relevant users directory entry via LDAP it then maps the windows user to a local sitekit user b) TryWindowsAuthentication this provides unchallenged WIA in conjunction with a single associated group association Approach 1 is richer approach with more information available on the relevant intranet about the end user. However it depends on reliable local access to the relevant AD OU via an LDAP query. Often it s possible to authenticate via remote domain by mapping users into universal AD groups and setting up one way or two way trust relationships. Such complication will prevent the mapping of filed via LDAP but may still support the simple second option. The first option also supports mapping of users to multiple sitekit groups, the second doesn t The configuration covers both options 4.2 Prerequisites Windows Integrated Authentication requires: Active Directory based network only Web Server must be part of the active directory domain or have trust relationship with the relevant AD domain All users requiring access to the system must be a member of 1 common active directory group (such as domain users) 4.3 Configuration 1. Ensure Windows Authentication is installed and enabled in IIS. For IIS 7 Windows Authentication is not installed by default and so must be added via Server Manager / Add Role Services. Once it is installed it is disabled by default, therefore you must ensure Windows Authentication is enabled for the site in IIS 7 / Authentication settings. (see caveat in 4.3 item 2) Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 10 of 19

11 2. You set up the web.config as shown below approximately. The allow roles is needed if using 8b but not for 8a 3. You add the relevant LDAPServers to the keys here (the domainprefix setting is no longer used). The key will accept comma separated values. This is needed for 8a but not 8b 4. Add the following location blocks to web.config, normally between the CodeSnippetParserSetting and system.net sections. (see caveat in 4.3 item 2) <location path="rss.aspx"> <system.web> <authorization> <allow users="?"/> </authorization> </system.web> </location> <location path="ws"> <system.web> <authorization> <allow users="?"/> </authorization> </system.web> </location> <location path="admin/ws"> <system.web> <authorization> <allow users="?"/> </authorization> </system.web> </location> <location path="directory"> <system.web> <authorization> Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 11 of 19

12 <allow users="?"/> </authorization> </system.web> </location> Note: Sitekit may reference back to these locations so anonymous access must be allowed. This will ensure correct functionality of data islands and feeds. See WIA considerations below 5. In Sitekit site setting you check this box 6. You map any stuff in the AD fields below that setting (8a only) 7. The relevant site needs added to the intranet security zone in IE.(see trust section below) 8. Sitekit does the following: a. Looks for the checkbox being ticked in item 4 if it is it uses method TryUnchallengedWindowsAuthentication and takes the windows user and goes to the ldap server in 2 and maps the fields listed in 5 to create a local sitekit user, authenticates them and then accesses the site as that user. In this mode every windows user will create a mapped sitekit user so the relevant sitekit group that matches the identically named AD group will gradually fill up. You d need to create the matching group name beforehand. The test section will then look like this Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 12 of 19

13 b. If the checkbox isn t ticked then it checks that you re not on a sitekit installation ie not *.sitekit.net, if you re not then it authenticates using the windows user via method TryWindowsAuthentication and then allocates the rights based on this box in the relevant group matching the roles name in the web.config as shown in item 1 With the tie in to the group at the bottom of the group admin c. If the latter method is used then there s no fields mapped just a group identified, the test will then show only the windows user and the relevant group id as shown below. Finally, If there s no joy in the windows authentication sequence above the code checks for authenticated users then it has a stab at logging in via IP 4.4 Testing WIA When you re testing and checking this you bear in mind it never works on the machine on which IIS is running. You need to test it on a machine on the same domain that is not the IIS server. Put in a test page with magic words to Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 13 of 19

14 see if stuff states operating. The following is useful to paste in and is the code snippet that the example outputs above use. <h1>welcome to our website</h1> <hr/> Auth method: :::authentication_method::: <br/> Windows user: :::windowsuser::: <br/> Sitekit user: :::username::: <br/> PeopleID: :::peopleid::: <br/> Name: :::firstname::: :::lastname::: <br/> Group: :::usergroupid::: <hr/> 4.5 Defining Trust Ensure the deployed Sitekit CMS site is using a domain which is trusted. An intranet is normally trusted by default using a group policy. If a policy is not set, each user will require to: 1. Navigate to Tools->Internet Options->Security in Internet Explorer 2. Click the Trusted Sites icon and click the Sites button 3. Type in the domain of the deployed Sitekit CMS site and click Add 4. Click Close and OK to save & exit You must ensure front end and admin domains are trusted otherwise repeated windows login prompts will be shown. It may be possible to set up some of these aspect on a corporate network via policies. When WIA is turned on any domains used which should not throw a login box must be set as either trusted sites or preferably, local intranet sites. On big networks this is normally handled by group policy, so we need to ask the customer to make any changes we need. Only once that is done will credentials be handed over to IIS from the browser automatically as different pages are loaded in the CMS. 4.6 Application of rights derived from WIA This is as described on the help site and provided as an example of restricting access rights to only users in a single group 1. Create the relevant asset class Under the configure tab and asset classes add a new asset class in case title WIAtest Add the relevant group to the new asset class via clicking on the asset class name after creation In this example all other user have had their read rights removed and the member group has read rights. The Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 14 of 19

15 member group is the one set up in section 8b. The member groupid is the one that is detected in the test code using the :::usergroupid::: magic word 2. Apply the asset class to the asset branch of interest via right clicking on the branch and then selecting folder properties. The new asset class is then chose and applied recursively to the assets underneath. This could be done at root level to apply to all or alternatively the permissions below could be applied to the default class at root level. The overall effect is that any windows authenticated user will have unchallenged access to the chose page that the asset class is applied to (in this case a single branch. All other user will get a CMS login prompt Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 15 of 19

16 4.7 Considerations when using WIA 1. Sitekit variables that link to active directory under third party authentication (see section 3.6) will not work with Windows Integrated Authentication. This includes the :::FULLNAME::: variable which can be of use when personalising intranet home pages. 2. When Windows Integrated Authentication is used there may be problems with data islands that consume files located in a site file library. Currently it is best to host these kind of consumed files at xsl.sitekit.net or in a physical folder within the Sitekit CMS application folder. In the past when issues have occurred with this the syptomes are that the page itself loads OK but the data island 401s and causes an error. This is true even when the data island in question is one of the expection outlined in item 4. If this occurs then a solution is to change all the exception in 4 from? to * (eg accepting for anonymous users not just authenticated users). At the same time anonymous authentication shoulds also be enabled (item 1) 3. Calls to items that are grabbed for later use such as MHT files for new broadcast via the channel er and PDF file creation, web services and RSS feeds can be broken by WIA as the relevant code cannot pass over the authentication details. These may be added as exceptions via the web.config edit seen in item 4 The Channel er requests newsletter pages via http and thus needs authentication. This means that the channel er need run as a scheduled task under a user that has access to the relevant pages (ie not a local server admin user). 4. The fields are not re-refreshed over again until the session time elapses. So there's no real-time update from changes to the AD 5. Pages don t index easily for search getting pages to be indexed is more difficult. Pages need created then visited by an authenticated user with read access for that page to be added to indexable content. In addition the visibility needs to be correct and the pages asset class needs to not have a universal read and it needs to be an extranet (all other users barred). Generally its harder to get pages to index in this environment which cause issues in initial population before there's any 'natural visitors'. 6. Multiple AD domains - it's relatively common in AD system to have the same user in more than one domain. This will produce duplicate Sitekit users in the CMS 7. Edit profile and Logout as nav menu item will not be shown to users logged in this way. 4.8 Code sample This is the code that defines the sequence above. Starts with the LDAP windows auth version and then if that s not set tries standard WIA without and LDAP field mapping. If both those are not used it then checks the IP range for access. If allowautoldap Then TryUnchallengedWindowsAuthentication(siteID, windowsuser) ElseIf IsDeployedServer() Then Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 16 of 19

17 End If TryWindowsAuthentication(siteID, windowsuser) If Not _UserAuthentic Then End If TryAutoIPLogin(siteID, IP) IsDeployedServer definition is below Dim regexp As String = "secure([0-9][0-9]*)*\.(dev\. beta\. fix\.)?[0-9]?sitekit\.net" Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 17 of 19

18 5.0 Further information This guide provides an overview of the capabilities of Sitekit CMS API and illustrated how it can be used to transform your website. Sitekit CMS has a range of technical guides detailing the latest features of Sitekit CMS and web management technology. These are available on request and also appear on the website. Sitekit corporate site. Sitekit maintains a knowledge base of articles organised by category in the Sitekit CMS support system. This would also be where registered users can submit support tickets for changes requests or report bugs. An interface to this system is one of the CMS options but you can also access it from the URL below. - Sitekit knowledge base. The Sitekit CMS online help system provides a useful source of information for how specific aspects of the administration system work. - Sitekit help. If you have any questions on functionality or prices please do not hesitate to contact us and we can arrange a visit. England Scotland Bloxham Mill, Sitekit House, Barford Road, Broom Place, Banbury, Portree, Oxfordshire, Isle of Skye, UK UK OX15 4FF IV51 9HL Tel: Tel: Fax: Fax: sales@sitekit.net support@sitekit.net 5.1 Disclaimer Information in this document is subject to change without notice. Sitekit Solutions Limited reserves the right to revise and improve its products as it sees fit. This document describes the state of this product at the time of its publication, and may not reflect the product at all times in the future. The use of this documentation is governed by the terms of a oftware licence agreement made between Sitekit Limited and the Licensee. The liability of Sitekit Limited in respect of the documentation and the licensed programs referred to, are set out in that software licence agreement. Sitekit Solutions Limited accepts no liability whatsoever for any use of the documentation or the licensed programs by any person other than a permitted user under the software licence agreement. 5.2 Copyright All rights reserved. All copyright and other rights in this manual and the licensed programs described in this manual are the property of Sitekit Limited. No part of this manual may be copied, reproduced, translated or reduced to any electronic medium or machine readable form without the written consent of Sitekit Limited. Sitekit Ltd Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 18 of 19

19 Publisher Rights: Sitekit Ltd 2012 This document is uncontrolled when printed Page 19 of 19