The official version of this document is available here for 4.5 and here for 5.0.
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:
|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.
|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:
|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"?>
2. Authentication fails
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
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.
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.
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
At this point you can access the webservice at a URL like:
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.
This is a ASP.Net project solution. After opening the project and running it you can access the sample at a URL like:
Implementation of sample service is in the Auth.asmx Web Service Code-Behind file Auth.asmx.cs.
When setting up this service in IIS using .NET version 1.1 or higher you'll need to configure your web.config to allow parameters to be sent through HTTP POST.
<configuration> <system.web> <webServices> <protocols> <add name="HttpPost"/> </protocols> </webServices> </system.web> </configuration>
More details are available here - http://support.microsoft.com/kb/819267.