Overview

Yellowfin's Administration Service allows for integrating Yellowfin with essentially all third-party authentication processes. Primarily an authentication bridge will be used when implementing Yellowfin as a standalone application or even a tightly integrated application. But to integrate with a third-party authentication process, a custom bridge needs to be created. This bridge will match a user's credentials from a third-party source with those in the Yellowfin system. Usually the authentication source will provide a username, but at times a password and other user attributes, to authenticate the user.

Once a match is made with an existing Yellowfin user, the bridge will perform a Single Sign-On (SSO) of that user into Yellowfin. This can be done using either the LOGINUSER web service (which requires a password for the user to log in), or the LOGINUSERNOPASSWORD service, which allows the bridge to log a user in, using only their username. This seems ideal, since very rarely will there be a password available from the third-party source.

The bridge is not necessarily used to determine whether or not the user is allowed to log in. The fact that the bridge receives the username, means that the user has already been validated. However, sometimes it will be responsible for “asking” the third-party if the user is valid.

Sometimes there will be a need to auto-create the users if they do not exist in Yellowfin. This might require using additional information to create the user, like their email address, first and last names, etc. which should be sourced from the third-party application. The bridge can use the GETUSER or VALIDATEUSER web service functions to determine if a user exists in Yellowfin or not and the ADDUSER web service call to create a user. If bulk user creation is required, the ADDUSERS web service function can be called.

Part of the bridge process may also be to modify the user's Yellowfin role or group membership as part of the login process. If Yellowfin is integrated with a product where access to different content may change, it may be required to update this group membership during the login process. This would require sourcing information from the third-party source about which groups a user should be added to/removed from. The UPDATEUSER web service call will allow a user’s role to be modified and the INCLUDEUSERINGROUP or EXCLUDEUSERFROMGROUP calls can be used to add or remove from groups that determine which Yellowfin content they can access.

The bridge can be implemented in many ways, such as being integrated as:

• a part of Yellowfin itself (as a JSP, Servlet or Filter within the Yellowfin web application);
• a standalone application (GUI, console or web application) that communicates with the third-party source and Yellowfin;
• a part of the third-party application itself.

The best place to implement the bridge will depend on the environment and components involved.

When implementing within the Yellowfin container, the various implementation methods will allow for different functionality to be included. JSPs and Servlets allow for implementing code when the user is directed to a particular URL, whereas filters allow for checking authentication on any URL requested from the Yellowfin system.

Here is a basic process of what a Yellowfin authentication bridge needs to do:

1. Get details via cookie, file, or network connection.
2. Check if the user already exists?
3. If user doesn't exist, then create user with the details provided.
4. If required, update user's details (such as, role, group, etc.)
5. Perform a SSO call to log the user in.

Note: If your authentication provider supports SAML, the Yellowfin SAML bridge can be used to SSO users.

Single Sign-on Functions

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.web.mi.hof.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <web:remoteAdministrationCall>
         <arg0>
            <loginId>admin@yellowfin.com.au</loginId>
            <password>test</password>
            <orgId>1</orgId>
            <function>LOGINUSER</function>
            <person>            
               <userId>admin@yellowfin.com.au</userId>
               <password>test</password>
            </person>
         </arg0>
      </web:remoteAdministrationCall>
   </soapenv:Body>
</soapenv:Envelope>

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:remoteAdministrationCallResponse xmlns:ns2="http://webservices.web.mi.hof.com/">
         <return>
            <errorCode>0</errorCode>
            <loginSessionId>689bce5624f1e5a312eb5ef7801ed9fc</loginSessionId>
            <messages>Successfully Authenticated User: admin@yellowfin.com.au</messages>
            <messages>Web Service Request Complete</messages>
            <sessionId>c8021e27fcc2ce507ff17ec1846919a5</sessionId>
            <statusCode>SUCCESS</statusCode>
         </return>
      </ns2:remoteAdministrationCallResponse>
   </S:Body>
</S:Envelope>

http://<YELLOWFIN-SERVER>/logon.i4?LoginWebserviceId=<TOKEN>

<script type="text/javascript" src="http://localhost/JsAPI?dashUUID=e9a6ab0a-bcb0-4fe6-9663-4dd33e58f08e&token=<TOKEN>"></script>

<%            
/*       ws_admin_singlesignon.jsp         */              
%>
<%@ page language="java" contentType="text/html; charset=UTF-8" %>
<%@ page import="com.hof.util.*, java.util.*, java.text.*" %> 
<%@ page import="com.hof.web.form.*" %>
<%@ page import="com.hof.mi.web.service.*" %>
<%
String url = "http://localhost:8080";         //provide your Yellowfin URL

AdministrationServiceService s_adm = new AdministrationServiceServiceLocator("localhost",8080,"/services/AdministrationService", false);        // adjust host and port number


AdministrationServiceSoapBindingStub adminService = (AdministrationServiceSoapBindingStub) s_adm.getAdministrationService();
AdministrationServiceRequest rsr = new AdministrationServiceRequest();

rsr.setLoginId("admin@yellowfin.com.au");          // provide your Yellowfin webservices admin account
rsr.setPassword("test")                            // change to be the password of the account above
rsr.setOrgId(1);
rsr.setFunction("LOGINUSER");

AdministrationPerson ap = new AdministrationPerson();
ap.setUserId("user@yellowfin.com.au");                  // provide existing Yellowfin user to login
ap.setPassword("usertest");                             // password of the user above

rsr.setPerson(ap);

String[] parameters = new String[] {"ENTRY=TIMELINE","DISABLEHEADER=TRUE"};
rsr.setParameters(parameters);

AdministrationServiceResponse rs = adminService.remoteAdministrationCall(rsr);


String token = "";
if ("SUCCESS".equals(rs.getStatusCode()) ) {
               token = rs.getLoginSessionId();
               response.sendRedirect(url + "/logon.i4?LoginWebserviceId=" + token);
} else {
               out.write("Single Sign on Failure");
               return;
}
%>