Stages Documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
72:kerberos_autologin [2018/07/06 15:48] – bkkr72:kerberos_autologin [2024/02/15 00:00] (current) – external edit 127.0.0.1
Line 1: Line 1:
-[[:72:start|Stages V7.2]] 
- 
 ====== Configure Kerberos Autologin ====== ====== Configure Kerberos Autologin ======
 +
 +** WARNING:  **Stages 7.10 is the last release that supports Kerberos Autologin (SPNEGO). Administrators are advised to migrate to the newer [[:72:integration:saml|SAML Single Sign On]] system as soon as possible.
  
 === Autologin === === Autologin ===
  
-  * **[[:72:autologin_system_design|Autologin System Design**]]**      * The autologin mechanism implemented in Active Directory is based on the Kerberos standard. For HTTP authentication the SPNego token format (RFC4178) is used together with an extension to the HTTP protocol (RFC 4559). +  * [[:72:autologin_system_design|]] 
-      * Kerberos requires a KDC (Key Distribution Center), which is configured by the Active Directory Management Utilities. Each member of the Active Directory maintains a trust relationship to the KDC. For Windows Clients, it is the Computer Account inside the Active Directory. For 3rd party systems (like Unix or Stages) it is a specifically configured user account, which has its credentials exported to a keytab file. Configuring the trust relationship between Stages and the KDC is necessary to enable Autologin support. The following sections will guide you step-by-step through this maintenance process. +  * [[:72:autologin_system_requirements|System Requirements]] 
-  * **[[:72:autologin_system_requirements|System Requirements**]]**      * Client PC +  *  [[:72:autologin_deployment_guide|Deployment Guide]] 
-        * The Client PC has to be a member of the Kerberos realm. Using Microsoft Active Directory, the name of the realm usually corresponds to the name of the Active Directory domain in capital letters. Example: if the company’s Active Directory domain name is “abc.com”, the name of the corresponding Kerberos realm is “ABC.COM”. +      * [[:72:enable_support|]] 
-        * Auto-login will only be possible for users who log into the client PC using an Active Directory domain account. Local user accounts are not suitable for the autologin-feature as user authentication is handled by Kerberos only. +      * [[:72:setup_directory|]] 
-      * Internet Browser +      * [[:72:configure_jaas_jgss|]] 
-        * The internet browser has to be configured to use SPNego authentication for trusted webpages +      * [[:72:configure_browser|]] 
-      * Network Configuration +      * [[:72:non-spnego|non-spnego]] 
-        * Time has to be synchrozined within the Active Directory Domain (clients and servers) as well as between the Stages server and the Active Directory domain because every Kerberos ticket has limited validity. +  * [[:72:kerberos_faq|Frequently Asked Questions (FAQs)]]
-        * It is also of critical importance that your name service is set up correctly. For each device the name service resolution has to work both ways, forward and backwards. Forward resolution resolves a full-qualified domain name to an IP address and backwards resolution resolves the IP address back to the fullqualified domain name. Resolving a hostname to an IP address and the address back to the hostname again, has to result in the same full qualified hostname. +
-      * Stages Server +
-        * The stages server doesn't have to be a member of the Active Directory domain. It can also be installed on a UNIX operating system. +
-  * **[[:72:autologin_deployment_guide|Deployment Guide**]]**      * Enable support for Autologin in Stages +
-        * By default, Autologin is configured to be off. To enable Autologin, set the configuration property “autologin.spnego.enabled” to “true”. This is configured in the appropriate PKitConfig.xml section. See the Stages Administration Guide for details on how to set configuration properties. +
-      * Setup Active Directory +
-        * For Stages to be able to validate the user’s Kerberos ticket it has to maintain a trust relationship with the Kerberos domain. This trust relationship is established by mapping the Stages service to an Active Directory user account and exporting the Kerberos key of that account to the Stages server. For each Stages server instance a separate trust account has to be created! +
-          * Steps: +
-            * Start Active Directory Users and Groups from the Administrative Tools menu and open the context menu of the Users tree node. Select New → User from that menu. +
-            * Enter the server's hostname in the first name field. +
-            * Type a password and check 'Password never expires." +
-            * Click 'Next' and also confirm the summary dialog window. +
-            * Export Kerberos key of the new account to a "keytab" file. +
-            * Open a command window on the Active Directory server and execute the following command: +
- +
-<code> +
-ktpass –princ HTTP/<fqdn>@<KERBEROS-REALM> +
- -mapuser <trust-account-name> +
- -pass <trust-account-password> +
- -out <output-file> +
- -crypto rc4-hmac-nt +
-</code> +
- +
-  * Now you have to securely transfer the "keytab" file to the Stages server +
-  * Configure JAAS and JGSS support on the Stages server +
-  * Java Authentication and Authorization Service (JAAS) +
-  * JAAS is a standard Java API, which has to be configured with your network settings. Please edit the provided example file “/tomcat/webapps/pkit/WEB-INF/conf/jaas.conf” and replace the example values according to your network configuration: +
- +
-<code> +
-de.methodpark.pkit.auth.SpnegoAuthenticator { +
-  com.sun.security.auth.module.Krb5LoginModule required +
-    useKeyTab=true +
-    keyTab="" +
-    storeKey=true +
-    realm="<KERBEROS-REALM>" +
-    debug="false" +
-    principal="HTTP/<fqnd>@<KERBEROS-REALM> +
-} +
-</code> +
- +
-  * Java Generic Security Services (JGSS) +
-      * JGSS is another Java Standard API, which has to be configured with your network information. Please edit the provided example file “/tomcat/webapps/pkit/WEB-INF/conf/krb5.conf” and replace the example values according to your network configuration: +
- +
-<code> +
-[libdefaults] +
-default_realm = <KERBEROS-REALM> +
-default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc +
-default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc +
-forwardable = true +
-[realms] +
-<KERBEROS-REALM> = { +
-kdc = <ad-server-fqdn>:88 +
-} +
-[domain_realm] +
-.<ad-dns-domain> = PKITBUILD.ER.METHODPARK.DE +
-<ad-dns-domain> = PKITBUILD.ER.METHODPARK.DE +
-</code> +
- +
-  * Configuration Test +
-      * To test your JAAS and JGSS configuration in a Stages server environment \\ proceed in the way described below \\ - Open a command prompt and change to the <PKIT_HOME> directory. \\ - Type “bin\testAutoLogin.bat” (on Windows) or “bin/testAutoLogin.sh” (on \\ Unix) and hit enter. \\ - Watch the command prompt for output messages. +
-  * Configuring the Browser +
-      * To use the autologin feature, a browser has to be configured to use SPNego authentication for trusted Intranet sites. Furthermore proxy usage for Intranet sites should be disabled. +
-      * **Firefox** +
-        * Open the Firefox configuration page by typing “about:config” into the URL address bar. You can filter the configuration options by typing “nego” into the search bar. +
-        * Change “network.negotiate-auth.delegation-uris” and “network.negotiateauth.trusted-uris” to the DNS domain name of the Stages server. You are free to use a smaller sub-part like in our example. The original domain name is “pkitbuild.er.methodpark.de”, but we used “methodpark.de” to enable SPNego for the whole company. +
-        * Change the search filter to “proxy” and add an expression like “*.methodpark.de” to the property “network.proxy.no_proxies_on”. +
-      * **Microsoft Internet Explorer** +
-        * Open the Tools > Internet Options menu and select the “Security” Tab. +
-        * Select “Local intranet” and push the “Sites” button. +
-        * Press the "Advanced" Button. +
-        * It is necessary to add the DNS domain of your Stages server to the trusted URLs list. +
-        * Furthermore it is necessary to enable SPNego support for the “Local intranet” zone. Go back to the “Security” Tab and press the “Custom Level” button. +
-        * Scroll down until “User Authentication” and check “Automatic logon only in Intranet zone”. +
-        * Go back to the “Internet Options” dialog box and select the “Advanced” Tab. Scroll down until “Security” and check “Enable Integrated Windows Authentication (requires restart)”. +
-        * Furthermore you have to change the Proxy settings to avoid proxy usage. Go to the advanced proxy settings and add an exception for the DNS domain name of the Stages server. +
-  * Handling of non-SPNego capable browsers +
-      * If autologin support is enabled, Stages expects every browser to be properly configured and capable of SPNego authentication. Browsers which lack support for the SPNego protocol or are not configured properly, will receive an error message when trying to access Stages. To enable Stages to also handle browsers which are not capable of SPNego authentication, the configuration property “autologin.spnego.handleNonCapableBrowsers” has to be set to “true”. +
-      * Please note: When enabling the support of non SPNego-capable browsers, the anonymous access mode “direct” has to be disabled, i.e. has to be set to “login”! Otherwise the Autologin feature will not work, i.e. every user accessing Stages will be logged in as a guest. Please see the Stages Administration Guide for information on how to set configuration properties. +
- +
-  * **Frequently Asked Questions (FAQs)** +
-      * //Will SPNego work with HTTP proxies?// +
-        * No and yes. To avoid difficulties, this manual recommends to disable proxy usage for the Stages server via browser configuration. +
-        * The problem is that the SPNego authentication headers might get modified or even be removed by a proxy. Furthermore a proxy has to take care of not sharing authenticated connections between several clients. There are proxy implementations which are capable of handling SPNego sessions correctly but in general we do not recommend proxy usage. +
-      * //I have messed up my keytab file and need to recreate it. What do I have to do?// +
-        * Ktpass will automatically map a SPN (service principal name) to the user account. Before you can call ktpass again, you have to remove this mapping manually. +
-          * Step 1: Check for assigned SPNs +
-            * +
- +
-<code> +
-C:\temp>setspn -l pkit +
-Registered ServicePrincipalNames for +
-CN=pkit,CN=Users,DC=pkitbuild,DC=er,DC=methodpark,DC=de: +
- HTTP/pkit.pkitbuild.er.methodpark.de +
-C:\temp> +
-</code> +
- +
-  * Step 2: For each SPN, remove it: +
-      * +
- +
-<code> +
-C:\temp>setspn -d HTTP/pkit.pkitbuild.er.methodpark.de pkit +
-Unregistering ServicePrincipalNames for CN=pkit,CN=Users,DC=pkitbuild,DC=er,DC=m +
-ethodpark,DC=de +
- HTTP/pkit.pkitbuild.er.methodpark.de +
-Updated object +
-C:\temp> +
-</code> +
- +
-  * //I use URLs like “[[http://localhost:8080|http://localhost:8080]]” or “[[http://stages:8080|http://stages:8080]]”, why do I have to use manual authentication?// +
-      * Kerberos is a security protocol. For security reasons it is necessary to have a globally unique network identification. Both, localhost and abbreviated host names are not globally unique. For this reason you always have to use the FQDN (full qualified domain name). +
-  * //How to determine the Kerberos Realm?// +
-      * In an Active Directory environment the Kerberos Realm is equal to the Domain name of Windows. +
-      * You can find the Domain name in System Control > System > Network Identification. +
-  * //I get exceptions like “GSSException: No valid credentials provided (Mechanism level: Failed to find any Kerberos Key)”// +
-      * There are various reasons for this exception: Autologin Guide.doc 05.05.2015 23 - 24  +
-      * Check location and file system permissions of the keytab file and the paths to this file inside JAAS configuration file. You have to use forward slashes “/” for path separation. +
-      * The Stages SPN has to be unique inside the Active Directory +
-      * The Stages SPN has to match the domain name of the Stages server +
-      * Check the SPN case. It is case sensitive! The domain part has to be lower case and the realm part has to be upper case +
-      * Check if there is an inner exception with message “Clock skew too great”. You have to enable time synchronization on every computer. Really, on every, including Active Directory Server, Stages Server and Client computers. Usually a tolerance of up to 5 minutes is acceptable. Don’t forget to check time zone settings and en-/disable daylight saving support on every machine in the whole network.+
  
 === Tools and Utiliites === === Tools and Utiliites ===
  
-  * **Windows Tools and Support** +  * [[:72:autologin_windows_tools|Windows Tools and Support]]
-      * The Windows Support Tools are located on every server installation CD, but with some versions of Windows they are not installed by default. Please search for a file named “suptools.msi” and install it. The installer package will depend on another file called “support.cab” inside the same directory. +
-        * //Ktpass.exe// +
-          * Ktpass is a Kerberos utility to create keytab files. Please see chapter 1.3.2 for an example. +
-        * //Setspn.exe// +
-          * With setspn.exe you can list and delete SPN (service principal names) assigned with ktpass.exe. Please see section 1.4.22 of the FAQ for an example on how to use this utility. +
-        * //Ldp.exe// +
-          * Ldp is an LDAP browser useful for evaluating the content of an LDAP directory. +
-        * //Windows Resource Tools – Kerbtray// +
-          * Kerbtray is useful to display ticket information for a given computer running the Kerberos protocol. It can be downloaded from [[http://download.microsoft.com|http://download.microsoft.com]]. Use the search facility and search for the keyword “Kerbtray”.+