Using LDAP for WebHelp with Feedback authentication

Post here questions and problems related to oXygen frameworks/document types.
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

Has anyone tackled this yet? I have 2 days to attempt it. I have the PHP LDAP library I need, so I just need to replace the existing login functions to perform an LDAP query instead. Registration isn't necessary, since all employees are already in the LDAP accessible Active Directory database.

I'm assuming I'll need to do the following:

* Hide the registration UI elements
* Replace the login functionality that queries the users database table with a query to the LDAP service. If the login is successful, check to see if the user is already in the users database table. If the user isn't already there, add it as a new user in the table so that all other user-base functionality works. If the user is already in the table, then no database action needed.

John
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

There's a step I missed.

If the user is the administrator username, then bypass LDAP and authenticate via the database table.
sorin_ristache
Posts: 4141
Joined: Fri Mar 28, 2003 2:12 pm

Re: Using LDAP for WebHelp with Feedback authentication

Post by sorin_ristache »

Hi John,

We plan to add LDAP authentication in a future version of Oxygen. If you want to try it I think you should modify the Ajax calls to the PHP files in directory OXYGEN_DIR\frameworks\docbook\xsl\com.oxygenxml.webhelp\oxygen-webhelp\resources\php which you can find in the functions from OXYGEN_DIR\frameworks\docbook\xsl\com.oxygenxml.webhelp\oxygen-webhelp\resources\js\comments-admin.js, or maybe just replace the calls to the MySQL database in the PHP files with calls to a LDAP server.
Regards,
Sorin

<oXygen/> XML Editor Support
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

Thanks Sorin.

(1) Given our timezone differences, I identified the same files you mentioned. Given that I'm unfamiliar with the codebase, I'm being cautious about making assumptions. I'm going through checkUser.php now. I want to make the smallest, most surgical changes I can in the right places to not inject craziness. I'm looking to see if authentication/authorization status of a user is stored in the session object at all, or if it needs to ping the LDAP server for each page access. This webhelp site will always be within our firewall, so it doesn't have to be perfect at the outset.

When you look at building in other authentication methods, I'm assuming that there are pluggable PHP options out there for you to leverage.

(2) At a functional level, I'm still a bit confused about relationship between the database and multiple product/versions. Can a single database support multiple product/version pairs? From the code I've seen, it appears it might.

What's the relationship, if any between the version in the comments table and the webhelp table?
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

There are also queries that reference the user, product, and version as a triplet in another relationship that I haven't been able to infer yet. Can a user have different level and notification settings per product/version? This would be handy, since there could easily be different moderators for different products from different business groups. If not, would it be necessary to create a different database for different products?
sorin_ristache
Posts: 4141
Joined: Fri Mar 28, 2003 2:12 pm

Re: Using LDAP for WebHelp with Feedback authentication

Post by sorin_ristache »

Hi John,

There are some code modifications that need to be done for adding LDAP authentication to the WebHelp-Feedback system. I think these cmodifications are not straightforward for someone who is not already familiar with the code for user management in the WebHelp-Feedback system.

Anyway we will work on it and we will let you know when we have something ready.
Regards,
Sorin

<oXygen/> XML Editor Support
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

Thanks Sorin. I've looked over about 6000+ lines of code to get familiar with the webhelp application. It looks to me like I just need to make the branch for LDAP validation in the "validate" function in the PHP User class. I will leave the session caching of user authentication info alone. I'll also need to suppress the "Sign Up" button. I am planning to add a variable definition to the config.php file to indicate the authentication method.

I have a deadline of this Monday to get this working so I'm sure at least one of us will get there by then. I have code from another in-house PHP web application that wraps all the LDAP weirdness into a simple function accepting a username/password pair and returns data about the user, including email address, etc. I'll then insert that data into the users database table on the first login attempt so that the rest of the application works as is. The user can change their notification options from the existing profile editor form.

I've also been asked to add a "completed" status to the comments to indicate that the comment has been addressed with an email notification to the comment submitter, along with the appropriate UI and database changes.

If you like, I can continue this dialog via email so I can exchange source code with you.
sorin_ristache
Posts: 4141
Joined: Fri Mar 28, 2003 2:12 pm

