Jive SBS Delegated Authentication

    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:

     

    1. 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.
    2. 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.
    3. 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.
    4. 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.
    5. 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
    usernamethe user's username
    passwordthe user's password
    sourceIpthe 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
    firstNameThe user's first name; the Jive profile will be updated with this value
    lastNameThe user's late name; the Jive profile will be updated with this value
    occupationThe user's occupation; the Jive profile will be updated with this value if the profile field exists
    companyThe company the user works at; the Jive profile will be updated with this value if the profile field exists
    phonenumberThe user's primary phone number; the Jive profile will be updated with this value if the profile field exists
    biographyThe user's biography; the Jive profile will be updated with this value if the profile field exists
    urlThe user's url; the Jive profile will be updated with this value if the profile field exists
    expertiseA description of the user's expertise areas; the Jive profile will be updated with this value if the profile field exists
    joindateDate the user account was created; the Jive profile will be updated with this value if the profile fields exists
    alternatephonenumberThe user's alternative phone number; the Jive profile will be updated with this value if the profile fields exists
    alternateemailThe 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=pass18080/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.

     

    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.