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... 10
Changing the Root Context (optional)... 13
Setting Up a Cache Server (optional)...13
Post-Installation Tasks... 14
Installing On a Cluster (optional)...15
Configuring a Cluster Node (optional)...17
Installation Known Issues... 17
Adding Features with Plugins... 17
Configuring Delegated Authentication... 18
LDAP and Active Directory Guide... 19
Overview of LDAP Integration Steps... 19
Using LDIF to Inventory Your LDAP Configuration...20
Configuring LDAP After Initial Setup...21
Synchronizing LDAP Users... 21
LDAP System Properties...22
Single Sign-On... 24
Understanding SSO with SAML...25
Getting Ready to Implement SAML SSO...25
Configuring IdPs for SSO... 26
SAML Identity Providers... 27
Configuring SSO with SAML...27
SAML SSO Attribute Mapping Tips... 28
Advanced SAML Integration Settings... 28
Troubleshooting SAML SSO... 31
IdP-Specific SAML SSO Issues...32
Understanding SSO with Kerberos... 33
Configuring SSO with Kerberos... 33
Understanding SSO with External Login...34
Configuring SSO with External Login...34
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.
2 -- 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
Required 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.
4 Jive Web
App and Database
Required 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.
5 Cache
Server(s)
Optional 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.
6 Doc
Conversion Module
Optional 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.
7 Cluster
Nodes
Optional 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.
Steps Module Required or Optional Install Instructions 8 Final Setup
Required With a supported web browser, navigate to http://<hostname>/, 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=3128 -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 2.
3. 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.
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 443 Open in.genius.jivesoftware.com, out.genius.jivesoftware.com
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.jivesoftware.com,
gateway.jivesoftware.com, apphosting.jivesoftware.com, developers.jivesoftware.com
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.
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)
443 if you use SSL, 80 if not Inbound to Jive instance out.jive-mobile.com (204.93.64.112) Mobile (all locations, including
EMEA)
443 Outbound from Jive instance
gateway.jive-mobile.com (204.93.64.255 and
204.93.64.252) Mobile (EMEA only) 443 if you use SSL, 80 if not Inbound to Jive instance 204.93.80.122
Jive Present 443 Inbound to Jive instance 188.93.102.111,
188.93.102.112, and
188.93.102.115
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 https://
license.jivesbs.com
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.
• 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:
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-5.0.0-78305.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 65535
/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.
Debugging information isn't displayed.
JIVE_APPLICATION_NOSERVICEPrevents 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.
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-5.0.0-78305.x86_64.rpm -- might have a slightly different name.)
rpm -ihv jive_sbs-5.0.0.0-78305.x86_64.rpm
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-5.0.0.0-78305.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 Run this command as root
Activity Engine service jive-eae-service start
Web app nodes 1 and 2* service jive-application start
service jive-httpd start
Cache server(s)* and cluster nodes* service jive-cache start
Document Conversion* service jive-docconverter start
*Optional nodes
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 Run this command as root
Activity Engine chkconfig jive-eae-service on
Document Conversion chkconfig jive-docconverter on
Cache server(s) and cluster nodes chkconfig jive-cache on
Web app nodes 1 and 2 chkconfig jive-application on
3. 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 Run this command as root
Document Conversion service jive-docconverter stop
Cache server(s) and cluster nodes service jive-cache stop
Web app node 2 service jive-httpd stop
service jive-application stop
4. With a supported web browser, navigate to http://<hostname>/, 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 Run this command as root
Document Conversion service jive-docconverter start
Cache server(s) and cluster nodes service jive-cache start
Web app node 2 service jive-httpd start
service jive-application start
Web app node 1 service jive-httpd restart
service jive-application restart
6. See Post-Installation Tasks for your next steps.
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 high-level packages. If any of these packages (system or high-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 202068
-rw-r--r-- 1 root root 206701420 Jan 20 16:03 jive_sbs-5.0.0-78310.i386.rpm -rwxr-xr-x 1 root root 1347 Oct 7 16:14 updateDNS.sh
[root@targethost ~]# rpm -ivh jive_sbs-5.0.0-78310.i386.rpm error: Failed dependencies:
sysstat >= 7 is needed by jive_sbs-5.0.0-78310.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-7.0.2-1.el5.i386. 100% |=========================| 15 kB 00:00 ---> Package sysstat.i386 0:7.0.2-1.el5 set to be updated
---> Downloading header for bash to pack into transaction set.
bash-3.2-21.el5.i386.rpm 100% |=========================| 55 kB 00:00 ---> Package bash.i386 0:3.2-21.el5 set to be updated
--> Running transaction check Dependencies Resolved
============================================================================= Package Arch Version Repository Size ============================================================================= Installing:
sysstat i386 7.0.2-1.el5 base 168 k Updating:
bash i386 3.2-21.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-7.0.2-1.el 100% |=========================| 168 kB 00:00 (2/2): bash-3.2-21.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:7.0.2-1.el5
Updated: bash.i386 0:3.2-21.el5 Complete!
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-5.0.0-78310.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:
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 http://yourcommunity.com. This is the recommended configuration and default installation behavior, but non-root contexts such as http://
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 (http://yourcommunity.com/ 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.
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 4.5.0. 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.
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 BeginBefore 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.
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.
Topology
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
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.
4. 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 Description
Enable cluster Click Enabled to enable this node for the cluster.
Cluster members Lists the addresses of other nodes in this cluster. Select the Remove check box to have this node's address removed from the database.
Local Cluster Address 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.
Cluster Overview 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.
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.
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
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: 20081119215504.0Z whenChanged: 20090202220617.0Z displayName: Cyr , Karl
uSNCreated: 4391224
memberOf: CN=FilterGroup,OU=Jive_Users,DC=support,DC=jive,DC=com uSNChanged: 4399897
department: Awesome name: Cyr , Karl
objectGUID:: 2tnXRo7VxE6zc72YqLtOTw== userAccountControl: 66048 badPwdCount: 1 codePage: 0 countryCode: 0 badPasswordTime: 128769530029375000 lastLogoff: 0 lastLogon: 128742007081093750 pwdLastSet: 128716053043750000 primaryGroupID: 513 objectSid:: AQUAAAAAAAUVAAAAF8sUcR3r8QcekDXQw9wAAA== accountExpires: 9223372036854775807 logonCount: 0 sAMAccountName: karl sAMAccountType: 805306368 userPrincipalName: [email protected] objectCategory: CN=Person,CN=Schema,CN=Configuration,DC=support,DC=jive,DC=com dSCorePropagationData: 20081119220919.0Z dSCorePropagationData: 20081119220919.0Z dSCorePropagationData: 20081119220919.0Z dSCorePropagationData: 16010108151056.0Z 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.
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* The LDAP field name used to look up
username values
uid
ldap.baseDN* The Distinguished Name of the base of your LDAP tree
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.emailField* The element key for the Email attribute mail ldap.connectionPoolEnabledSpecifies whether to enable connection
pooling. See http://download.oracle.com/ javase/jndi/tutorial/ldap/connect/config.html
true
ldap.followReferrals Specifies whether LDAP queries will follow referrals. This property should always be set to true for Active Directory.
true
ldap.adminDN* The DN for the LDAP admin user. This user does not need to be a Jive user.
CN=AdminMan,OU=Domain Users,DC=support,DC=jive,DC=com ldap.adminPassword* The encrypted password for the LDAP admin a54313f2d3bc98fb5234566995246c7 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.
true
ldap.ldapDebugEnabledSpecifies whether LDAP debug logging is on.
Property Meaning Sample Value(s) 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.
ldap.sslEnabled Specifies whether to use an SSL connection to communicate with the LDAP server.
false
ldap.initialContextFactory
ldap.searchFilter The filter applied to a remote directory when searching for users
ldap.groupNameField The field that maps a group to its CN in LDAP.
cn
ldap.groupMemberFieldThe field that maps a group to its members. member ldap.groupDescriptionFieldThe field that maps a description of a group. description ldap.posixMode 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).
false
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).
false
ldap.groupSearchFilter^The filter applied to a remote directory when searching for groups.
(objectClass=group)
ldap.managerField Maps the DN of a user's manager. Used when syncing relationship fields.
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.
creationdate
ldap.userGroupMember^The field that maps a user to a group. This is a user attribute.
memberOf
ldap.userDN^ A RDN (relative to the baseDN) which contains users to sync to SBS.
ou=People
jive.sync.user.ldap Specifies whether user synchronizations are enabled.
Property Meaning Sample Value(s) jive.sync.relationships.ldapSpecifies whether user relationships are
synchronized from LDAP.
false
jive.sync.profile.ldap.photoSpecifies whether profile photos are synchronized from LDAP.
false
jive.sync.profile.ldap.loginSpecifies whether profiles are synchronized at login.
false
jive.sync.auto.disable Specifies whether Jive should disable user accounts which cannot be found in the LDAP directory.
jive.sync.auto.disable.att.nameThe name of the attribute which indicates whether or not an account is disabled in LDAP.
userAccountControl
jive.sync.auto.disable.att.valueIn Active Directory, use Microsoft article 305144 as a reference for setting user account properties. You can also set up a bit-specific filter such as:
userAccountControl:1.2.840.113556.1.4.803:=2
514 (see link)
jive.usernames.case.insensitiveSetting 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.
true
GroupManager.classNameControls whether or not permission groups are synchronized from LDAP.
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.
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, email 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 5.0.3
Upgrade to Jive 5.0.3 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.
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.