Re: Using LDAP for WebHelp with Feedback authentication

Post by sorin_ristache »

Hi John,
kirkilj wrote:I have a deadline of this Monday to get this working so I'm sure at least one of us will get there by then. I have code from another in-house PHP web application that wraps all the LDAP weirdness into a simple function accepting a username/password pair and returns data about the user, including email address, etc. I'll then insert that data into the users database table on the first login attempt so that the rest of the application works as is. The user can change their notification options from the existing profile editor form.
In that case I think you can try to add LDAP authentication by modifying the code in User.php. Sorry I can't be more helpful, we didn't add the LDAP authentication yet. We are thinking to offer the authentication method (WebHelp classic via MySQL or LDAP) as an option at installation in the Web browser.
Regards,
Sorin

<oXygen/> XML Editor Support
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

Hi Sorin,

I've made changes in the CSS, PHP, and JavaScript to allow for LDAP integration. I had to suppress the signup button. In the User class, I'm changing the validate function so that if the username/password pair isn't found in the DB users table, it checks to see if LDAP is enabled. If so, it attempts to validate through the LDAP repository. If it does validate, it calls on the User class' InsertNewUser function to put it in the DB users table and then calls the same class' confirmUser function to immediately confirm the user and bypass the email validation process. I stayed clear of the session management of user information so that it would function the same way as it does for SQL authentication.

I also had to suppress the Lost Password and Signup links on the Login dialog through the localization strings by setting them to the empty string. These links are inserted by the WebHelp transform itself with no id attribute to key off of for CSS and I just wanted to focus on the contents of the .../oxygen-webhelp/resources directory to compartmentalize the changes.

I'm sure that there are cleaner ways of doing all of this, but I had to hold my nose and get it working quickly. I may have a few other use cases to consider. Hopefully, I'll be done today and can move onto adding a "completed" status to comments so reports can be run.
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

Amid all the text about LDAP authentication, I embedded a second, unrelated question that I need an answer to:
kirkilj wrote:At a functional level, I'm still a bit confused about relationship between the database and multiple product/versions. Can a single database support multiple product/version pairs? From the code I've seen, it appears it might.

What's the relationship, if any between the version in the comments table and the webhelp table?
Should there be a product/version pair in the webhelp table each time a new version of a ditamap is generated, or just for the latest version of each product?

John
sorin_ristache
Posts: 4141
Joined: Fri Mar 28, 2003 2:12 pm

Re: Using LDAP for WebHelp with Feedback authentication

Post by sorin_ristache »

Hi John,

The relationship is that a row with the same product P and version V values must exist in the webhelp table for each row in the comments table with the same product P and version V values.

The webhelp table has one row for each product/version pair of a WebHelp set of pages deployed and installed in a browser. It can contain any number of distinct product/version pairs. Many different versions of the same product can be deployed on the same server.
Regards,
Sorin

<oXygen/> XML Editor Support
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

The webhelp table is an attribute/value table qualified by P and V. The parameter column has values (databaseVersion, dir, installdate, minVisibleVersion, name, and path). Will all of these rows be duplicated for each P,V pair, especially the minVisibleVersion parameter row? Different products could have different minVisibleVersions. I'll look to see where these get inserted as well.
sorin_ristache
Posts: 4141
Joined: Fri Mar 28, 2003 2:12 pm

Re: Using LDAP for WebHelp with Feedback authentication

Post by sorin_ristache »

There are 4 rows in the webhelp table for each P/V pair in which the parameter column contains: dir, installDate, name and path.

There is no minVisibleVersions value in any column of the table. It is a computed value, not a value stored in a table.
Regards,
Sorin

<oXygen/> XML Editor Support
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

Maybe I'm misunderstanding something. minVisibleVersion looks like a row-based parameter, not a column. The product version is a column though. Here's our webhelp table with some obfuscation:

Code: Select all


