Saturday, October 9, 2010

UCM Security - Need To Know component - sample step by step implementation

Guys,

Recently I came across a requirement which had to restrict the standard UCM Content Server security for few documents. Luckily we found there was already a component provided by Oracle just for that purpose (either to extend or restrict the standard security) named Need To Know.

This component can be downloaded from the Oracle website. Although there was a complete sixty page document for this component, it was no cakewalk for me to get it working. I tried to google but no luck, not much has been written about this component in the internet. So, I thought of writing one and sharing my experience.

The Need to Know component supports customization for Content Security, Search Results, Hit list roles, Content metadata security, and WHERE clause calculation. I will touch upon the Content Security part in this article.

The Need to Know component works on Security Group.

Lets get started with a sample requirement.
Consider a sample UCM application which has three security groups namely "SECGRP1", "SECGRP2" and "CONF_SECGRP". Accounts are enabled (about which we don't bother for this requirement). The requirement is to restrict access to some of the documents belonging to the Security Group "CONF_SECGRP". Even if user "A" has read permission on "CONF_SECGRP" as per standard security, we need to restrict it based upon some query given during check-in or update of the document.

Step 1 - Installation : Install the "Need to Know"(NTK) Component using either Component Manager or Component Wizard. Enable it.

Step 2 - Configuration :
a) Open the Admin Server Page and click the General Configuration link.
b) Under the "Additional Configuration Variables" heading, add the below
entry at the end of the text area.
SpecialAuthGroups=conf_secgrp
Only the security groups specified in the SpecialAuthGroups variable will use
the NTK component. Other security groups will have standard security applied.
c) Add a new metadata field that will be used for content-item level queries
(remember our requirement - restrict users based upon some value).
Add the new metadata field using the Configuration Manager. Use any field
name you wish. Here we name it as "DocDisclosureQuery". The field type
should be "memo". After adding the field, click Update Database Design.
d) Add a hit list role using the User Admin Applet. Create two roles "hitlist-r"
and "hitlist". Give read access to "CONF_SECGRP" for the role hitlist-r and
write access to "CONF_SECGRP" for the role hitlist. Do not assign this role
to any user.
e) Restart the content server.

Step 3 - NTK Administration : In the administration tab, you must be able to see a link for NTK component administration - NTK Configuration Information. Click on that link. NTK Administration screen looks as below.



Now we need to configure the new metadata field and hit list roles that we created in the last step.

a) Configuring the DocDisclosure field :

Click Edit button on the top right corner and select "Content Security Configuration Information" link. Scroll to the bottom of the page, in the
"Other Options" section, select the new metadata field that was created as the Disclosure Field and click Update.


b) Configuring the Hit List Role :

Click Edit button on the top right corner and select "Hit List Roles Configuration Information" link. Select "hitlist-r" role as Query Role and "hitlist" role as Update Role and click Update.



c) Limiting Access :

In the "Content Security Configuration Information" page, under the "Read Options" section, select "Yes" for both "Use Security" and "Limit Access". Since our requirement is to limit read access, we did the above configuration only in the "Read Options" section.

In the "Script" text area, write the below script which will determine the read access, based upon the content-item level query given during check-in or update of the document.

<$if isDisclosureQuery(xDocDisclosureQuery)$>
<$isNTKReadAccess=1$>
<$endif$>

Click Update button.


Now the NTK Configuration Information Page should appear as below reflecting the configurations done till now.



Step 4 : Click the "New Check In" link in the top menu and in the Content Check In form now a new metadata field for DocDisclosureQuery will appear along with a "update" button adjacent besides it.



The DocDisclosureQuery applet will be loaded by clicking the update button adjacent to the DocDisclosureQuery field. This applet will contain all the user attributes which can be used to form a content item level query that determines the access on top of standard security.

Step 5 - Check-in a document :
We are all set to check-in a document, specify a content level query and check whether all this works.

Click "New Check In" link in the menu.
1) Give the title of the document.
2) Select the Security Group - the one that is specified in SpecialAuthGroups.
3) Browse the document.
4) Enter all other metadata as per your application.

5) Content Item Level Query :
Click the Update button adjacent to the DocDisclosureQuery field. In the applet
select the "Field" as "Username", "Operator" as "Is" and Value as should be allowed to view this document>. Click Add button. The query
"Username is selvam" appears in the "Query Expression" text area.
You can form complex queries by making use of different user attributes and the
Add, Update and Merge buttons in the applet. For our example we will stick with
one user attrubute to form the query - Username.



Click Append button. The query should now appear in the DocDisclosureQuery field text area as below. You can even directly edit the query in the DocDisclosureQuery field text area.



Click "Check In". The document is successfully checked in now.

Step 6 - Testing the NTK security :
Login using user "selvam" and try to access the above checked-in document. This user must be able to view the content information page of the document.

Login using any other user who have read access to "CONF_SECGRP" other than "selvam" and try to access the document. "Insufficient Access Privilege" error will be thrown.

This is a very simple example of extending standard UCM security using NTK component.

There is one other thing to be noted here. If in your application, the virtual folders belong to the security group specified in the SpecialAuthGroups, and if the Read Access is limited using NTK component, then users won't be able to view the folders. There will be number of ways to overcome this problem. I did it the following way. There is a filter called "checkExtendedSecurityModelDocAccess". NTK makes use of this filter to extend the standard UCM security. The actual class implementing this filter is "NTKFilter" in the NTK component. So you can override this filter in such a way that the NTK security is not applied for the COLLECTION related services.

Hope this post serves as a good starting point to extend Standard UCM security using NTK component.

Good day..