| Oracle® Fusion Middleware System Administrator's Guide for Content Server 11g Release 1 (11.1.1) E10792-01 |
|
 Previous |
 Next |
Home > System Administrator' > Need to Know Component > Using the Need To Know Comp...
| Oracle® Fusion Middleware System Administrator's Guide for Content Server 11g Release 1 (11.1.1) E10792-01 |
|
Previous |
Next |
Home > System Administrator' > Need to Know Component > Using the Need To Know Comp...
This section covers the following topics:
The Need to Know component provides additional security configuration support focused on the following areas:
Content Security: Changing user access to content items.
Search Results: Changing the display of search results.
Hit List Roles: Changing user credentials for query and check-in pages.
WHERE Clause Calculation: Changing use of the WHERE clause in searches.
Content Metadata Security: Changing the behavior of metadata changes for content items.
Standard security uses security roles, groups, and accounts to determine if a user has the appropriate privilege level to access a content item. The Need to Know component enables you to customize the process of determining user privilege. You can use the Need to Know component interface to set configuration fields and create Idoc Script to specify Read, Write, and Delete privilege levels. The Idoc Script can also contain user and content metadata values.
The Need to Know component computes content security using the following process:
A user clicks a link to view content information.
If the user has the “admin” role, standard security is used and the user can view the content.
If the security group of the content item is not a Need to Know authorization group, then standard security is used to evaluate the user's Read request.
If Need to Know security is not enabled at the Read privilege level, then standard security is used to evaluate the user's Read request.
If Need to Know security is not limited at the Read privilege level, and the user has standard security access to the content item, the user is given access to the content.
The Need to Know security Idoc Script (in this case the Read security script) is evaluated.
The Need to Know access flag (in this case, isNTKReadAccess) is evaluated to determine if the user has access to the content. Access is allowed or denied based on the Need to Know access flag.
The Need to Know component also enables you to test security configuration scripts for each access level: Read, Write, and Delete. For a test you can specify a user and a content ID, and you have the option of specifying roles and accounts. These attributes are used in the test instead of the user's actual attributes. For example, you could test Idoc Script using an external user whose attributes may not be accessible. After the test is run, the component reports on whether the user has access to the content item, whether Need to Know security was used, and if Need to Know security was not used then the reason why.
For information on using the Need to Know component interface to configure content security, see the "NTK Configuration Information Page" and the "Content Security Configuration Information Page". For samples of Idoc Script that can configure content security, see "Security Customization Samples".
The following Idoc Script functions can be used in the Script fields to determine content security. For additional information on Idoc Script refer to the Idoc Script Reference Guidel.
| Idoc Script Function | Description |
|---|---|
| allStrIntersect | Takes two required comma-delimited strings and one optional Boolean flag as parameters. If all values in the second string occur in the first string, the function returns true. If the optional parameter is set to true and the second value is an empty string, the function returns true. By default, the optional parameter is false. The comparison of values in the comma-delimited strings are not case sensitive. |
| includeNTKDeleteSecurityScript | Evaluates the Delete security script and makes the isNTKDeleteAccess variable available for use in the Read or Write security scripts. If this function is used in the Delete security script, it is ignored. |
| includeNTKReadSecurityScript | Evaluates the Read security script and makes the isNTKReadAccess variable available for use in the Write or Delete security scripts. If this function is used in the Read security script, it is ignored. |
| includeNTKWriteSecurityScript | Evaluates the Write security script and makes the isNTKWriteAccess variable available for use in the Read or Delete security scripts. If this function is used in the Write security script, it is ignored. |
| isDisclosureQuery | Evaluates the query for the disclosure field (if specified) and returns true or false. An optional parameter can be specified to determine if the function should return true or false if the disclosure query is empty. If the disclosure field has not been specified or does not exist, this function always returns false. |
| isMetaChange | This variable is set if the content security call involves a content update or a check in. |
| isStrIntersect | Takes two required comma-delimited strings and one optional Boolean flag as parameters. If at least one value in the second string occurs in the first string, the function returns true. If the optional parameter is set to true and the second value is an empty string, the function returns true. By default, the optional parameter is false. The comparison of values in the comma-delimited strings are not case sensitive. |
| stdSecurityCheck | Checks standard security for the current access level. For example, if the function is in the Read security script, it checks security at the Read access level. |
The Need to Know component enables you to customize the presentation of the search results that are returned from a search query. Two configuration values can be set using the NTK interface: Hidden Fields, and Script.
The Hidden Fields value is a list of fields that can be hidden from view on the Search Results page. The values are set to empty strings. To hide the fields, the field hideFields must be set in the component search results Idoc Script.
Idoc Script controls the presentation of the search results. Idoc Script is evaluated for each row in the search results. A number of fields can be set in script to alter the presentation of search results. To see the list of fields and how to use the Need to Know component interface to customize script for search results presentation, see "Search Results Configuration Information Page".
The Need to Know component uses the securityCheck Idoc Script function to determine search results presentation. The securityCheck function checks the security against the current content item (standard security or Need to Know security), depending on the configuration values. The function has an option parameter to determine what access level to check:
1 = Read
2 = Write
4 = Delete
8 = Admin
If no parameter is used with securityCheck, by default it checks the Read access level.
For examples of Idoc Script that can alter search results presentation, see "Security Customization Samples".
Hit list roles enable you to change user credentials for using content Search, Content Check In, and Update pages. Using the User Admin applet, you can add a hit list role with any name you wish. You don't assign the role to a user; when the role is enabled it is automatically added to a user's attributes when doing a search, check in, or update. When creating a hit list role, you need to give Read access to all the security groups that you specify in the SpecialAuthGroups configuration entry. If you want these security groups to be listed on the Content Check In page or Update page, you also need to add Write access to the hit list role.
Using the Need to Know component Hit List Roles Configuration Information page, you can implement hit list roles in two forms: Query and Update. A hit list role used in a query is applied to content searches. A hit list role used in an update is applied to content check-ins and updates.
For additional information about how to use hit list roles, see "NTK Configuration Information Page" and "Hit List Roles Configuration Information Page". For samples of using hit list roles, see "Security Customization Samples".
The Need to Know component provides two filters that enable you to customize the query WHERE clause that is used to retrieve search results:
preDetermineWhereClause: Overrides the entire WHERE clause.
postDetermineWhereClause: Appends to the standard security WHERE clause.
The code for these filters is located in the NTKFilter Java class. For samples of how these filters work, see "Security Customization Samples".
The Need to Know component provides a filter called checkMetaChangeSecurity that enables you to alter the behavior of metadata changes when a content item is checked in or updated.
The code for this filter is located in the NTKFilter Java class. For an example of how the filter works, see "Security Customization Samples".
The Disclosure Query Security applet is used to define a query for a particular content item during check-in.To access the applet, click the Update button next to the DocDisclosureQuery field on the Content Check In Form page.
| Element | Description |
|---|---|
| Field field | Select a user attribute field to be specified in the query. This list includes User Locale, User Name, User Role, and all of your custom user attribute fields. |
| Operator field | Select an operator to apply to the Field and Value. The following operators are used for all fields except User Role:
Is: The value in the specified Field matches the specified Value. Is Not: The value in the specified Field does not match the specified Value. Begins With: The value in the specified Field starts with the specified Value. Contains: The value in the specified Field contains the specified Value. The User Role field has only one operator, Has Member, and displays a drop-down list of roles in the Value field. |
| Value field | Enter the value to be specified in the query.
|
| Add button | Enters the query specified by the Field, Operator, and Value fields into the Query Expression text box. Each click of the Add button appends the current settings to the query as an AND clause. |
| Update button | Updates a selected query clause with the parameters specified in the Field, Operator, and Value fields |
| Merge button | Creates an OR clause (inserts a pipe character) for the selected query clause. This button is enabled under the following conditions:
|
| Query Expression | Displays each clause of the query as a single line. |
| Delete button | Deletes the selected query clause. |
| Append button | Appends the Query Expression to any existing query in the DocDisclosureQuery field on the Content Check In Form page. |
| Replace button | Replaces any existing query in the DocDisclosureQuery field on the Content Check In Form page with the Query Expression. |
| Cancel button | Closes the Disclosure Query Security applet without applying any query changes. |
The Disclosure Security Query applet creates queries with the correct Idoc Script syntax, but you can also enter your own queries directly in the DocDisclosureQuery field. The following Idoc Script syntax is used in disclosure queries:
|
Note: You can learn how to correctly format query clauses for direct entry in the DocDisclosureQuery field by experimenting with the Disclosure Query Security Applet (page 3-6) |
The like operator matches substrings and wildcard strings. Enclose all strings in single quotes.
Use wildcard strings to match variable characters and options. Wildcard strings use the syntax
For example, the following code would match “MyClient”, “3rd Quarter MyClient Report”, “MyClient Visit”, “Meeting with MyClient”, and “1996 Reports”. This string would not match “My Client”, “All 1996 Reports”, or “1996 Report”.
dDocName like '*MyClient*|199? Reports'
Query clauses can be joined by and, or, and not Boolean operators.
The Boolean operators must be lower case.
Each clause must be in parentheses. For example:
(uRoles like '*:contributor:*') and (uUserLocale like 'hq')
The variable UserName is the name of the user who is currently logged in. For example, the following code would grant privileges only to the users jgreen or hbrown.
UserName like 'jgreen|hbrown'
The variable stdSecurity specifies the standard security model; it is mapped to the stdSecurityCheck Idoc Script function. This variable can be used in Boolean combination with other query clauses to refine access (using the and operator) or expand access (using the or operator). For example, the following code would grant access to the document if the user would normally be able to access the document or they are jgreen or hbrown.
stdSecurity or UserName like 'jgreen|hbrown'
When specifying user attribute fields in a query, use the format uFieldName. For example:
uMyUserField like 'Value'
User roles require a special form because the UserRoles Idoc Script function returns all the roles for the current user in comma delimited form. (In this example, a uRoles shortcut has been defined for this function.) For example, the uRoles value could be:
role1,role2,...,role10
Therefore, to specify a query string that includes the value role1, wildcards must be included so that the query will recognize the value regardless of its position in the role list. For example:
uRoles like '*role1*'
However, this query string would also grant security access to a user with the role role10, which might not be a role you want to include. To limit the uRoles value to only those roles specified in the query, you need to use the DelimitedUserRoles function and syntax, which includes single quotes and colons on each side of the role value as follows:
uRoles like '*:role1:*'
To match either role1 or role2, use this syntax:
uRoles like '*:role1:*|*:role2:*'
Use the following procedure to define a query for an individual content item:
Display the Content Check In Form page (for a new content item) or the Info Update Form page (for an existing content item).
Click the Update button next to the DocDisclosureQuery field (the name of this field will be whatever you named it during installation).
The Disclosure Query Security Applet is displayed.
Choose a Field, an Operator, and a Value to create a query clause.
Click Add.
The query clause is added to the Query Expression text box.
Continue building the query:
To add another query clause with an and operator, enter the values and click Add.
To change an existing query clause, enter the new values, select the query line you want to change, and click Update.
To create an or clause, enter the new values, select the query line you want to change, and click Merge.
To delete a query clause, select the query line and click Delete.
Enter the query expression in the DocDisclosureQuery field.
To replace the existing query in the DocDisclosureQuery field with the query expression in the applet, click Replace.
To append the query expression in the applet to the existing query in the DocDisclosureQuery field, click Append.
The Disclosure Query Security applet converts the query clauses to the appropriate syntax for the query and enters the query in the DocDisclosureQuery field on the Content Check In Form or Info Update Form page.
|
Note: You can learn how to correctly format query clauses for direct entry in the DocDisclosureQuery field by experimenting with the Disclosure Query Security applet. |
After filling out the rest of the fields, click Check In or Update.
The disclosure query is validated, and if the query is ill-formed, an error message tells you the specific problem with the query.
