Contents Installing

Transcription

1 Installing

2 TOC 2 Contents Installing... 3 Installation Overview... 3 Connecting Through a Proxy Server...4 Connecting to Jive-Hosted Services...5 Managing Client Certificates...6 Installing the Jive Linux Package and Starting Up... 7 Troubleshooting Linux Installations Changing the Root Context (optional) Setting Up a Cache Server (optional)...13 Post-Installation Tasks Installing On a Cluster (optional)...15 Configuring a Cluster Node (optional)...17 Installation Known Issues Adding Features with Plugins Configuring Delegated Authentication LDAP and Active Directory Guide...19 Overview of LDAP Integration Steps Using LDIF to Inventory Your LDAP Configuration...20 Configuring LDAP After Initial Setup...21 Synchronizing LDAP Users LDAP System Properties...22 Single Sign-On Understanding SSO with SAML...25 Getting Ready to Implement SAML SSO...25 Configuring IdPs for SSO SAML Identity Providers Configuring SSO with SAML...27 SAML SSO Attribute Mapping Tips Advanced SAML Integration Settings Troubleshooting SAML SSO IdP-Specific SAML SSO Issues...32 Understanding SSO with Kerberos Configuring SSO with Kerberos Understanding SSO with External Login...34 Configuring SSO with External Login...34 SSO and Mobile... 34

3 Installing 3 Installing This guide includes information on installing the application. Use these instructions as a guide, keeping in mind that they're a template and your requirements will be specific to your community. Some Jive modules (and plugins) you've purchased have their own system and installation requirements. See the separate documentation for each. The distribution you receive includes key required pieces (such as an application server, Java VM, and an evaluation database). Your operating system should have a package manager (such as the RPM manager on Linux) already installed. When installing, you'll invoke that manager to install the package that contains the application. Important: The pre-packaged PostgreSQL DBMS is for evaluation purposes and should not be used for production instances. Installation Overview When you install the Jive platform, you'll perform several steps in a specific sequence. Here is an overview of all the installation steps and the order in which you should perform them: Steps Module Required or Optional Install Instructions 1 -- Required Review the System Architecture drawing and the System Requirements to understand a typical configuration, required components and sizes, and how to scale your system. See the Environmental Requirements for additional information Required Review the information in Connecting to Jive-Hosted Services to ensure your servers can communicate with the externally hosted components. If you use a proxy server, make sure it's configured correctly to access the required external resources. See Connecting Through a Proxy Server. 3 Activity Engine and Database 4 Jive Web App and Database 5 Cache Server(s) Required Required Optional 6 Doc Optional Conversion Module 7 Cluster Nodes Optional Install the Jive Linux package on your Activity Engine node and its database. This node should be able to access the Recommender Service as described in Connecting to Jive-Hosted Services. Install the Jive Linux package on your web app node(s) and its database. Any web app nodes will need access to the domains for Apps Market and Mobile Gateway, directly or through your proxy server, as described in Connecting to Jive-Hosted Services. Install the Jive Linux package on the cache server(s). This is an optional step, but typical for many configurations. See the System Architecture drawing to better understand a typical configuration and how to scale your system. Install the Jive Linux package on the document conversion node. This is an optional module that controls document conversion. For more information, see Setting Up a Document Conversion Node. Configure your cluster. Not all configurations will require a clustered environment, so this is an optional step. For this, you will install the Jive Linux package on each node of the cluster, and configure it appropriately.

4 Installing 4 Steps Module Required or Optional Install Instructions 8 Final Setup Required With a supported web browser, navigate to where hostname is the DNS-resolvable name of the server where you installed the Jive application on your primary web application node. There, you will be prompted to finish configuring the Jive application via the admin console setup wizard. If you plan to populate your community with users synchronized from your LDAP implementation, the setup screens are included in this wizard. Connecting Through a Proxy Server Certain core components and features, including the Recommender, Mobile, and Apps Market services, require Jive to access information from across the firewall. If you use a proxy server to access the Internet, setting up the proxy connection using the Proxy Server settings in the admin console ensures you can connect to Mobile and the Apps Market. You can also set exceptions if you want to connect to certain hosts directly, rather than through the proxy server. Fastpath: Admin Console: System > Settings > Proxy Server See Advanced Proxy Configurations below for some situations that may require additional workarounds. Setting JVM Properties for Recommender Connecting to the Recommender service requires setting JVM properties as well after you complete the Activity Engine installation. To set them: 1. Modify start in /usr/local/jive/services/eae-service/bin/ to add the following java args to the service invocation: -Dhttp.proxyHost=webproxy_address -Dhttp.proxyPort=webproxy_port -Dhttp.proxyUser=webproxy_user - Dhttp.proxyPassword=webproxy_pwd. For example, add: -Dhttp.proxyHost=webproxy.eng.jiveland.com -Dhttp.proxyPort= Dhttp.proxyUser=jive -Dhttp.proxyPassword=jive The proxyuser and proxypassword properties are required. If your proxy server does not require a user name and password, include these options with blank values. 2. If the system is NOT the production instance go to System > Management > System Properties and set the system property jive.eae.instance.type to the value Restart the Activity Engine instance and the application servers. Advanced Proxy Configurations If you have DNS proxying enabled, you also need to set the jive.apps.proxy.whitelist.cidrs system property to include the IP address (single node) or CIDR addresses of your proxy server. Domain names are not supported. You can separate multiple addresses with spaces. If your site uses client certificate validation, you should contact Support for assistance. Reverse proxying can modify data in ways that are not compatible with running Jive. Reverse proxies are often configured to reject GETs with special characters in the query string, strip the bodies from PUT commands, and add prefixes to cookie names. For example, Jive Apps require the colon (:) character to be supported in URLs. If you use IIS-based reverse proxying with.net 4.5 or earlier, colons are blocked by default. In this case, upgrading to.net 5.0 resolves the problem.

5 Installing 5 Preparing to Connect to Jive-Hosted Services To ensure a successful installation, you need to make sure you can connect successfully to several component services that are hosted by Jive. In addition to the core components of Jive that you install on your own servers, running Jive requires connections to the Apps Market service, the Recommender service, and, if you use them, the optional Mobile Gateway and Video services. You'll also need to connect to the licensing server. The following sections provide the ports and addresses you'll use when ensuring your firewall can access the correct ports and domains for these services. They also provide some pointers for successful setup. General Best Practices For all these components, you need to ensure that your proxy server is configured to access resources outside the firewall. See Connecting Through a Proxy Server for more information. Recommender Service Make sure your Activity Engine servers can connect through the firewall using the following Component Port(s) Direction Domain(s) or IPs Jive Genius Recommender Service (Activity Engine) TCP port: 7020 JMX port: 7021 Open in.genius.jivesoftw out.genius.jivesof 443 After installation is complete, you can check the status of each Activity Engine's connection to the Recommender service using the Activity Engine page in the admin console. Navigate to System > Settings > Activity Engine and check the Recommender column of the Activity Engine Overview table. Note that if you relocate an instance by changing the jiveurl, and you then enable and disable the Recommender on that instance, the Recommender restarts with a new ID for the instance. Recommendations from before the jiveurl changed will be lost. Apps Market Service Make sure the following ports and domains are enabled so the web application nodes can contact the Market. Component Port(s) Direction Domain(s) or IPs Jive Apps Market none n/a market.apps.jives gateway.jivesoftw apphosting.jiveso developers.jiveso After you complete your Jive installation, make sure you have enabled the legacy REST services under System > Settings > Web Services > Legacy Web Services and the Core API under System > Settings > Web Services > Core API. Complete instructions for setting up and troubleshooting your connection to the Apps Market service can be found under Setting Up Apps. Note that if you relocate an instance by changing the jiveurl, and you then enable and disable the Apps Market on the instance, the Market restarts with a new ID for the instance. Installed Apps from before the jiveurl changed may be lost or work incorrectly. The correct path is to relocate the instance with the Market enabled, so that the ID remains the same.

6 Installing 6 Mobile Gateway If you plan to have your community members access the community with Jive Mobile, you'll need access to the Jive Mobile Gateway. Make sure the following ports and IPs are enabled so the web application nodes can contact it. Component Port(s) Direction Domain(s) or IPs Mobile (all locations, including EMEA) Mobile (all locations, including EMEA) 443 if you use SSL, 80 if not Inbound to Jive instance out.jivemobile.com ( ) 443 Outbound from Jive instance gateway.jivemobile.com ( and ) Mobile (EMEA only) 443 if you use SSL, 80 if not Inbound to Jive instance Jive Present 443 Inbound to Jive instance , , and Video Service Setting up the firewall for Video is complex. For complete information, see the full Video documentation, especially Setting Up Your Firewall. Licensing You need to be able to connect to the license server through your firewall to keep your instance running. Component Port(s) Direction Domain(s) or IPs Licensing 443 Outbound license.jivesbs.co Managing Client Certificates In the rare case where your corporate network uses client certificates for authentication, you will need to configure Jive so it can authenticate properly. You can use the admin console to choose how to handle client certificates. If you choose a method that allows for storing certificates in Jive, you can also view and manage them in the admin console. Jive interface accepts PKCS12 encrypted keys, just as your browser does. Uploading a new certificate and key takes effect immediately, and all the nodes in a cluster share the same keystore. Fastpath: Admin Console: System > Settings > Client Certificates Certificate Management Strategies Select Java as the client certificate strategy if you're planning to use Java's keytool to manage certificates outside Jive using Java system properties. The Client Certificates dialog then becomes read-only, and you can't upload any certificates. More information about the Java keytool is available at the Oracle website.