mysql> select * from webhelp;
+-------------------+---------------------------+----------------+---------+
| parameter | value | product | version |
+-------------------+---------------------------+----------------+---------+
| databaseVersion | 1 | oXygen | 1.0 |
| dir | /serv/helpsys/html | CRR-InfoCenter | 1.0 |
| installDate | 20141120184245 | CRR-InfoCenter | 1.0 |
| minVisibleVersion | 1.5 | CRR-InfoCenter | 1.0 |
| name | CRR-InfoCenter | CRR-InfoCenter | 1.0 |
| path | http://help.acmeprod.net/ | CRR-InfoCenter | 1.0 |
+-------------------+---------------------------+----------------+---------+
I've been poking around. The rows you mentioned are inserted in the installProduct function in do_install.php during the install, as well as the updateProductPath function, which updates the 3 rows you mentioned in the webhelp table on every single new comment insertion, which I can't see the reason for quite yet. Here it is:

Code: Select all

$db->run("UPDATE webhelp SET value='" . addslashes(__BASE_URL__) . "' WHERE parameter='path' AND product='" . $product . "' AND version='" . $version . "';");
$db->run("UPDATE webhelp SET value='" . addslashes(__BASE_DIR__) . "' WHERE parameter='dir' AND product='" . $product . "' AND version='" . $version . "';");
$db->run("UPDATE webhelp SET value='" . addslashes(__PRODUCT_NAME__) . "' WHERE parameter='name' AND product='" . $product . "' AND version='" . $version . "';");
Why would these need to be updated on every comment insertion? Perhaps I must be missing a major concept.

Here's what I've gathered from the code:

The minVisibleVersion webhelp row is either inserted or updated through the Admin Panel's set "Set Version" button to define which comments should be shown on the topic pages. For example, if the minVisibleVersion is set to 1.5 then all comments stamped with versions less than that would have their 'visible' column value set to false. It appears to be implemented in the Comment class' setMinVisibleVersion function. Maybe you're referring to the queryVersions and queryInfo functions in that class, which does compute the minVisibleVersion, but then it uses that value to populate the minVisibleVersion as a static value in the webhelp table.

In summary, I'm getting closer, but I'm concerned I don't really grasp if a single database can support multiple products. Since I only have one database on our MySQL server, I can't just test this out by generating and adding another product since it's our production server. Our dev and test database servers will be available to me in a few days.

The install topic in your Webhelp says:
Note: You can restrict the displayed comments of a product depending on its version. In case you have two products that use the same database and you restrict one of them to display comments starting from a certain version, the comments of the other product are also displayed from the specified version onwards.
Does this mean if we have product A for which we only want to display comments from version 2.3 onward, we can't have product B showing comments from it's version 1.6 onward in the same database? For us, version numbers of different product documentation are independent of each other?

John
sorin_ristache
Posts: 4141
Joined: Fri Mar 28, 2003 2:12 pm

Re: Using LDAP for WebHelp with Feedback authentication

Post by sorin_ristache »

kirkilj wrote:Why would these need to be updated on every comment insertion? Perhaps I must be missing a major concept.
They are updated for storing in the webhelp table the latest server installation path in case the server address is changed between adding two user comments on the WebHelp pages. I think you can ignore that because it does not affect the authentication, LDAP or otherwise.
kirkilj wrote:In summary, I'm getting closer, but I'm concerned I don't really grasp if a single database can support multiple products. Since I only have one database on our MySQL server, I can't just test this out by generating and adding another product since it's our production server. Our dev and test database servers will be available to me in a few days.
Yes it can support multiple products. Only those 3 rows are updated in the webhelp table that match the product ID and version number of the WebHelp set of pages where the user comment was added. The other rows in the same table are allocated for other products and they stay the same.
kirkilj wrote:The install topic in your Webhelp says:
Note: You can restrict the displayed comments of a product depending on its version. In case you have two products that use the same database and you restrict one of them to display comments starting from a certain version, the comments of the other product are also displayed from the specified version onwards.
Does this mean if we have product A for which we only want to display comments from version 2.3 onward, we can't have product B showing comments from it's version 1.6 onward in the same database? For us, version numbers of different product documentation are independent of each other?
The note is about one product only. The minimum version number (MVN) set to a product (identified by a product ID/version pair) works like this: one topic (WebHelp page) is shared between two or more products (which means two or more sets of WebHelp pages, each identified by a pair product ID/version number), so when that topic is displayed in the browser for product P1/V1 then all user comments are also displayed on the same WebHelp page from all topics with the same relative path (for example tasks/how-to-create-foo-bar.html) in all products with a version number larger than MVN.

