Jive SBS Delegated Authentication

What is Jive SBS Delegated Authentication?

Delegated Authentication is a mechanism that allows a customer to control the definition of users outside of the Jive SBS system. This feature is available in Jive SBS starting with version 4.0.

Elements controlled by Delegated Authentication include:

existance of a user account
enabled/disabled state of a user account
password used to authenticate an account
profile fields associated with account

When Delegated Authentication is enabled and configured Jive SBS will make a simple Web Service call out to the configured server whenever a user attempts to login.

Web Service Details

When Delegated Authentication is enabled, the login process is as follows:

When a user tries to log in through the website or Jive API, a web services call passes the username, password, and sourceIP to a web service hosted by your organization. The web service must be deployed at a location that can be accessed by Jive servers.
Your implementation of the web service validates the information and returns a value for "authenticated" of either "true" or "false". Optionally, the web service can return profile information that should be used by Jive, and whether the user account is enabled or disabled.
If the disabled value is "true" then the user account will be disabled in the Jive SBS UI and the user is informed that the username and password combination was invalid.
If the authenticated value is "true" then the login succeeds. If "false" is returned, then the user is informed that the username and password combination was invalid.
If the authenticated value is "true" and includes profile data, the Jive profile information for the user will be updated with the supplied values.

The web service will be called using HTTP POST using the following parameters:

Name	Description
username	the user's username
password	the user's password
sourceIP	the IP address that originated the login request. This value can be used to only allow logins from a certain IP address range; for example, to ensure that a user is connected to the VPN.

The response to the web service call is an XML document with a single required parameter indicating whether the authentication succeeded. If authenticated has a value of "true" the web service response can include optional profile data so that the Jive profile is kept synchronized with an external profile such as an LDAP directory or website member data. An optional attribute will control if the user account should be disabled.

Name	Description
authenticated	"true" if the user should be authenticated, "false" otherwise. When "true", an optional profile element can be specified to update the user's profile data
disabled	"true" if the user account should be disabled, "false" otherwise.

The values contained in the <profile> element depend on the edition and configuration of your Jive SBS instance. All values are optional. The following is an example of values that are recognized by a Jive SBS Public Community:

Name	Description
firstName	The user's first name; the Jive profile will be updated with this value
lastName	The user's late name; the Jive profile will be updated with this value
occupation	The user's occupation; the Jive profile will be updated with this value if the profile field exists
company	The company the user works at; the Jive profile will be updated with this value if the profile field exists
phonenumber	The user's primary phone number; the Jive profile will be updated with this value if the profile field exists
biography	The user's biography; the Jive profile will be updated with this value if the profile field exists
url	The user's url; the Jive profile will be updated with this value if the profile field exists
expertise	A description of the user's expertise areas; the Jive profile will be updated with this value if the profile field exists
joindate	Date the user account was created; the Jive profile will be updated with this value if the profile fields exists
alternatephonenumber	The user's alternative phone number; the Jive profile will be updated with this value if the profile fields exists
alternateemail	The user's alternative email address; the Jive profile will be updated with this value if the profile fields exists

Example web service responses:

1. User is authenticated and certain profile data is included.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AuthenticationResponse xmlns:ns2="http://jivesoftware.com/authentication">
    <authenticated>true</authenticated>
    <profile>
        <firstName>Joe</firstName>
        <lastName>Smith</lastName>
        <email>joe.smith@example.com</email>
    </profile>
</AuthenticationResponse>

2. Authentication fails

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AuthenticationResponse xmlns:ns2="http://jivesoftware.com/authentication">
    <authenticated>false</authenticated>
</AuthenticationResponse>

Additional Recommendations and Considerations

We highly recommend using and requiring https for the web service end-point to improve security. When https is used, a valid signed certificate is required from a trusted provider such as Thawte or Verisign.
The web service endpoint must return a reasponse within 2 seconds. If a response is not returned within this period, the end-user will be shown an error message stating that the remote authentication service is not available.
The implementation of the web service must be accessible by Jive servers. Typically this means deploying the web service on a server in the DMZ then using the server's external DNS name when configuring authentication gateway URL within Jive.

Sample Projects

There are two attachments to this document for implementations of sample servers. Both of these servers have a sample implementation of user validation logic - if the user name is like 'userN@company.com' (where N is a number) and the password is 'passN' then the user will be authenticated. You can replace this sample implementation with your own logic.

delegatedsso-sample-cxf.tar

This is a sample Java implementation. It is a Maven project that uses CXF's support for JAX-RS to implement the server.

To get the sample up and running:

tar xvf delegated-sample-cxf.tar

cd delegated-sample-cxf

mvn install

mvn jetty:run

At this point you can access the webservice at a URL like:

http://localhost:8080/delegated-sample-cxf/jiveauth/auth?username=user1@company.com&password=pass1 8080/delegated-sample-cxf/jiveauth/auth?username=user1@company.com&password=pass1

This project will output a WAR file that can be deployed to your choice of App server.

You can replace the sample implementation in SampleSSOManager.java with your own implementation. To specify your implementation you can edit the spring configuration in cxf-beans.xml.

delegatedsso.zip

This is a ASP.Net project solution. After opening the project and running it you can access the sample at a URL like:

http://localhost/Auth.asmx/doAuth?username=user2@company.com&password=pass2&sourceip=//localhost/Auth.asmx/doAuth?username=user2@company.com&password=pass2&sourceip=

Implementation of sample service is in the Auth.asmx Web Service Code-Behind file Auth.asmx.cs.