7 Installing 7 Select Issuer as the client certificate strategy if you want to select certificates by issuer. You'll need to provide the key and the certificate password when you upload your client certificates to the Jive keystore. Select Domain as the client certificate strategy if you want to specify the certificates to use for a specific domain. You'll need to provide the domain and the certificate password used to access the cert file when you upload your client certificates to the Jive keystore. Testing Certificate Validation If you put a test URL in the box and click Test Connectivity, you'll get a detailed report on client and server connectivity. Installing the Jive Linux Package and Starting Up Jive is compatible with a number of hardware configurations as well as network topologies. To understand the recommended deployment configuration for an on-premise installation, see Jive Enterprise Architecture. What You'll Need To install Jive using the RPM, you'll need the following: A server(s) that meets the minimum specified hardware requirements described in System Requirements. A host computer running Linux. See the System Requirements for supported versions. SSH access to the host computer so you can copy the RPM there for installation. Root access (not just sudo) to the host where the installation is performed, commonly via SSH, or less commonly through user interface access such as VNC. A bash shell to run the install commands. Install the Package on All Nodes You will need to install the Jive Linux package on the following nodes: Activity Engine node web application node(s) cache server(s) (if you're using one or more) Document Conversion node (if you've purchased this additional module) Note: Document Conversion, which generates previews of Microsoft Office documents and PDFs, requires a separate machine. For more information, see Setting Up a Document Conversion Server. Caution: You should not create a jive user or a jive group (locally or in a remote authentication system) before installing because they are created for you automatically during install. If you manually create a jive user or a jive group, serious problems may occur when you administer or configure your instance later. Note that the jive user and jive group are both required for installation and normal operation and cannot be changed. Installation Steps The following installation steps are the most common approach to installing the Jive platform: 1. Ensure that the web application and Activity Engine databases have been created as described in Database Prerequisites, and you have created users on them. 2. From the command line, access the target host as root. For example, the following illustrates using the ssh command to access the server at targethost as the root user. joe@joesbox ~ $ ssh root@targethost root@targethost's password: Last login: Mon Feb 14 14:00: from joesbox.example.com

8 Installing 8 3. Copy the Jive application RPM package to the target host. Here's an example using the Linux scp command to copy the package from a computer named "joesbox" to a target host at "targethost": scp -v joe@joesbox:/users/joe/jive_sbs x86_64.rpm root@targethost:/root 4. Set open file limits for the Linux system(s) on which you're installing Jive. To set how many file handles the jive user can have open at a time, add the following lines to the appropriate configuration file. File Lines to add /etc/security/limits.conf jive soft nofile 8192 jive hard nofile /etc/pam.d/login session required /lib64/security/ pam_limits.so 5. Set options for the installation. Note: We strongly recommend setting JIVE_APPLICATION_NOSERVICE before you install the package on the Activity Engine, Document Conversion, cache nodes, and one of the web application nodes if you're using more than one. Doing so prevents the package from starting the services on each of the nodes immediately after you install the RPM package on them. To set these, use the Linux export command, which sets them as environment variables. All package-level variables are enabled by setting their value to a non-empty string. For example, the following command turns on debugging information: export JIVE_DEBUG=1 You can clear the variable with a command such as: unset JIVE_DEBUG Option Description Default JIVE_DEBUG Exposes installation debugging information, listing actions the installer is performing. This is in addition to the information displayed by the rpm -v (verbose) flag. JIVE_APPLICATION_NOSERVICE Prevents the package from starting the web application services immediately after installation. Note: We strongly recommend setting this option before you install the package on the Activity Engine, Document Conversion, cache nodes, and one of the web application nodes if you're using more than one. Debugging information isn't displayed. By default, the application starts immediately after installation; so you only want one instance running after installation--the one on your primary web application node. You'll be able to navigate to that node in a web browser after installing and starting up so that you can continue with the application setup wizard. All other nodes should be stopped during that time. 6. Install the Jive application RPM using an rpm command such as the following. The i, h, and v options are provided to indicate install with hash indicators, and to be verbose during the installation. (Your copy of the Jive RPM file -- here, jive_sbs x86_64.rpm -- might have a slightly different name.) rpm -ihv jive_sbs x86_64.rpm Note: You can find out more about rpm command syntax at the Fedora web site.

9 Installing 9 The following truncated example shows the output for a successful installation using the preceding command. In this case, the Jive RPM package was in the /root directory of the target host. [root@targethost ~]# rpm -ihv jive_sbs x86_64.rpm Preparing... ########################################### [100%] Preparing clean installation. Pre-install tasks complete. 1:jive_sbs ########################################### [100%] Writing installation version.... sbs started successfully. All applications started successfully (1 total). Starting jive-httpd: Jive post-install configuration complete. When it's finished, the installation program indicates that the post-install configuration is complete. 7. If you'll be using a database whose driver is not included, ensure its driver is in the application's classpath by following the steps in Database Prerequisites. 8. You're finished installing. After you have installed the Jive package on all of your nodes, you'll start the services as described in the following section. Starting the Services 1. Start the services on all of the nodes from root. On this node Activity Engine Web app nodes 1 and 2* Cache server(s)* and cluster nodes* Document Conversion* *Optional nodes Run this command as root service jive-eae-service start service jive-application start service jive-httpd start service jive-cache start service jive-docconverter start Caution: If you did not enable JIVE_APPLICATION_NOSERVICE on the Activity Engine, Document Conversion, and cache nodes as we strongly recommend, the Jive service will start automatically on the web application nodes. 2. On the Activity Engine, Document Conversion, and cache server(s), run a chkconfig to permanently enable the service that you're running on each machine. This will ensure each node's service starts by default on a reboot. Note that on the web app node(s), run the chkconfig only if you have enabled JIVE_APPLICATION_NOSERVICE. On this node Activity Engine Document Conversion Cache server(s) and cluster nodes Web app nodes 1 and 2 Run this command as root chkconfig jive-eae-service on chkconfig jive-docconverter on chkconfig jive-cache on chkconfig jive-application on chkconfig jive-httpd on

10 Installing Now you'll need to stop the services on all of the nodes except for the Activity Engine and your primary web application node, which you will use to walk through the admin console setup wizard in a web browser (in the next step). On the Document Conversion, cache nodes, and one of the web application nodes, run the following stop command: On this node Document Conversion Cache server(s) and cluster nodes Web app node 2 Run this command as root service jive-docconverter stop service jive-cache stop service jive-httpd stop service jive-application stop 4. With a supported web browser, navigate to where hostname is the DNS-resolvable name of the server where you installed the Jive application on your primary web application node. There, you will be prompted to finish configuring the Jive application via the admin console setup wizard. If you plan to populate your community with users synchronized from your LDAP implementation, the setup screens are included in this wizard. 5. When you're finished with the setup wizard, you'll need to start the services, plus restart the primary web app node, as follows and in this order: On this node Document Conversion Cache server(s) and cluster nodes Web app node 2 Web app node 1 6. See Post-Installation Tasks for your next steps. Run this command as root service jive-docconverter start service jive-cache start service jive-httpd start service jive-application start service jive-httpd restart service jive-application restart Troubleshooting Linux Installations The Jive installation uses Linux RPM, a widely tested and used application that is very unlikely to fail. However, if you run into trouble during an installation, you can delete and start over as described here. Note: You'll find the installation log files on the target computer at /usr/local/jive/var/logs. Unsatisfied Dependencies The Jive application RPM depends on the presence of several low-level system packages that are common to nearly all configurations of Jive s supported Linux distributions. Also, the Jive application RPM depends on three highlevel packages. If any of these packages (system or high-level) is not present, the RPM subsystem will warn you, then refuse to install. When you see these warnings, simply install the missing packages using RPM, then install Jive as described in the instructions. Unsatisfied dependencies appear as an error when attempting to install the Jive application: [root@targethost ~]# ls -l total rw-r--r-- 1 root root Jan 20 16:03 jive_sbs i386.rpm -rwxr-xr-x 1 root root 1347 Oct 7 16:14 updatedns.sh [root@targethost ~]# rpm -ivh jive_sbs i386.rpm error: Failed dependencies: bash >= 3.2 is needed by jive_sbs i386

11 Installing 11 sysstat >= 7 is needed by jive_sbs i386 Depending on the host configuration, it may be possible to install the dependencies directly using system tools. For example, in RedHat Enterprise Linux, the yum command can install dependencies via network repositories. The following demonstrates how to install the dependencies shown in the error above. [root@targethost ~]# yum install bash-3.2 sysstat Loading "installonlyn" plugin Setting up Install Process Setting up repositories extras 100% ========================= 1.1 kb 00:00 updates 951 B 00:00 base 100% ========================= 1.1 kb 00:00 addons 100% ========================= 951 B 00:00 Reading repository metadata in from local files primary.xml.gz 100% ========================= 90 kb 00:00 ################################################## 295/295 primary.xml.gz 369 kb 00:03 ################################################## 796/796 primary.xml.gz 100% ========================= 853 kb 00:01 ################################################## 2458/2458 Parsing package install arguments Resolving Dependencies --> Populating transaction set with selected packages. Please wait. ---> Downloading header for sysstat to pack into transaction set. sysstat el5.i % ========================= 15 kb 00:00 ---> Package sysstat.i386 0: el5 set to be updated ---> Downloading header for bash to pack into transaction set. bash el5.i386.rpm 100% ========================= 55 kb 00:00 ---> Package bash.i386 0: el5 set to be updated --> Running transaction check Dependencies Resolved ============================================================================= Package Arch Version Repository Size ============================================================================= Installing: sysstat i el5 base 168 k Updating: bash i el5 base 1.9 M Transaction Summary ============================================================================= Install 1 Package(s) Update 1 Package(s) Remove 0 Package(s) Total download size: 2.0 M Is this ok [y/n]: y Downloading Packages: (1/2): sysstat el 100% ========================= 168 kb 00:00 (2/2): bash el5.i3 100% ========================= 1.9 MB 00:02 Running Transaction Test Finished Transaction Test Transaction Test Succeeded Running Transaction Updating : bash ######################### [1/3] Installing: sysstat ######################### [2/3] Cleanup : bash ######################### [3/3] Installed: sysstat.i386 0: el5 Updated: bash.i386 0: el5 Complete!

12 Installing 12 After dependencies have been resolved, the package should install normally. Insufficient System Memory The Jive platform requires a minimum of 3GB of RAM to operate effectively for an enterprise environment. If sufficient memory is not available on the target installation system, the installer will provide a warning at installation time similar to the example below. [root@targethost ~]# rpm -ivh jive_sbs i386.rpm Preparing... ########################################### [100%] 1:jive_sbs ########################################### [100%] Writing installation version. Wrote installation version. Executing Jive post-install configuration. Creating jive group jive. Creating jive system user jive. useradd: warning: the home directory already exists. Not copying any file from skel directory into it. Marking all upgrades as complete. WARNING: this host does not have sufficient RAM to run a production Jive system. A minimum of 3GB is required to host the application and HTTPD servers. 4GB is required to run a locally hosted database. Starting Jive System Daemon. Performing Jive system configurations. Disabling CPU frequency stepping.... Jive post-install configuration complete. In the above example, note the message WARNING: this host does not have sufficient RAM to run a production system. A minimum of 3GB is required to host the application and HTTPD servers. 4GB is required to run a locally hosted database. Despite this warning, the package does install correctly; however, further errors are noted on the output line: "Failed to start application sbs. See log file at '/usr/local/jive/var/logs/sbs.out'." The contents of this log file indicate: [root@targethost ~]# cat /usr/local/jive/var/logs/sbs.out SCRIPT_DIR=/usr/local/jive/applications/sbs/bin JIVE_BASE=/usr/local/jive/applications/sbs Creating temp directory at /usr/local/jive/var/work/sbs. Starting application sbs Error occurred during initialization of VM Could not reserve enough space for object heap Starting Over In the unlikely event that something goes wrong during installation and you want to start over, you can uninstall. When uninstalling, you don't specify the RPM filename, as you did when installing. Instead, provide the logical name by which the RPM now knows the application: jive_sbs. Here's an example using rpm -e for uninstalling: rpm -e jive_sbs

13 Installing 13 If you want to be sure you've removed all remnants of the installation, delete the destination directory created by the RPM with: rm -rf /usr/local/jive Changing the Root Context (optional) By default, Jive installs and configures using the root context, for example This is the recommended configuration and default installation behavior, but non-root contexts such as yourcommunity.com/community are also supported. To use a non-root context, you need to set an environmental variable that changes default installation behavior. The RPM has several flags you can set before installation to dictate default behavior. By default, on fresh installs the RPM runs: appadd --verbose sbs This command gives you the basic application setup with Apache files responding on port 80 of the root context and pointing to your Tomcat installation on the default ports. It also copies /usr/local/jive/application/ template to /usr/local/jive/application/sbs. However, you can set the following environmental variable to change this behavior before installing: export JIVE_NO_DEFAULT_APP=1 Or, if you forgot to set the environmental variable and want to change the default settings you can issue: apprm sbs appadd --context-path=community community apprm removes the existing installation of Jive while retaining the database. appadd creates the new application instance. In this case, the context path would be the text to appear after the root URL ( community) and the argument community would be the name of the directory created in /usr/local/jive/ applications/. Note that appadd has several flags that control the configuration files. For example: appadd --auto-port --context-path=sbs1 sbs1 appadd --auto-port --context-path=sbs2 sbs2 auto-port is aware of existing installations and will stagger the ports to allow multiple instances on a single server. This is useful for testing Jive, but note that single-server deployments are not recommended or supported for production. For more about appadd see the appadd command reference. Setting Up a Cache Server (optional) This topic describes how to install a separate cache server for use by application server nodes in a cluster. To install the cache server, you use the same Linux package that you use to install an application server. If your installation uses a single application node, the installation will not enable the cache services; instead, the installation will use the local cache installed with the application server. When you have a multi-node configuration, use the following steps to set up cache services in the cluster.

14 Installing 14 Note: If you're upgrading from a version earlier than version 4.5.0, keep in mind that the caching technology was completely revised as of For information about the differences, see Clustering and In-Memory Caching: Rationale and Design for Changing Models. To install a cache server: 1. Install the application as described in the (installation documentation). 2. Because the cache server machine's only function will be operating as a cache server, shut down the services you won't need on a cache server: On Linux /etc/init.d/jive-httpd stop /etc/init.d/jive-httpd deactivate /etc/init.d/jive-application stop /etc/init.d/jive-application deactivate /etc/init.d/jive-database stop /etc/init.d/jive-database deactivate 3. Configure the cache server with its address. You can either edit /etc/jive/conf/cache.conf and add the CACHE_ADDRESSES line or export the variable. Caution: If you're setting up more than one cache server machine, you must use three or more. The CACHE_ADDRESSES value should list them in a comma-separated list. Using only two cache servers is not supported and can cause data loss. 4. Register and start the caching service with a command as shown below: On Linux /etc/init.d/jive-cache activate /etc/init.d/jive-cache start As the cache service starts it will: Write the CACHE_ADDRESSES value to the cache configuration file located in /etc/jive/conf/cache.conf. Run the cache configuration script located in $JIVE_HOME/sbin/configure-cache. Generate cluster.xml. Generate server.properties. Generate stores.xml. Start the cache service. The cache service writes several log files to $JIVE_HOME/var/logs/. These are: cache.log -- Output from the cache processes, showing start flags, restarts, and general errors. cache-gc.log -- Output from garbage collection of the cache process. cache-service.log -- Output from the cache service watchdog daemon, which restarts the cache service as needed and logs interruptions in service. 5. If you haven't already, set up your application cluster to use the cache server address you specified here. Post-Installation Tasks This section is intended to provide sample configurations and script examples common to long-term operation of a Jive installation. As opposed to the Run Book (Linux), these operations are common to a new installation, but generally not for day-to-day operation of this platform.

15 Installing 15 Using Commands to Work with Your Managed Instance Jive includes several command-line tools you can use to perform maintenance tasks with your managed instance. With these tools, you can start and stop the application, upgrade the application, collect information needed by Jive support, and more. You'll find these documented in the Application Management Command Reference. Enabling SSL Encryption The Jive platform is capable of encrypting HTTP requests via SSL or TLS. Enabling encryption of HTTP traffic requires several steps on a platform-managed host. For more about this, see Enabling SSL Encryption. Disabling the Local Jive System Database Many deployments will not wish to use the locally managed Jive platform database, choosing instead to use an RDBMS that is controlled by an internal IT group. In this case, the local database should be disabled. For information on disabling the application database, see the Operations Cookbook Note that disabling the database does not stop the service if it is running. Likewise, re-enabling the database does not start the database service. Setting Up a Document Conversion Node If you have purchased the Document Conversion module, see Setting Up a Document Conversion Node Some documents -- including PDFs and those from Microsoft Office -- are supported in a preview view in Jive. If you want to convert content from its native format into a form that can be previewed without altering the original document, you'll need the Document Conversion module, which you'll need to deploy on a server that is separate from your core Jive production instances. Installing On a Cluster (optional) Before You Begin Before you set up the nodes in a cluster, you should have already configured a cache server, as described in Setting Up a Cache Server. The cluster will require the presence of a cache server to cache data that should be available to all nodes in the cluster. If your cache server isn't configured and running, you won't be able to set up the cluster. Topology Note: Your license determines whether or not clustering is enabled and how many nodes are supported. To check on the number of clustered servers your license allows, see the license information after logging into the admin console. The nodes in a cluster need to be installed on the same subnet, and preferably on the same switch. You cannot install nodes in a cluster across a WAN. Upgrading IMPORTANT If you're upgrading and copying the home directory (such as /usr/local/jive/ applications/<instance_name>/home) from the older installation, you must preserve the node.id file and the crypto directory from the home directory before starting the server. The value stored in this file must be unique among the cluster nodes; that is, each node in a cluster will have a unique value in the node.id file. You must preserve the node.id file because it plays a role in storing encrypted information in the cluster; if that file is lost, you will lose access to the encrypted information. If you are deploying a new cluster, it is permissible to copy the contents of the home directory from the first node (where you set up clustering) to subsequent nodes -- with the exception of the node.id file. Do not copy the

16 Installing 16 node.id file to subsequent nodes. If the node.id file does not exist, the application will generate a new file on startup. The cache server must be cleared and restarted before the upgraded application server nodes are started and try to talk to the cache. If you're upgrading a plugin, clear the cache for that plugin and shut down the cache server first. Starting a New Cluster Always wait for the first node in the cluster to be up and running with clustering enabled before you start other cluster nodes. Waiting a minute or more between starting each node ensures the nodes are not in competition. As the senior member, the first node you start has a unique role in the cluster. See the clustering overview for more information. Clocks The clocks on all machines must be synchronized for caching to work correctly. For more information, take a look at Managing Cache Servers. Also, if you're running in a virtualized environment, you must have VMware tools installed in order to counteract clock drift. If you're running in a virtualized environment, you must have VMware tools installed in order to counteract clock drift. Cluster Node Communication Do not put a firewall between your cache servers and your Jive application servers. If you do so, caching will not work. A firewall is unnecessary because your application servers will not be sending untrusted communications to the cache servers, or vice versa. There should be nothing that might slow down communication between the application servers and the cache servers. All ports between the cache and web application servers must be open. Port 6650 should be blocked to external access (but not between the cluster nodes!) so that any access outside of the datacenter is disallowed. This is to prevent operations allowed by JMX from being executed on the cache server. Overview of a Cluster Installation 1. Be sure to read the System Requirements for important information about software, hardware, and network requirements and recommendations. 2. Provision a database server. Be sure to read the Database Prerequisites. 3. If you're going to use a separate server for binary storage, Configure a Binary Storage Provider. 4. If your community will use the document conversion feature, see Setting Up a Document Conversion. 5. Install a cache server on a separate server. 6. Install and configure the application on the first node in your cluster. 7. Install and configure the application on the subsequent nodes in your cluster. Installing on a Cluster Important: If, as part of your new installation, you're setting up one node as a template, then copying the home directory (such as /usr/local/jive/applications/<instance_name>/home) to other nodes in the cluster, you must remove the node.id file and the crypto directory from the home directory before starting the server. The application will correctly populate them. 1. Use the Jive application package to set up a cache server on a separate machine. See Setting Up a Cache Server for more information. Note the cache server address for use in setting up the application servers. 2. Before proceeding, make sure the cache server you set up is running. It must be running while you set up the application server nodes. 3. On each node in the cluster, install the application using the package (RPM on Linux), but don't run the admin console's setup wizard. See the Linux installation instructions for more information on installing the application.

17 Installing Start the primary node and navigate to its instance with a web browser. In the setup screen provided, enter the address of the cache server you installed, then complete the admin console setup wizard. 5. After you've finished with the setup wizard, restart the node. 6. Copy the jive.license file, the jive_startup.xml file, and the search folder from the home directory on the primary node to each of the other nodes in the cluster. The home directory is typically found in /usr/ local/jive/applications/your_instance_name. 7. On each of the secondary nodes, remove the node.id file and the crypto directory from the home directory. (The application will correctly populate these on each node when they are started for the first time.) 8. Start the application on each of the secondary nodes (service jive-application start followed by service jive-httpd start). Because they are connecting to the same database used by the primary server, each secondary node will detect that clustering is enabled and will pick up the configuration you set on the primary node. 9. Restart all the servers in the cluster to ensure that the address of each node in the cluster is known to all the other nodes. Configuring a Cluster Node (optional) You can get information about any node in the cluster and make configuration changes to it from the admin console. You can also enable or disable clustering from a node in the cluster and set the node's cluster address (which is unnecessary unless you want to ensure that the node has a particular TCP endpoint--ip address and port number). By design, a node that is new to a cluster creates its own address and registers itself in the database as a member of the cluster. Be sure to read the clustering overview for information about how the clustering system works. Fastpath: Admin Console: System > Settings > Cluster Use the following settings on the admin console's Cluster page to get information and configure the cluster: Setting Enable cluster Cluster members Local Cluster Address Cluster Overview Description Click Enabled to enable this node for the cluster. Lists the addresses of other nodes in this cluster. Select the Remove check box to have this node's address removed from the database. Displays this node's IP address and the port on which this node listens for others in the cluster. The IP address and port form the unique TCP endpoint for this node in the cluster. Lists the nodes in this cluster, indicating which is the senior member. Installation Known Issues Poor Performance When Citrix Is Used Jive does not work properly when accessed through Citrix. This is because Citrix doesn't support AJAX, a technology Jive uses for accessing the server asynchronously in the background. Adding Features with Plugins By purchasing optional plugins offered by Jive Software, you can enhance Jive with powerful features not included by default. You can learn more about supported plugins at the Jive website.

18 Installing 18 Configuring Delegated Authentication In delegated authentication, Jive delegates authentication to your user identity provider. Note: For information on building delegated authentication support for your user identity provider, see Jive Delegated Authentication in the Jive Community. Fastpath: Admin Console: People > Settings > Delegated Authentication Settings Use the following high-level steps to understand the configuration process. The sections below provide more information on the settings themselves. 1. Select the Enable Delegated Authentication check box to reveal other configuration options. 2. Under Services, select the services for which you want authentication delegated. 3. Under Options, select optional features to go along with authentication. 4. Under Service Location, enter the URL at which your authentication web service can be found. 5. Test communication from the application to your web service. a. Enter a username and password that will provide access to the web service. b. Enter the IP address for this community. c. Click Perform Test. Services This section lists services provided by the application, and which can require authentication for access. In other words, each of these represents a point of access for users. Select the services whose authentication requests should be delegated to the authentication provider you're describing in configuration here. Web interface -- The application's browser-based user interface. This is what your users will likely use most often. Mobile integration -- Access via a mobile device, such as the iphone. Note that this option has been deprecated as of Jive 5.0. To enable delegated authentication for the Mobile plugin, select the Web interface option. Web services -- Access via SOAP- or REST-based web services. RSS feeds -- Access via RSS/Atom calls, such as from a feed aggregator. Options These are optional actions you can have the delegated authentication feature perform. Auto-create users -- Select this to have the application create internal user accounts for users it authenticates with your identity provider, but who aren't represented in the application's database yet. Synchronize profile fields -- Select this to synchronize user profiles between the application's profile data and profile data stored by your identity provider. Service Location The service address is the location at which to find your authentication web service. Username -- A username known to the user identity provider. Password -- The password for the username provided. Source IP -- An optional field if your authentication web service will evaluate the IP address of the incoming request. For example, you might use this if you anticipate allowing access from only one IP address and you want to test that functionality here.

19 Installing 19 LDAP and Active Directory Guide If your enterprise already uses LDAP or Active Directory repository to manage users, you can configure your Jive community to integrate with it. By default, the application doesn't use LDAP. Instead, it stores all user data in a database and performs authentication with that data. When you integrate with LDAP, Jive will authenticate against your LDAP server. During setup, you specify which users and groups from LDAP you want the application to use. The instructions for LDAP integration assume that you are or have access to an LDAP administrator and that you're familiar with the Jive Admin Console. If you don't have this expertise, you may want to contract with Jive Professional Services or another outside resource with LDAP knowledge. Note: If you're using Active Directory, make sure it allows LDAP querying. You might also be interested in reading LDAP Querying Basics at the Microsoft web site, or LDAP Attributes at the Computer Performance web site. LDAP Security The Jive application database never caches or stores user credentials. However, if the LDAP system property ldap.ldapdebugenabled is on (true), LDAP traffic can be logged, and user passwords can be printed in plain text to the application's sbs.out log file if connections to LDAP are unecrypted, i.e., non-ssl. It is your responsibility to ensure that your LDAP communication runs over an SSL connection. Overview of LDAP Integration Steps To set up LDAP integration, you need to gather information about your LDAP implementation, identify the location of your key LDAP server and tree, map your users and (optionally) groups so Jive can synchronize to them, and then test your implementation to ensure it is successful. LDAP integration relies on preparation and testing to be successful. If you use this list of overview steps to plan your integration, and if you run a test implementation to ensure that you have correctly identified the users, groups, and fields you want to sync with your Jive instance, you can avoid some frustrating missteps associated with integrating these two complicated products. 1. Gather information about your LDAP installation. To complete the integration setup, you will need: The address of your LDAP server and how it will communicate with Jive. If you're using Jive to host your community, you can contact Support for assistance with setting up the connection between these servers. Make sure you account for server referrals, especially if you use Active Directory. The Base DN associated with the users you want to sync with Jive. You may or may not want to include all the users in your organization, so make sure your Base DN is associated with the part of the tree that includes the users you are targeting. Keep in mind that if you plan to map groups as well as users, your BaseDN needs to be at a tree level that contains both users and groups. You can also narrow down your users by specifying a User DN relative to the Base DN during setup. The DN associated with an Administrator account that has full access to your LDAP server. (This account does not need to be linked to a Jive user.) The field identifiers in LDAP associated with any fields you want to sync to Jive profile fields. For example, the Username field is typically associated with the samaccountname field for Active Directory. A good method for obtaining this information for your LDAP setup is to export an LDIF file. Any LDAP filter expressions you need to limit the number of users returned when you sync Jive to your LDAP tree. If you don't filter, synchronizing to your LDAP instance will return every user associated with the Base DN you supplied, and your Jive community may be populated with users who don't need to be there. The LDAP Explorer website is a helpful resource for information about LDAP filters. For filter information focused on Active Directory, see LDAP Query Basics on the Microsoft website. The field identifiers for any LDAP groups you want to map to permissions groups in Jive. You don't need to map any groups if you want to manage permissions entirely in the Jive community. You will also need to specify an attribute such as member or memberof that can be used to associate users and groups. 2. Start the LDAP integration setup. (If you aren't configuring LDAP as part of your initial Jive setup, see Configuring LDAP After Initial Setup for instructions on returning to setup mode. If your installation is hosted by

20 Installing 20 Jive Software, you'll need to contact Support for help with this step.) If you select Directory Server (LDAP) in your User Settings during Jive setup, LDAP setup continues for the next three screens. Each screen has field-level Help that you can access by clicking the? next to a field. 3. Supply your connection settings and test the connection by clicking Test Settings. If you can't connect, you may need to check your credentials. The account you're binding with must have read access to users and groups for the entire subtree rooted at the base DN. 4. In the User Mapping screen, map any Jive profile settings you want to populate from LDAP by supplying an LDAP string. If you click LDAP Managed next to a field, that field will be updated from LDAP whenever a sync takes place, typically when the user logs in. Click Advanced Settings to add any user filters you want to use to narrow down the number of users you will sync. 5. Click Test Settings to validate your mappings. Fields that turn red do not currently have a corresponding field in LDAP. If this is expected and you plan to add those fields later, make sure you click LDAP Managed so those fields can be synced after you add them in LDAP. 6. Before you click Continue, enable Synchronize User's Profile on Login. This setting ensures each Jive user's credentials are synchronized as soon as she logs in. (You can use People > Settings > User Data Synchronization Settings after setup to set a nightly synchronization task or to perform a one-time manual sync, but keep in mind that synchronizing all users at once can cause slower performance during peak usage.) 7. In the Group Mapping screen, decide whether to use and synchronize the permissions groups you have set up in LDAP or whether you will use Jive to assign users to permissions groups. Note that group permissions have nothing to do with social groups in Jive. 8. On the Admin Account page, specify whether you want the default user to be defined as an LDAP admin account. Choosing this option disables the default Jive admin account. Keep in mind that if you choose an LDAP admin account, you may not be able to access the Jive community if your LDAP connection is unavailable or misconfigured. Using LDIF to Inventory Your LDAP Configuration Exporting an LDIF file from LDAP can help you extract key information about your LDAP settings that's useful in setting up your Jive integration. The information you'll use to set up your user and group mappings during LDAP integration setup can be exported easily into a format called LDIF (LDAP Data Interchange Format). You can use this information yourself or provide it to a Jive Support engineer. Any LDAP directory browser provides the ability to export to and import from an LDIF file. If you're using Active Directory, you can use the ldifde command line tool. Another excellent tool is JXplorer, which helps you to validate your LDAP mappings and provides an easy-to-use LDIF export. Here's an example of the ldifde command which will yield an LDIF output like above: The following example shows an LDIF output generated by executing ldifde -f output.txt -d ou=jive_users,dc=support,dc=jive,dc=com: dn: CN=Cyr \, Karl,OU=Jive_Users,DC=support,DC=jive,DC=com changetype: add objectclass: top objectclass: person objectclass: organizationalperson objectclass: user cn: Cyr, Karl sn: Cyr physicaldeliveryofficename: Awesome givenname: Karl initials: KC distinguishedname: CN=Cyr \, Karl,OU=Jive_Users,DC=support,DC=jive,DC=com instancetype: 4 whencreated: Z whenchanged: Z displayname: Cyr, Karl

21 Installing 21 usncreated: memberof: CN=FilterGroup,OU=Jive_Users,DC=support,DC=jive,DC=com usnchanged: department: Awesome name: Cyr, Karl objectguid:: 2tnXRo7VxE6zc72YqLtOTw== useraccountcontrol: badpwdcount: 1 codepage: 0 countrycode: 0 badpasswordtime: lastlogoff: 0 lastlogon: pwdlastset: primarygroupid: 513 objectsid:: AQUAAAAAAAUVAAAAF8sUcR3r8QcekDXQw9wAAA== accountexpires: logoncount: 0 samaccountname: karl samaccounttype: userprincipalname: [email protected] objectcategory: CN=Person,CN=Schema,CN=Configuration,DC=support,DC=jive,DC=com dscorepropagationdata: Z dscorepropagationdata: Z dscorepropagationdata: Z dscorepropagationdata: Z mail: [email protected] Configuring LDAP After Initial Setup To configure your LDAP integration after initial setup, you can modify system properties or rerun the setup tool. You can also change your user synchronization settings. If you want to change your LDAP settings after initial configuration, you can use the Admin Console to modify the LDAP-related system properties. Alternately, use the following steps to rerun the setup tool if you have an on-premise installation. If your installation is hosted by Jive, you can contact Support instead. 1. Stop the jive-application service from the command prompt: /etc/init.d/jive-application stop 2. Edit /usr/local/jive/applications/sbs/home/jive_startup.xml so that the <setup> element has the value "false" (meaning "setup has not been run"). 3. Start (or restart) the jive-application service from the command prompt: /etc/init.d/jive-application start (if you are restarting, use jive-application restart). 4. Point your browser at Jive using the URL above and rerun the setup tool. Synchronizing LDAP Users You can manually synchronize users or synchronize them during a nightly batch job, but make sure you allow for performance and take care to use the correct rules. Typically, a user's profile is synchronized to LDAP each time the user logs in to the community. This occurs if you selected Synchronize User's Profile on Login during setup. However, you may occasionally want to synchronize users manually. This should occur when: You have added a number of new users in LDAP who have never logged into the community You want to mass-disable community users from LDAP. You can also run synchronization nightly to catch up with any changes during the day. Note that if you set LDAP rules that exclude some of the users who are enabled in Jive and then do a mass synchronization (nightly or manually), the excluded users will have their Jive accounts disabled.

22 Installing 22 To manually synchronize LDAP: 1. In the Admin Console, click People > Settings > User Data Synchronization Settings 2. Make sure your synchronization settings are the way you want them and that you are currently managing some profile fields through LDAP. If you aren't managing any fields, synchronization won't pick up any LDAP changes such as new users. 3. Click Run Synchronization Task Now.. LDAP System Properties You can modify LDAP system properties to reset some elements of your LDAP configuration without running the setup tool. If you want to make small changes to your LDAP configuration, you can use the following system properties to modify it: make the changes and then restart your instance. For larger-scale changes, you may want to rerun the setup tool. For more information, see Configuring LDAP After Initial Setup. Table 1: Property Meaning Sample Value(s) ldap.servertype.id* The type of LDAP instance 2=AD, 3=openLDAP, 4=other ldap.host* The hostname of IP address of the LDAP server ldap.jive.com ldap.port* The port number of the LDAP server 389 (default) or 636 (SSL) ldap.usernamefield* ldap.basedn* The LDAP field name used to look up username values The Distinguished Name of the base of your LDAP tree uid DC=support,DC=jive,DC=com ldap.namefield^ The element key for the name attribute cn ldap.firstnamefield^ The element key for the First Name attribute givenname ldap.lastnamefield^ The element key for the Surname attribute sn ldap. field* The element key for the attribute mail ldap.connectionpoolenabled Specifies whether to enable connection pooling. See javase/jndi/tutorial/ldap/connect/config.html true ldap.followreferrals ldap.admindn* Specifies whether LDAP queries will follow referrals. This property should always be set to true for Active Directory. The DN for the LDAP admin user. This user does not need to be a Jive user. true CN=AdminMan,OU=Domain Users,DC=support,DC=jive,DC=com ldap.adminpassword* The encrypted password for the LDAP admin a54313f2d3bc98fb c7 ldap.adminpassword.key* The key used to encrypt the admin password. ldap.adminpassword.encrypted* Specifies whether or not the Admin password is encrypted. This property should always be set to true. ldap.ldapdebugenabledspecifies whether LDAP debug logging is on. true false

23 Installing 23 Property Meaning Sample Value(s) ldap.sslenabled ldap.initialcontextfactory ldap.searchfilter Caution: If ldap.ldapdebugenabled is on (true), LDAP traffic can be logged, and user passwords can be printed in plain text to the application's sbs.out log file if connections to LDAP are unecrypted, i.e., non-ssl. It is your responsibility to ensure that your LDAP communication runs over an SSL connection. Note: LDAP logging is extremely verbose and should never be used in production unless Support recommends it. Using debug mode can cause serious performance problems or system failure. Specifies whether to use an SSL connection to communicate with the LDAP server. The filter applied to a remote directory when searching for users ldap.groupnamefield The field that maps a group to its CN in LDAP. ldap.groupmemberfieldthe field that maps a group to its members. ldap.groupdescriptionfield The field that maps a description of a group. ldap.posixmode ldap.posixenabled Specifies whether to connect to LDAP in POSIX mode. POSIX groups store their member associations by common name (CN) rather than full distinguished name (DN). Specifies whether to connect to LDAP in POSIX mode. POSIX groups store their member associations by common name (CN) rather than full distinguished name (DN). ldap.groupsearchfilter^the filter applied to a remote directory when searching for groups. ldap.managerfield Maps the DN of a user's manager. Used when syncing relationship fields. false cn member description false false (objectclass=group) manager ldap.photofield Maps a photo to a user's profile. photo ldap.lastupdatedfield Used to check if an LDAP record has been updated since the most recent sync. ldap.usergroupmember^the field that maps a user to a group. This is a user attribute. ldap.userdn^ jive.sync.user.ldap A RDN (relative to the basedn) which contains users to sync to SBS. Specifies whether user synchronizations are enabled. creationdate memberof ou=people true

24 Installing 24 Property Meaning Sample Value(s) jive.sync.relationships.ldap Specifies whether user relationships are synchronized from LDAP. jive.sync.profile.ldap.photo Specifies whether profile photos are synchronized from LDAP. jive.sync.profile.ldap.login Specifies whether profiles are synchronized at login. jive.sync.auto.disable Specifies whether Jive should disable user accounts which cannot be found in the LDAP directory. jive.sync.auto.disable.att.name The name of the attribute which indicates whether or not an account is disabled in LDAP. false false false useraccountcontrol jive.sync.auto.disable.att.value In Active Directory, use Microsoft 514 (see link) article as a reference for setting user account properties. You can also set up a bit-specific filter such as: useraccountcontrol: :=2 jive.usernames.case.insensitive Setting to false makes case sensitive comparisons when users register or log in, for example, bbrag is a different user than BBragg. When set to true, there is no disctinction between bbragg and BBragg. You may need to set this property to false when existing usernames in your Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or single sign on (SSO) are case sensitive. GroupManager.className Controls whether or not permission groups are synchronized from LDAP. true com.jivesoftware.base.ldap.ldapgroupmanager (for LDAP groups) com.jivesoftware.base.database.dbgroupmanager (default group manager) Single Sign-On Single Sign-On allows you to integrate Jive authentication with an external identity provider. You can use Jive's local database storage to authenticate users out of the box. However, you may find it useful to integrate your external identity provider with Jive so you can centralize identity management and provide your users with a consistent login experience. Many Jive communities implement SSO as part of a larger profile synchronization effort that includes LDAP and/or SAML. Getting Set Up If you already have a Jive community with more than a few users set up, you need to plan a migration strategy before you implement SSO, particularly if you will use SAML or Kerberos. If you implement SSO without migrating users first, you will orphan your existing users--information they contributed to the community will still exist, but they will be unable to log in under the credentials that created that content. If you need help migrating your user data to another authentication scheme before you enable SSO, you should contact Jive Professional Services.

25 Installing 25 Understanding SSO with SAML When you implement single sign-on (SSO) with SAML 2.0, information for each user is passed from the IdP in the form of a digitally-signed XML document. SAML is a protocol for exchanging authentication credentials between two parties, a service provider (SP) and an identity provider (IdP). In this case, Jive plays the role of SP. The SP sends a request for authentication to the IdP, which then tries to authenticate the user. Authentication typically uses a username and password. The IdP typically also contains user information such as login ID, name, address, department, and phone. After authenticating the user, the IdP then sends a SAML XML response message back to the SP, which then logs the user in. Depending on your requirements, you can use SAML solely for authentication users; for group authorization; or for populating the Jive profile by synchronizing from the IdP on login. Jive authentication through SAML includes the following stages: 1. A user visits Jive and requests a page that requires authentication. 2. Jive redirects the user to the configured IdP. The request URL includes a base64-encoded version of some request XML. 3. If authentication doesn't succeed, the user sees a login screen. 4. The IdP sends an encoded XML-based response in a redirect to Jive. If the user was successfully authenticated, this response includes the information we need to create a Jive representation of the user. 5. Jive parses the XML and validates the necessary signatures, decrypting if necessary. A valid response from the IdP at this point indicates the user has been successfully authenticated. 6. Jive parses the XML response from the IdP and creates or updates the user, using any override attributes you specified in Jive. If users have been seeded beforehand and shouldn't be updated, profile sync can be disabled. 7. The user is authenticated with Jive and redirected to the requested destination. Getting Ready to Implement SAML SSO Before you begin configuring a SAML SSO implementation, make sure you read about the requirements and best practices. A successful SAML implementation requires the following prerequisites. An identity provider that complies with the SAML 2.0 standard. For more information, see SAML Identity Providers. You should make sure you have expert knowledge of how to configure your identity provider before proceeding. Familiarity with the SAML 2.0 specification. Before you begin the process of configuring Jive as a SAML 2.0 service provider to your IdP, you need to understand the details of how SAML works or else enlist the assistance of a SAML professional. The links that follow can supply some of this information. Oasis SAML Technical Overview (.pdf) Wikipedia entry on SAML 2.0 Upgrade to Upgrade to Jive if you're planning to do an out-of-the-box integration with SAML SSO. Earlier versions will require patching and other assistance from Support. SSL Implementation It is theoretically possible to implement SSO without SSL, but this raises some difficult security challenges. You should implement SSL, and you'll find it much easier to set up SSO if your jiveurl uses https, not http. Disable Storage Provider File System Caching Before you begin setting up SAML, go to System > Settings > Storage Providerand click Edit. Then select No under Cache Enabled. You won't be able to modify your IdP metadata unless caching is disabled.

26 Installing 26 LDAP Integration If you're going to use LDAP in conjunction with SAML, we recommend using SAML for authentication only, while using LDAP for user provisioning, user deprovisioning, and profile synchronization. LDAP setup can be a lengthy process including VPN setup and testing, so allow time for this setup process if you're implementing LDAP as part of your SSO implementation. Migrating Existing Jive Users Before you implement SAML, make sure you have a migration strategy for any existing Jive users. Implementing SSO without migrating your users to your new authentication provider will orphan existing user accounts, so users can't access their community content. If you use LDAP sync, CSV sync, or web services to auto-provision users, you can use Username Identity to look up existing users by username. If you don't, you can manually create users in the new jiveexternalidentity table. Please contact Support for help if you're planning to use this approach. If you use Username Identity, you need to make sure your existing users are marked as federated users. Jive Support can help you with this step. Required Information Before you begin the configuration process, you must have the following information available: The IdP metadata (URL location or file content). Specifying a URL usually makes updates easier. Your metadata needs to include the following information: The IdP entity ID The IdP KeyInfo element The IdP Location that defines your endpoints If you can't verify that this information is included, talk to your IdP administrator. Note: To integrate Jive with SAML, you need the complete metadata file, not just the information described above. The friendly attribute names sent with each SAML assertion. Planning for Jive User Provisioning and Profile Synchronization When you implement SAML, you need to decide on a strategy for which members of your organization will be included in the Jive Community, and with what rights. For example, you'll need to decide whether all your organization's users should be able to create accounts in the Jive community, and whether you will assign them to authorization groups. If you're primarily responsible for the technical implementation of this feature, make sure you discuss these decisions with your Community Administrator. Configuring IdPs for SSO Certain IdPs require special configuration before you can set up SAML SSO. The following list describes some known configuration prerequisites for specific IdPs. These are tips and, obviously, do not provide a complete description of required IdP configuration for your identity provider. ADFS Set the expected digital signature to SHA-1 ADFS expects the digital signature to be SHA-256, but Jive sends it as SHA-1. To change this expectation, go to the Advanced tab of your Relying Party Trusts profile and set the secure hash algorithm to SHA-1.

27 Installing 27 Siteminder Use the jive entityid as the Siteminder profile name Typically, the Jive entityid, which is set using the Base metadata URL in the Advanced tab of your SAML SSO settings, is the same as the jiveurl. SAML Identity Providers Jive can be integrated with a wide variety of SAML IdPs. Jive regularly tests SAML support with integrations to the following IdPs: Microsoft ADFS (the most common SSO provider used by our customers) Shibboleth: (the open-source standard for IdPs) and can typically assist with configuration for these providers. Troubleshooting assistance for other IdP integrations is available through Jive Professional Services. Configuring SSO with SAML SAML configuration Fastpath: Admin Console: People > Settings > Single Sign On > SAML Understanding SSO with SAML You can use the SAML settings dialog to set up single sign-on with an SAML identity provider, or to enable, disable, or tweak a configured SAML SSO configuration. Note: Before you begin configuring SAML setup, please read Getting Ready to Implement SAML SSO. Note: When you change any settings in the SAML configuration dialogs, you need to restart Jive before the settings take effect. Setting Up the IdP Connection To begin setting up the connection between Jive and your identity provider, use the following steps: 1. Enter the metadata URL for your SAML provider and click Load. (If you don't have a metadata URL, you can click Edit Metadata to paste in the XML containing the connection metadata.) 2. Optionally, edit the metadata if it contains any non-conforming code and click Save Settings to load it. You should ensure IDP metadata has a validuntil date that is still valid, or else remove it to keep the metadata from expiring. 3. Map the user attributes in the Jive profile to your IdP's attributes. For more information about this topic, see User Attribute Mapping. Note that importing or saving your metadata populates the General tab with a list of attributes from your IdP, so you can use it as a reference when you specify the attributes you want to map. 4. If you want to assign users to groups by passing a special group attribute from your IdP to Jive, select Group Mapping Enabled and supply the attribute. For more information, see Group Mapping below. 5. Click Save Settings. 6. If you have v5.0.3, go to your Jive instance URL and append /saml/metadata to the end. If you have version or higher, click Download SAML Metadata at the top right of the SAML tab. You'll need this information to configure your IdP with a profile for Jive User Attribute Mapping User Attribute Mapping is used to identify fields in the Jive profile that you plan to populate from the IdP profile by synchronizing them on login. To map a field, specify the IdP attribute used to identify it in the text box and select the Federated check box. Any fields you don't map will be user-configurable in the Jive profile settings. (A field that you specify, but do not mark as federated, will be populated with the specified value but still configurable.) By default,

28 Installing 28 Jive uses the NameID property as the key unique identifier for a user. You can select Override Subject NameID for Username and specify a different attribute if you want to use a different key identifier. For more information about the ins and outs of User Attribute Mapping, see SAML SSO Attribute Mapping Tips. Group Mapping You can assign users to security groups automatically by passing a special group attribute from the IdP to Jive. Select Group Mapping Enabled to enable this functionality and provide the AttributeName of the attribute containing your group information. This attribute value must include multiple attribute value elements, each of which defines the name of a group in which the user should be placed. The group mapping attribute will be used to get security group names from each assertion. If the corresponding groups with these names don't exist, they will be created when you synchronize, and users will be added to these groups. If you use group mapping, you can't manage authorization groups individually in Jive. All your IdP-provisioned security groups will be replicated in Jive. Fine-Tuning Using Advanced Settings You may need to refine or debug your integration using the Advanced SAML Integration Settings. SAML SSO Attribute Mapping Tips Determining your IdP's Attributes The easiest way to figure out how your IdP's attributes are set is to set the field in the General tab of Jive to something you know isn't in the response, like xxxx , and then look at the error message for all the available attributes in the SAML Response. Many IdPs assign both a Name and a Friendly Name to each assertion attribute. When you're setting up Attribute Mapping, you should use Name. For ADFS, the Name value typically looks like a URL, for example claims/ Jive doesn't support mapping to complex profile fields such as multiple select lists or addresses. Advanced SAML Integration Settings The settings on the Advanced tab are used to refine and troubleshoot a SAML integration. The following settings on the Advanced tab control some less commonly used SSO configuration. Debug Mode Base metadata URL Enable Username Confirmation for New Users, Enable Confirmation for New Users, Enable Name Confirmation for New Users Enable to provide detailed logging for troubleshooting authentication problems. You need to enable this setting during setup and validation, but turn it off in production. This value sets the desired URL for the entityid and endpoint URLs. This URL should be an https. If you aren't using a URL with https, you need to get help from Support to continue setting up SSO. These settings define the behavior for new users when they first log in. When they're selected, users will be asked to confirm that they want to use their Single Sign-On credentials to interact with the community. By default, these settings are all disabled, since in most cases the intended result is for users to log in using SSO. The Enable Name Confirmation setting has an additional application when users typically log in with either a single-word username or an address, but may need the option to provide a first/last name combbination. If

29 Installing 29 you select this check box, users can write to those profile fields after initial login. Note: These fields also apply to any users who may be logging into your community using External ID. Sync user profile on login Username Identity Logout URL Response Skew Maximum Authentication Age Passive Authentication Enable this setting to update users based on the remote user profile each time they log in. This setting is enabled by default and should not be disabled unless you seeded the Jive community with users before enabling SSO. When you select this checkbox, Jive does an exact match by username to find the Jive account and bypass the external identity table. You should select this checkbox if you use LDAP sync, CSV sync, or web services to autoprovision users, or you already have existing users in the instance who will be using SAML from now on. For more information about using this setting when you have existing Jive users, see Migrating Existing Users. By default, /sso/logged-out.jspa is a page that doesn't require authentication. If guest access is disabled, users need to land on a non-authentication-requiring page. (Otherwise they'd be automatically logged in again.) If guest access is enabled, you can also set this value to /. Another option is to set it to the IDP logout URL, so that the user is logged out of both Jive and the IDP. We do not support the SAML SingleLogout (SLO) protocol. Changing this setting requires you to restart the Jive server. Specifies the maximum permitted time between the timestamps in the SAML Response and the clock on the Jive instance. The default value is 120 seconds. If there is a significant amount of clock drift between the IDP and Jive, you can increase this value. The same value is also used for the skew in the NotBefore check in the response. If you see an error indicating a problem with the NotBefore check and you aren't able to fix the clock difference problem, you can try increasing this value. However, increasing the response skew value can increase your security risk. Identifies the maximum session time that's set for the IdP. The default setting is two hours. However, to avoid login failures, you need to set this to match the maximum session set on the IdP. (Some IdPs are set to expire sessions every eight hours or more.) When guest access is enabled, issues a SAML AuthnRequest upon first access with "ispassive=true", which should cause the IDP to simply redirect back to Jive if the user doesn't have an active session with the IDP. Note that in 5.0.3, this does not exclude robots, so an instance is effectively excluded from Google or Facebook share, because those bots cannot navigate

30 Installing 30 NameID Format NameID Allow Create Include Scoping Proxy Count Force Authentication SSO Service Binding Sign Metadata Sign Assertions Request Signed Requested AuthnContext Requested AuthnContext Comparison RSA Signature Algorithm URI Key Store the SSO process (even though they don't need to authenticate). If you need to list your site on Google or share it on Facebook, don't enable this setting. For most IdPs, using the default setting is correct. By default, this check box is cleared. You should leave it cleared unless you receive an error about NameID creation while setting up your SAML integration. This check box is selected by default. If you use ADFS, you should clear it. This setting specifies whether to include the maximum number of proxies any request can go through in the request to the IdP. The check box is cleared by default. Forces any user with an existing IdP session to log in again. Defines whether Jive should send the request to the IDP with an HTTP GET Redirect or a POST. The default service binding is HTTP-Redirect, but the most common value is urn:oasis:names:tc:saml:2.0:bindings:http- POST. (Make sure that the Location binding is in the IDP metadata.) POST is preferred because older versions of Internet Explorer and some firewalls have restrictions on the length of the HTTP path. Note: If you're configuring ADFS, keep in mind that using POST can cause problems for users on Safari. Specifies that metadata should be signed. You should clear this check box UNLESS your IDP requires that the metadata be signed. If you use ADFS, you must clear this check box. This option is enabled by default, and it allows AuthnResponse validation to pass if either the Response or the Assertions within the Response are signed. Clearing the checkbox enforces that the Response must be signed. Most IDPs sign the Assertions section in the AuthnResponse. If you use SFDC, however, you should clear this checkbox, because SFDC only signs the entire Response. This setting determines whether the saml request is signed or not. Enabling this setting can increase security, but it's incompatible with some IdPs. This setting is disabled by default. Along with Requested AuthnContext Comparison, this optional setting is used to add additional information to requests in certain specific cases. It's disabled by default. Along with Requested AuthnContext, this optional setting is used to add additional information to requests in certain specific cases. It's disabled by default. This setting is used to troubleshoot ADFS integrations. This feature is used by Support for troubleshooting.

31 Installing 31 Troubleshooting SAML SSO Running SSO in debug mode will help you troubleshoot your integration. An attribute is missing, or was mistyped In the following sample error message, the name of the attribute configured for the user's address was named , but that doesn't exist in the saml message. In this example, MAIL is the name of the correct attribute. com.jivesoftware.community.aaa.sso.ssoauthentica User did not have the required attributes send from the identify provider. Missing attribute: . Given attributes: [MAIL, title, companyname, FIRSTNAME, LASTNAME] "Missing attribute" field in an error message is blank If you see a message like this: com.jivesoftware.community.aaa.sso.ssoauthentica User did not have the required attributes send from the identify provider. Missing attribute:. Jive is trying to sync a single name as Firstname and Lastname. To work around this problem, set the system property saml.namefield to the same attribute the first name is populated from. Authentication works on some nodes, not others "Responder" message. You may discover that the certificates in the metadata for each node are different: Jive metadata won't be the same on each node and so authentication will succeed on some nodes and fail on others. To verify that the same key is being used on each node, go directly to the path /saml/metadata for each node. This problem occurs when Storage Provider file system caching is enabled. To disable it, go to System > Settings > Storage Providerand click Edit. Then select No under Cache Enabled. If you get any status message in this format: <samlp:status> <samlp:statuscode Value="urn:oasis:names:tc:SAML:2.0:status:Respo > <samlp:statusmessage>something_is_wrong</ samlp:statusmessage> </samlp:status> this indicates a problem with your IdP configuration.

32 Installing 32 An assertion fails on the notbefore condition If the IdP clock is ahead of the Jive clock by even a second, the notbefore check fails and you get the message Assertion is not yet valid, invalidated by condition notbefore? This problem can be caused by clock drift on either end, but you can also try addressing it by adjusting the Response Skew setting in the Advanced SSO settings. username doesn't exist in attribute If you see the following message: IdP-Specific SAML SSO Issues Some problems and workarounds only apply to specific IdPs. ADFS ERROR org.springframework.security.saml.samlprocessin - There was an error during SAML authentication java.lang.illegalargumentexception: [Assertion failed] - this argument is required; it must not be null The attribute with the username does not exist--it may be in the Subject NameID instead, in which case you should make sure the Override Subject NameID for Username checkbox is cleared in the General tab of your SAML settings. Otherwise, you may need to add the username attribute to the SAML message. Responder error with details mentioning the Scoping element. To fix this problem, select the Include Scoping checkbox in Advanced Settings. PingFederate A UAT instance doesn't work in the same browser where a production SSO IDP session existed This problem is caused by a session cookie handling problem. You can work around it by always creating a new browser session before testing in UAT. Siteminder IDP metadata won't save in Jive AudienceRestriction attribute contains incorrect or multiple entityids for jive instance OpenSAML has a bug where the validuntil timestamp on the IDP metadata's IDPSSODescriptor is checked incorrectly, and will only pass validation if the timestamp is invalid. The workaround is to remove the IDPSSODescriptor validuntil attribute from the metadata. This problem occurs when the SP profile name in SiteMinder is not the same as the entityid in Jive, causing a validation error.

33 Installing 33 Understanding SSO with Kerberos When you implement single sign-on (SSO) with Kerberos, LDAP handles all the authorization and user synchronization, while Kerberos handles authentication. Kerberos is an authentication protocol that is meant to be used in conjunction with an LDAP-enabled instance. LDAP handles all authorization and user synchronization, while Kerberos handles authentication. On Windows and Mac machines that are joined to an Active Directory domain, users can seamlessly log into Jive without entering a username or password, or even seeing a login screen. Users who are not logged into the domain on their computers will still see a standard login form. Because authentication uses a single token passed from the operating systems, no redirect is required. The token is verified against the configured Key Domain Controller (KDC), and if it's valid, the user is logged in. Communication with the KDC typically uses the standard service principal string and password. However, you can also specify a keytab and krb5.conf file. Configuring SSO with Kerberos Fastpath: Admin Console: People > Settings > Single Sign On > Kerberos Understanding SSO with Kerberos Note: Before you configure SSO, make sure you have a migration strategy for your existing Jive users. Implementing SSO without migrating your users to your new authentication provider will orphan existing user accounts, so users can't access their community content. Setting Up Kerberos SSO Service Principal Realm (KDC) Key Distribution Center Password The service principal used to communicate with the KDC and validate any user tickets passed to Jive. Typically, the Service Principal value is the username for an account. The realm for the service principal account username you specified. The hostname for the key distribution center. You may not need to provide this information if the realm already resolves to the KDC. Specifies the password for the service principal account username you specified. Advanced Settings The following settings on the Advanced tab control some less commonly used SSO configurations. Debug Mode Use Keytab for Authentication Use KRB Configuration File Enable to provide detailed logging for troubleshooting authentication problems. You should disable this setting in production. Enable to specify a keytab file as an alternate credentialling method. To upload your keytab file, you need to Base64-encode it and paste it into the text box provided. Enable to specify a krb5.conf file. Then paste the file contents into the text box provided.

34 Installing 34 Understanding SSO with External Login When you implement single sign-on (SSO) using an external login, users can choose to log in using any of several different authentication providers including Facebook, Google, and OpenID. External logins are a good choice for public communities because authentication can be passed to a third-party provider. The community user enters credentials on the provider site. The authentication token is then passed back and verified on the Jive side. Community users can log in with any number of different providers and have all their details pre-populated. For sites that support an avatar attribute, avatars are synchronized as well. An external login implementation can optionally include Facebook Connect authentication. Both OpenID and Facebook Connect use the Attribute Exchange standard for exchanging information, which enables Jive to pull in profile information about new users. After login the user sees a confirmation page and can verify profile information, pick a username (if this information isn't prepopulated from the profile), and proceed to the Jive community. OpenID with Facebook Authentication Enabling Facebook authentication requires you to register your Jive instance as an app on the Facebook developer site. You'll need the application id and the application secret to configure single sign-on. Configuring SSO with External Login Fastpath: Admin Console: People > Settings > Single Sign On > External Login Understanding SSO with OpenID Note: Before you configure SSO, make sure you have a migration strategy for your existing Jive users. There is no way to link an existing Jive user account to a Facebook account, and an existing Jive user whose external account uses the same address will not be able to use that account in Jive. To implement SSO for Jive with external logins, you set this page to Enabled and select the top four identity providers you want users to choose from on your site. You select identity providers by dragging them into the yellow area on the page. If you disable external logins after enabling them, Jive users will need to authenticate against Jive directly instead of using an external login. To troubleshoot authentication problems, you can enable Debug Mode. You should disable this setting in production. Facebook Configuration Before you can enable Facebook login, you need to create an app on the Facebook developer site. Provide your app credentials (the Application ID and secret) to complete SSO authentication with Facebook. SSO and Mobile As of Jive 5.0.1, by default, internal communities (i.e., communities that typically involve only employees or other internal audiences) with the Mobile plugin will no longer send user credentials through the Jive Mobile Gateway. Instead, users must register their devices with the Jive desktop application first before mobile access is granted. Users register mobile devices from the Jive desktop application by going to Preferences > Mobile and following the prompts (for more about how to register a device, see the Mobile plugin documentation). After this one-time registration is completed, the device is enabled for mobile access until it is unregistered. External Jive communities (i.e., communities that typically involve your customers, vendors, and other external audiences) will continue to use username/password-based mobile login by default. If you need to change these defaults, please contact Jive Support.