These are really just details that you can ignore if you just want to add a new authentication method (LDAP).
Regards,
Sorin

<oXygen/> XML Editor Support
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

Thanks, as always, Sorin for the reply.

I want to understand the use-cases the feedback feature supports so I can answer my manager's many questions about what it can do for us, as well as where the integration points may be. Jira integration may be on the horizon as well. As Radu mentioned in an email, inserting Ajax requests in the webhelp code to Jira could be straightforward, but I don't know enough about Jira's integration options to know if roundtrip coherence is worth it. It might just be easier to add a few more workflow options in webhelp by adding support for one or two new comment states and be done with it. I also need to record usage analytics as well, so I'll be looking at the best places to add that instrumentation.

I was thinking of forking this thread when I got LDAP working, but I ranked continuity over subject matter. You can always hack your MySQL comments table to do so after the fact. :wink:
sorin_ristache
Posts: 4141
Joined: Fri Mar 28, 2003 2:12 pm

Re: Using LDAP for WebHelp with Feedback authentication

Post by sorin_ristache »

kirkilj wrote:I also need to record usage analytics as well, so I'll be looking at the best places to add that instrumentation.
For example Google Analytics code can be added as custom JavaScript code in the template called "create-toc-common-file" in the file:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl

You can look at the parameter WEBHELP_BODY_SCRIPT as an example.
Regards,
Sorin

<oXygen/> XML Editor Support
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

Thanks for the clues on where to make such changes in the transform, but rather than use Google Analytics, I'll just write a function to log the events we're interested in to a new database table so that I can catch the desired transactions explicitly. Many of the Webhelp PHP URLs require analysis of the query params and values to figure out the nature of the event. I can also capture username and other internal information by using an internal logging method. With the LDAP-provided info, I can add the department number and title of the user so we can do analysis by business group and user's role in the company. This would tell us who's using it and how. We'll just use Excel's Power Query addon for MySQL or something similar for custom analysis.
kirkilj
Posts: 110
Joined: Fri May 14, 2010 12:14 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by kirkilj »

I just looked at our LDAP schema and there are other interesting attributes, particularly the users' location attributes that would indicate which country and office they work from. If it turns out that documentation editors in India are the primary users and we're not getting much feedback from our engineers in China, then it could be actionable information.
sorin_ristache
Posts: 4141
Joined: Fri Mar 28, 2003 2:12 pm

Re: Using LDAP for WebHelp with Feedback authentication

Post by sorin_ristache »

kirkilj wrote:Thanks for the clues on where to make such changes in the transform, but rather than use Google Analytics, I'll just write a function to log the events we're interested in to a new database table so that I can catch the desired transactions explicitly. Many of the Webhelp PHP URLs require analysis of the query params and values to figure out the nature of the event.
Maybe a new PHP function that will add a table row for each event and that you can call for each event that you want logged to that table?
Regards,
Sorin

<oXygen/> XML Editor Support
Radu
Posts: 8992
Joined: Fri Jul 09, 2004 5:18 pm

Re: Using LDAP for WebHelp with Feedback authentication

Post by Radu »

Hi,

Just to update this thread, the WebHelp output obtained with Oxygen 17.0 should have LDAP authentication support.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
bobrumsby
Posts: 1
Joined: Fri Jan 13, 2017 4:35 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by bobrumsby »

I need to provide separate logins to different users of my webhelp system. Maybe LDAP authentication can solve this problem? I'm not sure how to go about doing this, not having worked with LDAP before. Can you summarize what needs to be done?
bogdan_cercelaru
Posts: 222
Joined: Tue Jul 01, 2014 11:48 am

Re: Using LDAP for WebHelp with Feedback authentication

Post by bogdan_cercelaru »

Hello,

LDAP authentication can be a solution if you already have a LDAP server used in your company for "single sign-on". In case you don't have a LDAP server, you have to configure one in order to be used with the WebHelp system.
If you don't want to create a LDAP server, every user that needs to access the WebHelp system have to create an account using the "Sign Up" button available at the bottom of the WebHelp system.

Regards,
Bogdan
Bogdan Cercelaru
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com
Post Reply