UMANTIS CLOUD SSO (ADFS) CONFIGURATION GUIDE Haufe-umantis AG Untertrasse 11 CH-9001 St. Gallen Tel. +41 71 224 01 01 Fax +41 71 224 01 02 umantis@haufe.com www.haufe.com/umantis
INHALT umantis Cloud SSO Configuration Guide... 4 Audience... 5 Pre-requisites... 6 SAML Protocol Elements... 7 Cloud ADFS-based SSO... 9 Customer-provided IDP: ADFS... 9 umantis Service Provider... 9 Circle of Trust... 9 ADFS SSO Configuration Instructions... 10 Send Configuration Information to umantis... 10 Add ADFS Relying Party... 10 Verification... 16 Validate Configuration... 16 Finally... 17 Cloud SSO Troubleshooting... 18 Troubleshooting ADFS 2.0... 18 SSO does not work (error 500)... 18 SSO does not work with chrome browsers... 18 SSO does not work reliably (sometimes requires many attempts)... 18 Ad-hoc reports don't work with SSO... 19 Cloud SSO continuously prompts for login/password... 19 Content blocked - invalid certificate error... 19 Umantis Login/password screen is shown when SSO is enabled... 19 2
The signing certificate does not match what's defined in the entity metadata... 20 SSO does not work (HTTP 400 "Bad Request (Request header too long)")... 20 Cloud SSO is very slow... 20 This content cannot be displayed in a frame / Dieser Inhalt kann nicht in einem Frame angezeigt werden / Die Seite kann nicht angezeigt werden... 20 Windows login appears when doing SSO... 21 Integrated Authentication does not work / Windows logins doesnt work with IE... 23 Invalid Status code in Response... 24 Cloud SSO Tips & Tricks... 25 Step-by-step installation of ADFS 2.0... 25 SSO url status codes... 25 Disable SSO for individual users with NOSSO... 25 Step-by-step guide... 25 Force sso login when Cloud SSO not yet activated... 26 Ignore IP range checking... 26 Umantis custom claim... 26 Multifactor Authentication (MFA)... 27 Enable/Disable ADFS Forms authentication... 27 Enable/Disable Forms authentication of ADFS 2.0... 27 Enable/Disable Forms authentication of ADFS 3.0... 27 How to retrieve ADFS metadata... 29 3
UMANTIS CLOUD SSO CONFIGURATION GUIDE With Microsoft Active Directory Federation Server AU THOR: M AL LKU CAB ALLERO DOCUM ENT VERSION: 2.0 This document describes the requirements to setup a Single Sign On (SSO) configuration on umantis cloud based solutions against a customer s private Active Directory Federation Server (ADFS) 4
AUDIENCE This document is intended primarily for umantis Technical Consultants and customers IT departments. 5
PRE-REQUISITES The customer is responsible for installing Microsoft Active Directory Federation Server version 2.0 (with Update Rollup 3 or newer) or 3.0 on a domain-joined server within his infrastructure. The details for this installation and general configuration are not covered in this document. An understanding of the SAML SSO protocol is useful but not absolutely required. Some basic elements are presented in this document but the reader is encouraged to seek relevant resources (e.g. http://saml.xml.org/saml-specifications) for a more complete description. 6
SAML PROTOCOL ELEMENTS umantis Single Sign On architecture is based on the SAML 2 standard and more specifically on the SAML Web Browser SSO Profile that is widely used on the Internet and specifically supported by Microsoft s ADFS technology. The SAML infrastructure defines two key components: the Service Provider (SP), for all practical purposes: the umantis cloud application, and the Identity Provider (IDP) which is responsible for checking credentials and authorizing access to protected resources. 7
1. A user interacting via a web browser, attempts to access a resource on the SP 2. The SP determines that a session has not yet been initiated and redirects the user to the IDP for authentication. 3. The IDP request an authentication (e.g. login page) from the user 4. The user provides authentication (e.g. user & password) 5. The IDP authorizes the user and allows the SP to establish a session umantis provides a default IDP for conventional logins where requested user and password credentials are checked against a database managed within its internal infrastructure. Some customers request a tighter integration into their internal working environment so that their existing domain credentials may be used to authorize access to their umantis solution without having to manage a separate set of user and passwords. umantis supports this scenario with its Cloud SSO. 8
CLOUD ADFS-BASED SSO Cloud SSO is rather straightforward as long as the customer can provide his own SAML2-capable Identity Provider. CUSTOMER-PROVIDED IDP: ADFS Where customers already have an Active Directory backed windows domain, the most common configuration involves the usage of Microsoft s ADFS component which is basically a lightweight service that extends Active Directory to make it SAML2-capable. Note: ADFS versions older than 2.0 are not supported UMANTIS SERVICE PROVIDER umantis applications are already SAML2-enabled by default, i.e. they are standard SAML Service Providers. CIRCLE OF TRUST A secure SSO configuration requires the SP and the IDP to KNOW OF E ACH OTHER, in such a way that they can ascertain that the counterparty is legitimate. In SAML, this is achieved by configuring a CIRCLE OF TRUS T that involves exchanging metadata, signing and encryption certificates that ensure mutual authentication as well as the confidentiality of exchanged data. 9
ADFS SSO CONFIGURATION INSTRUCTIONS This section describes the precise elements that umantis and the customer must exchange as well as the configuration the customer must perform on their Active Directory Federation Server in order to establish the Circle of Trust required for Cloud SSO. The process always starts with a configuration on a umantis test sso server in order to validate the all technical aspects of the configuration as efficiently as possible. Important Note: during the SSO configuration test phase, it will be necessary to temporarily turn off password expiry in the umantis solution. ADFS Metadata SEND CONFIGURATION INFORMATION TO UMANTIS Option 1) send the ADFS metadata url to your ADFS metadata to umantis, typically: https://your_adfs_host_name/federationmetadata/2007-06/federationmetadata.xml Option 2) if the ADFS metadata url is not accessible from the Internet, load it in a browser by yourself, save it to a local file named idp.xml and send that file to umantis. SSO IP Ranges All users of the system are not in the domain (e.g. internet job applicants). Our system looks at the IP address of the http request to determine whether SAML2 login or standard user password should be performed. In many cases, the required IP addresses are those of the proxies through which most customers route their outgoing internet traffic. This information is not critical during the initial configuration but if no SSO IP range is provided by the time SSO is activated, only domain users will be able to access the umantis system. ADD ADFS RELYING PARTY 10
1. Wait for umantis confirmation that your metadata has been activated. You will receive the UM AN TISM ETAD AT AURL and the UM AN TISSPEN TI TYID that are required in the following steps in the confirmation email. 2. Use the ADFS Management tool. 3. Navigate to Trust Relationships / Relying Party 4. Use the Add Relying Party Trust function to import the umantis service provider using the UM AN TISM ETAD AT AURL Note: if no access from the ADFS server to the umantis server is possible, you may save the XML returned from the above url in any workstation and manually import it in ADFS. The following steps remain unchanged. 5. There may be warning that not all data could be imported. You can safely ignore it. 6. When asked whether you want to add Claim Rules select Yes to enter the Edit Claim Rules dialog. 7. For ADFS 2.x 1. Add a generic LDAP rule where you map the internal Active Directory LDAP attribute for the umantis login to outgoing UPN claim type 1. On the Issuance Transform Rules tab, click Add Rule. 2. On the Select Rule Template page, select Send LDAP Attributes as Claims. Click Next. 3. On the Configure Rule page, type the name (e.g. UPN) of the claim rule in the Claim rule name field. 4. From the Attribute Store drop-down list, select Active Directory. 5. In the Mapping of LDAP attributes to outgoing claim types section, select the same attribute as in 7. e. 6. Under Outgoing Claim Type, select UPN. 2. Create an additional Custom Rule with the following definition: c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"] => issue(type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.issuer, OriginalIssuer = c.originalissuer, Value = c.value, ValueType = c.valuetype, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:saml:2.0:nameid-format:transient", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "youradfsentityid", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "umantisspentityid"); Where: - YOURADFSENTI TYID is usually of the form: http://your_adfs_host_na ME/adfs/services/trust - UM AN TISSPEN TI TYI D is provided to you in Step 1 (looks like url but is only used as identifier) 8. For ADFS 3.x (Windows Server 2012R2 or newer) 1. Add a generic LDAP rule where you map the internal Active Directory LDAP attribute for the umantis login to the outgoing umantis custom claim type 11
1. On the Issuance Transform Rules tab, click Add Rule. 2. On the Select Rule Template page, select Send LDAP Attributes as Claims. Click Next. 3. On the Configure Rule page, type the name (e.g. umantisid) of the claim rule in the Claim rule name field. 4. From the Attribute Store drop-down list, select Active Directory. 5. In the Mapping of LDAP attributes to outgoing claim types section, under LDAP Attribute, select SAM-Account-Name or E-Mail-Addresses or any other suitable unique identifier that maps to existing umantis Talent Management account names. 6. Under Outgoing Claim Type, type http://umantisid. 7. Click Finish, and then click OK. 2. Create an additional Custom Rule with the following definition: 12
c:[type == "http://umantisid"] => issue(type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.issuer, OriginalIssuer = c.originalissuer, Value = c.value, ValueType = c.valuetype, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:saml:2.0:nameid-format:transient", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "youradfsentityid", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "umantisspentityid"); Where: - YOURADFSENTI TYID is usually of the form: http://your_adfs_host_na ME/adfs/services/trust - UM AN TISSPEN TI TYI D is provided to you in Step 1 (looks like url but only used as identifier) 13
3. Add a generic LDAP rule where you map the internal Active Directory LDAP attribute for the umantis login to outgoing UPN claim type 14
1. On the Issuance Transform Rules tab, click Add Rule. 2. On the Select Rule Template page, select Send LDAP Attributes as Claims. Click Next. 3. On the Configure Rule page, type the name (e.g. UPN) of the claim rule in the Claim rule name field. 4. From the Attribute Store drop-down list, select Active Directory. 5. In the Mapping of LDAP attributes to outgoing claim types section, select the same attribute as in 7. e. 6. Under Outgoing Claim Type, select UPN. 7. Click Finish, and then click OK. 9. After importing the metadata, open the Settings dialog and: 1. On the Encryption Tab, check that the umantis_te Certificate is selected. 2. On the Signature Tab, check that the umantis_ts Certificate is selected. 3. On the Advanced Tab, change the security algorithm to SHA1 15
VERIFICATION Your configuration should be similar to this: VALIDATE CONFIGURATION The Cloud SSO configuration can be validated with a user that has a domain account even if he has no umantis Talent Management account by visiting the umantisssotesturl that will be provided to you during the process: If sso was successful, you should see: Your SSO login succeeded user=your.login.identifier metaalias=http://sso.umantis.com/sp-customer 16
FINALLY Once the technical configuration has been validated, our Customer Service will complete the process with the customer s umantis administrator in order to plan the final pre-requisites to SSO activation. The very last steps involve activating the SAML configuration on production servers, which will lead to a new metadata that we will communicate to the customer, and then a last sanity check before activating Cloud SSO as the default authentication for all customer users. Note: once activated, all logins will be handled by SSO by default (except for those outside the SSO IP range). However, it is possible to force an non- SSO login, for instance to login into a dedicated admin account, by appending the following parameter to a umantis URL: https://some_umantis_url&v4login=1 17
CLOUD SSO TROUBLESHOOTING TROUBLESHOOTING ADFS 2.0 Check out this article on technet: http://technet.microsoft.com/en-us/library/adfs2-troubleshooting-things-to-check%28v=ws.10%29.aspx SSO DOES NOT WORK (ERROR 500) a) Make sure ADFS entry is configured with SHA-1 in signing algorithm. b) Make sure the rules are defined in the order specified in the documentation. c) Make sure there are no typos in custom rules. The sp entity id or idp entity id may be incorrect (e.g. missing.de prefix for german customers). Also, sometimes https is used instead of http in the entityid; these are id's and not actual urls. SSO DOES NOT WORK WITH CHROME BROW SERS This often occurs when a self-signed certificate is used and chrome provides no feedback in the browser. Solution: Customer IT must install a proper certificate on their ADFS server SSO DOES NOT WORK RELIABLY (SOMETIMES REQUIRES MANY ATTEMPTS) This could be an "infinite redirects" problem. To make sure, ask the customer to perform a Fiddler trace of a failed login attempt (anonymous session). If many successive connection to customer ADFS server (up to 8) can be seen we most likely have an "infinite redirect". To be 100% sure, ask a customer system administrator to check if KB2843638 patch is installed on ADFS server. Solution: There is a known issue with Microsoft's KB2843638 patch. There are two possible solutions to this issue (must be performed by customer on their own ADFS server): a) Uninstall KB2843638 (usually prefered solution for customers) b) Install the KB2896713 hotfix on top of the KB2843638 patch. Please note that the 2896713 is not a "well tested" hotfix and therefore you have to request it by e-mail. 18
AD-HOC REPORTS DON'T WORK WITH SSO Old generation ad-hoc reports cannot work with CloudSSO. Solution: All ad-hoc reports must be converted to the new xlsreport format in order to be SSO-compatible. CLOUD SSO CONTINUOUSLY PROMPTS FOR LOGIN/PASSWORD This is a known issue if customer is using Firefox Version 3.6.3. Solution: Set network.auth.force-generic-ntlm=true in Firefox configuration. Details can be found here. CONTENT BLOCKED - INVALID CERTIFICATE ERROR This usually happens when the customer installed just a self-signed certificate instead of proper SSL certificate on his ADFS server. Solution: Customer's IT must install a proper certificate on their ADFS server; nothing we can do. UMANTIS LOGIN/PASSWORD SCREEN IS SHOW N WHEN SSO IS ENABLED Even though SSO is enabled and the customer is on the corporate LAN, the login/password screen is shown instead of an automatic login. Solution: There are several possible causes to this problem: a) If the browser url ends with ssocode=iprange then the user's ipaddress is not in the configured SSO range b) If the browser url ends with ssocode=denied then the user was explicitly denied sso through ADFS configuration (must be fixed by customer) c) If the browser url ends with ssocode=disabled then the user was explicitly disabled through ADFS configuration (must be fixed by customer) d) If the browser url does not contain an ssocode parameter then the user has an Active Directory account but no umantis account e) Issue occurs because we used an alias for our SSO server. Before I have configured a c-record (alias) in DNS for sso.acme.net, but running in the problem with the login mask. Solved by configuring an a-record in DNS. f) Check that all users are granted access by default in ADFS access control configuration 19
THE SIGNING CERTIFICATE DOES NOT MATCH W HAT'S DEFINED IN THE ENTITY METADATA Cloud SSO error: The signing certificate does not match what's defined in the entity metadata. This is usually due to an automatic certificate roll-over which is configured on ADFS to occur yearly by default. Solution: The customer should send an up-to-date version of the IdP xml metadata to umantis support. SSO DOES NOT WORK (HTTP 400 "BAD REQUEST (REQUEST HEADER TOO LONG)") Customer gets a HTTP 404 Error. In the requested Browser logs you see a HTTP 400 Bad Request (Request header too long) Error. Solution: Customer should follow this article: http://support.microsoft.com/kb/2020943 CLOUD SSO IS VERY SLOW The request to ADFS takes a very long time to complete. Solution: It could be that the system is configured to Automatically Detect Proxy Settings or is configured to use a Proxy Configuration script. This configuration is found inside Internet Explorer s Tools > Internet Options > Connections > LAN Settings The performance problem can arise when the proxy determination process (WPAD) takes a long time to complete (either fail or succeed), or when the URL of the automatic configuration script is unreachable. THIS CONTENT CANNOT BE DISPLAYED IN A FRAME / DIESER INHALT KANN NICHT IN EINEM FRAME ANGEZEIGT WERDEN / DIE SEITE KANN NICHT ANGEZEIGT WERDEN this problem can occur when the customer enables Login Form authentication on his IdP for external users. By default, the web server (e.g. IIS) is often configured to send "X-Frame-Options-HTTP-Headers" headers that instruct the browser to prevent the page from being displayed within an iframe. Our solution performs the sso exchanges within an IFrame by default in order to display the progress (spinning wheel) indicator. Solution: 20
There are two possible solutions: 1) Customer changes his "X-Frame-Options-HTTP-Headers" web server configuration to enable embedding with umantis.com domain 2) Customers requests that umantis supports turns off iframe option. Without this option, the "Connection in progress" indicator will no longer be available. WINDOWS LOGIN APPEARS WHEN DOING SSO If a windows login appears during the sso login phase, the following root causes are possible: User is not logged into Domain ( Windows ) ADFS Server is not in Trusted Zone ADFS Authentication Policies are configured to require ADFS login page by default. How to check in Internet Explorer: 21
22
There should be the url to the adfs server listed in Websites section INTEGRATED AUTHENTICATION DOES NOT WORK / WINDOWS LOGINS DOESNT WORK WITH IE Problem could be that in IE the User Authentication Settings in Internetoptions are not correctly set. Solution 1: Place ADFS Server in local intranet 1. Select Internetoptions > Security > Local Intranet 2. Click Sites and add https://<your_adfs_server> and Click OK 3. Click Custom level... and make sure that "User Authentication > Logon" is set to: "automatic logon only in intranet zone" 23
Solution 2: Place ADFS Server in Trusted Sites 1. Select Internetoptions > Security > Trusted Sites 2. Click Sites and add https://<your_adfs_server> and Click OK 3. Click Custom level... and make sure that "User Authentication > Logon" is set to: "automatic logon with current username and password" INVALID STATUS CODE IN RESPONSE In most cases, this results from a configuration problem on the customer side. In most cases, there is a mistake or a typo in the Custom Rule (e.g. error in spentityid wrong). If the customer does not spot the problem by himself, ask him to send the content of the custom rule (or a screenshot) by email and double-check. If nothing appears to be wrong with the custom rule, ask the customer to have a look at the ADFS Event Log to get more details on the error. If he can't spot the problem by himself, ask him to email an export of the ADFS event log. 24
CLOUD SSO TIPS & TRICKS STEP-BY-STEP INSTALLATION OF ADFS 2.0 Check out this article on technet: http://technet.microsoft.com/en-us/library/adfs2-step-by-step-guides%28v=ws.10%29.aspx SSO URL STATUS CODES In case of errors, an ssocode parameter is appended to the resulting url. Possible values are: denied: user exists in AD but ADFS authorization rule denies access nosubject: missing subject in assertion (error in IdP configuration) iprange: user ip address is outside of configured SSO range disabled: presence of http://schemas.umantis.com/custom claim with value NOSSO (experimental) DISABLE SSO FOR INDIVIDUAL USERS WITH NOSSO Customers sometimes require that specific do not use SSO even if they exist on Active Directory. This cannot be satisfied with sso ip range configuration since the account must be disabled from any ip. A possible solution might be the using the v4login=1 url parameter although the downside is that if it is forgotten just once then the account is converted to sso (password removed). Another solution regarding ADFS access rights is discussed here but it seems that, at some customers, such a denied login is considered a potential security breach and generates alerts. The solution presented in this article is in production at Infineon in order to disable SSO login on special accounts that are shared amongst different users. STEP-BY-STEP GUIDE 25
The configuration must be performed by the customer himself on his ADFS. Create a new custom rule as follows: c:[type == "http://acme.com/claims/accounttype", Value =~ "^(?i)(shared test admin service resource fab project)$"] => issue(type = "http://schemas.umantis.com/custom", Issuer = c.issuer, OriginalIssuer = c.originalissuer, Value = "NOSSO", ValueType = c.valuetype); add v4login=sso parameter to url FORCE SSO LOGIN WHEN CLOUD SSO NOT YET ACTIVATED e.g. https://employeeapp-133.umantis.com/selfservice?v4login=sso IGNORE IP RANGE CHECKING Sometimes it can be useful to force sso even if IP is outside of range. This can be done by adding the sso=true parameter to the url. e.g: https://employeeapp-133.umantis.com/selfservice?sso=true UMANTIS CUSTOM CLAIM It is possible to setup a claim that generate custom attributes from umantis on ADFS. This can be done with two extra rules: 1. Define a standard rule that maps an LDAP attribute to a claim (e.g. LDAP-Email-Address => Claim-emailAddress 2. Generate a custom rule (umantis_custom) as follows: c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/emailaddress"] 26
=> issuetype(type = "http://schemas.umantis.com/claims/custom", Issuer = c.issuer, OriginalIssuer = c.originalissuer, Value = c.value, ValueType = c.valuetype); Currently, a umantis custom claim containing the value "NOSSO" will cause SSO to be denied by multitenant-sp Example: a umantis custom rule that disables SSO when no email is defined: NOT EXISTS([Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/emailaddress"]) => issuetype(type = "http://schemas.umantis.com/claims/custom", Value = "NOSSO"); MULTIFACTOR AUTHENTICATION (MFA) ADFS 3.0 has specific features to support multifactor authentication that don't require any changes on the Haufe-umantis side. Technet https://technet.microsoft.com/en-us/library/dn486781.aspx ENABLE/DISABLE ADFS FORMS AUTHENTICATION ENABLE/DISABLE FORMS AUTHENTICATION OF ADFS 2.0 See: http://social.technet.microsoft.com/wiki/contents/articles/1600.ad-fs-2-0-how-to-change-the-local-authentication-type.aspx ENABLE/DISABLE FORMS AUTHENTICATION OF ADFS 3.0 Technet https://technet.microsoft.com/en-us/library/dn486781.aspx 27
28
HOW TO RETRIEVE ADFS METADATA https://hostname/federationmetadata/2007-06/federationmetadata.xml Where hostname must be replaced by the actual ADFS server's host name. This url is often not accessible from the Internet. In these cases, the customer himself must save the retrieved XML and send it by email 29