34 Managing Users on the Management System
WebCenter Sites provides authentication functionality through the USER
tags, user profile management through the DIR
tags, and enforces security on database tables and rendered pages through access control lists (ACLs). You use these user management and security mechanisms to manage users and control user access on your distribution system and on your WebCenter Sites development and management systems.
Topics:
About the Directory Services API
The Directory Services API enables your WebCenter Sites system to connect to directory servers that contain authentication information, user information, and so on. WebCenter Sites delivers three directory services plug-ins, one of which is installed along with your WebCenter Sites systems.
-
The WebCenter Sites directory services plug-in, which uses the native WebCenter Sites user management tables; that is, the
SystemUsers
andSystemUserAttrs
tables. -
The LDAP plug-in, which supports any JNDI server.
-
The NT plug-in, which retrieves user credentials and login name from the NT directory but gets all other user information from the
SystemUserAttrs
table.
The plug-in is installed during the installation of your WebCenter Sites systems and it is configured by setting properties in the wcs_properties.json
file. For information about configuring your user management setup, see Understanding the LDAP Plug-In in Administering Oracle WebCenter
Sites.
This section includes the following topics:
Entries
A directory entry is a named object with assigned attributes, in particular, user and group type entries:
-
A user type object has a distinguished name and a set of attributes such as commonname, user name, password and email.
-
A group type object, similar to a WebCenter Sites ACL, also has a distinguished name and a set of attributes.
Names reflect the hierarchy in which they are associated. To ensure portability across directory implementations, names should be treated as opaque strings.
Hierarchies
Some directory databases organize entries using a hierarchical structure. With WebCenter Sites directory services API, an entry's attributes and its place in the hierarchy are distinct. As a result, retrieving an entry's attributes does not yield information about its children.
Support for hierarchies depends on the underlying directory implementation; for example, LDAP directories support a hierarchical structure, while WebCenter Sites native directory database does not support a hierarchical structure. To ensure portability across directory implementations, your code should not assume support for hierarchical data.
Note:
Group hierarchies do not affect internal WebCenter Sites permissions.
Groups
WebCenter Sites directory services API does not enforce referential integrity. When you delete a user with the directory tags first remove the user from the groups that he is associated with. This ensure that group memberships are also deleted.
When a member is added to a group, the JNDI implementation always builds a fully distinguished name for the value of the uniquemember
attribute, regardless of the name passed into the addmember
tag.
Directory Services Tags
You can use the DIR
tag family, as shown in the following table, with both XML and JSP versions to invoke the Directory Services API.
Table 34-1 Directory Services Tags
Tag | Description |
---|---|
|
Adds attributes to an existing entry (which can be either a user or a group). |
|
Adds a member to a group (usually a user). |
|
Retrieves the child entries for a specified parent in a list variable. |
|
Creates a directory entry. |
|
Deletes a directory entry. |
|
Gets the attribute values for a specified entry in a list variable. |
|
Lists the members of a specified group. |
|
Lists all the groups that an entry (either a group or a user) belongs to. |
|
Returns a list of all the users in the directory. |
|
Deletes an attribute value for an entry. |
|
Removes an entry from a group. |
|
Replaces the value of an attribute for an entry (either a user or a group). |
|
Searches the directory for entries who match the specified search criteria. |
Regardless of whether the directory is implemented with LDAP or WebCenter Sites only, the code you write with the DIR
tags is very similar.
See the Tag Reference for Oracle WebCenter Sites Reference and Directory Services Code Samples.
Directory Operations
Some WebCenter Sites Directory Services tags write information to the database. If your database administrators will be handling all of the website's write operations, such as adding user information to the database, restrict use of the directory tags to read-only operations. This policy avoids synchronization issues with third-party directory administration tools.
The read-only operations are presented in this section. These operations are performed using the credentials and read permissions of the currently authenticated user.
This section includes the following topics:
Searching
Due to limitations in some directory servers, search is not allowed from the top organizational level. To avoid portability issues, always specify the context attribute on the DIR.SEARCH
tag.
Looking Up a User
Looking up a user generally involves two steps:
- Call
DIR.SEARCH
on theuserid
to get the entry name. - Call
DIR.GETATTRS
to get the attributes of the user in question.
Listing Users
It is recommended that you use one of the following three methods to list users:
-
For small user databases, use the
DIR.LISTUSERS
tag, which recursively lists all users under thepeopleParent
property. This tag is inefficient on large user databases. -
For large user databases, use the
DIR.CHILDREN
tag to walk the hierarchy. TheDIR.CHILDREN
tag is best used for group types and not for user types. -
For user databases with a flat hierarchy, narrow results with a search.
Directory Services Code Samples
The following JSP code sample illustrates some possible directory operations:
<% String sMainTestUserName = "user name"; String sMainTestUserPW="password"; String sPeopleParent = ics.GetProperty("peopleparent", "dir.ini", true); String sGroupParent = ics.GetProperty("groupparent", "dir.ini", true); String sUsername = ics.GetProperty("username", "dir.ini", true); String sCommonName = ics.GetProperty("cn", "dir.ini", true); IList mylist; %> <user:su username='<%=sMainTestUserName%>' password='<%=sMainTestUserPW%>'> <H2>List All Users</H2> <ics:clearerrno/> <dir:listusers list='mylist'/> <br> <b>dir:listusers errno: <ics:getvar name='errno'/></b> <ics:listloop listname='mylist'> <br><ics:listget listname='mylist' fieldname='NAME'/> </ics:listloop> <H2>Look Up the ContentServer User by Username</H2> <ics:clearerrno/> <dir:search list='mylist' context='<%=sPeopleParent%>'> <dir:argument name='<%=sUsername%>' value='ContentServer'/> </dir:search> <br><b>dir:search errno: <ics:getvar name='errno'/></b> <% mylist = ics.GetList("mylist"); if(mylist.numRows() != 1) { out.print("<br>Error finding entry."); } mylist.moveTo(1); ics.SetVar("ContentServerDn", mylist.getValue("NAME")); %> <H2>Show ContentServer Attributes</H2> <ics:clearerrno/> <dir:getattrs list='mylist' name='<%=ics.GetVar("ContentServerDn")%>'/> <br><b>dir:getattrs errno: <ics:getvar name='errno'/></b> <ics:listloop listname='mylist'> <br> <ics:listget listname='mylist' fieldname='NAME'/>= <ics:listget listname='mylist' fieldname='VALUE'/> </ics:listloop> <H2>Show Group Memberships for ContentServer</H2> <ics:clearerrno/> <dir:groupmemberships name='<%=ics.GetVar("ContentServerDn")%>' list='mylist'/> <br><b>dir:groupmemberships errno: <ics:getvar name='errno'/></b> <ics:listloop listname='mylist'> <br> <ics:listget listname='mylist' fieldname='NAME'/> </ics:listloop> <H2>Lookup the SiteGod Group by CommonName</H2> <ics:clearerrno/> <dir:search list='mylist' context='<%=sGroupParent%>'> <dir:argument name='<%=sCommonName%>' value='SiteGod'/> </dir:search> <br><b>dir:search errno: <ics:getvar name='errno'/></b> <% mylist = ics.GetList("mylist"); if(mylist.numRows() != 1) { out.print("<br>Error finding entry."); } mylist.moveTo(1); ics.SetVar("SiteGodDn", mylist.getValue("NAME")); %> <H2>Show SiteGod Attributes</H2> <ics:clearerrno/> <dir:getattrs list='mylist' name='<%=ics.GetVar("SiteGodDn")%>'/> <br> <b>dir:getattrs errno: <ics:getvar name='errno'/></b> <ics:listloop listname='mylist'> <br> <ics:listget listname='mylist' fieldname='NAME'/>= <ics:listget listname='mylist' fieldname='VALUE'/> </ics:listloop> <H2>Show SiteGod Group Members</H2> <ics:clearerrno/> <dir:groupmembers name='<%=ics.GetVar("SiteGodDn")%>' list='mylist2'/> <br> <b>dir:groupmembers errno: <ics:getvar name='errno'/></b> <ics:listloop listname='mylist2'> <br> <ics:listget listname='mylist2' fieldname='NAME'/> </ics:listloop> <H2>Children of groupparent </H2> <ics:clearerrno/> <dir:children name='<%=sGroupParent%>' list='mylist'/> <br> <b>dir:children errno: <ics:getvar name='errno'/></b> <ics:listloop listname='mylist'> <br> <ics:listget listname='mylist' fieldname='NAME'/> </ics:listloop> </user:su>
Error Handling
Any of the directory tags can cause a range of directory errors to be set. See the Tag Reference for Oracle WebCenter Sites Reference for a comprehensive list of directory services error messages.
Your directory services code should handle every one of the error codes listed for a given tag call. This is necessary to support the J2EE JNDI interface.
Directory Services Applications Troubleshooting
The first step in troubleshooting directory services applications is to check the error log (in the WebCenter Sites log file).
You enable directory services logging by setting the log.filterLevel
property (found in the logging.ini
property file). There are seven levels of error messages that you can view:
-
fatal: Logs fatal level messages.
-
severe: Logs severe and fatal level messages.
-
error: Logs error and fatal level messages.
-
warning: Logs warning and fatal level messages.
-
info: Logs warning, error, severe, and fatal level messages.
-
trace: Logs trace messages.
-
detail: Logs all types of messages.
During troubleshooting, trace
is the most verbose setting, and as a result, has the highest performance impact.
Directory services log entries use the following format:
[<timestamp>][Directory-<severity>-<errno>] [<class>:<method>][<message>][<session id>]
For example:
[Jan 17, 2002 1:49:44 PM][Directory-T] [BaseFactory:instantiateImplementation(ICS,String,Class[], Object[])][Instantiating:com.openmarket.directory.common.Factory] [PEccxyF1Ueh7zYvjNgg4D6bqZzf0llfWMaiBimIN9H1Z9KomDcPy]
The previous message is a trace (T), and thus has no associated errno
value.
See Logging and Debugging Errors.
A common problem for LDAP implementations is incorrectly specified permissions on the directory server. If the error log indicates a permission problem, ensure that the authenticated user has permissions to execute the requested operation by checking the permission settings on the directory server. Try logging into the directory server directly (outside of WebCenter Sites) and performing the same action to ensure that permissions are correctly set. After checking the log and permissions, you can often resolve a configuration error by examining the property files.
See the Property Files Reference for Oracle WebCenter Sites.
Working with Custom User Manager
You can access user information stored in the database tables or in LDAP (or other Directory protocols) using the implementation available through the CustomUserManager class.
Topics:
What is Custom User Manager?
For those who want greater flexibility than that provided by the WebCenter Sites out of the box authentication mechanism, Oracle also provides implementations to access user information stored in the database tables or in LDAP (or other Directory protocols). These implementations are available through the CustomUserManager class.
The CustomUserManager class enables clients to implement a connection to an arbitrary user repository by extending the existing architecture. This connection is used to authenticate and authorize WebCenter Sites users. It provides read-only access to the user directory. The write-access is not required because all user maintenance operations are performed in a central directory system. Those who implement UserDirectory are responsible for correctly mapping the user attributes of the users in the arbitrary user repository to those that WebCenter Sites uses. For example, ACLs and Roles per site.
Interfaces to Extend a Site Architecture
-
oracle.fatwire.sites.directory.custom.UserDirectory
: Clients implement this interface. WebCenter Sites invokes the client’s implementation to authenticate the user and obtain user roles and ACLs. -
oracle.fatwire.sites.directory.custom.UserFactory
andoracle.fatwire.sites.directory.custom.UserFactory.Builder
: WebCenter Sites provides an implementation of these interfaces as a container to populate user information.
See Java API Reference for Oracle WebCenter Sites.
Webcenter Sites doesn’t cache any user information or roles from the arbitrary user repository. Clients can customize their implementation to handle caching of user information and roles. Clients can create new roles in WebCenter Sites after setting this property in the wcs_properties.json
under the config
directory: xcelerate.rolemanagerclass=com.openmarket.xcelerate.roles.RoleManager
These roles can’t be updated.
All property changes are retained when WebCenter Sites is upgraded. However, clients need to back up any classes used for the UserDirectory implementation.
Logger for Custom User Manager
A new logger oracle.wcsites.directory.custom
is added for this Custom User Management customization hook. This hook provides clients with the flexibility to customize or define their own authentication. Use log level TRACE. Legacy code continues using old loggers (dirLogger/ics.LogMsg()
and logging.ini
, com.fatwire.logging.cs.auth
, com.fatwire.logging.cs.session
etc.).
Sample Implementation of Custom User Manager
To help you develop a good understanding of Custom User Manager, a sample implementation is provided in the WebCenter Sites repository.
The sample code is located under <ORACLE_HOME>/wcsites/webcentersites/sites-home/bootstrap/samples/CustomUserManager
.
This implementation consists of the following files:
-
user-repository.json
: This json file stores the user details such as username, encrypted password, roles, and ACLs. Ensure that the userId contains the proper parent string as it was defined during installation. See the peopleparent property in thewcs_properties.json
file for the value of the parent string. -
FileUserRepository.java
: It is a backend store for user information. It reads the json file and populates the SampleUser objects in the memory. You need to restart the server to reflect any changes touser-repository.json
. -
SampleUser.java
: Holds the user information in the memory. -
SampleUserRepository.java
: This class implements theoracle.fatwire.sites.directory.custom.UserDirectory
interface. WebCenter Sites invokes this implementation when it needs to authenticate a user, get the user roles, list users matching criteria and so on.
The sample implementation project is easy to compile with WebCenter Sites 12.2.1.2.0 and above. To understand the project setup, see ReadMe.txt under <ORACLE_HOME>/wcsites/webcentersites/sites-home/bootstrap/samples/CustomUserManager
.
Integrating the Sample Implementation with WebCenter Sites
All you need to do to integrate the sample implementation of Custom User Manager is change and add a few properties to the wcs_properties.json
file, compile the project, and update the application server class path.
What You May Need to Know About the Custom User Manager
The UserDirectory interface provides a read-only access to the user directory because all user maintenance operations are performed in a central directory system.
-
As a result, the following operations may not work or show erroneous success messages:
-
The <DIR> tags allow you to perform functions such as creating and updating user profiles and adding user roles. When these tags are invoked, WebCenter Sites logs the operation not supported exception and sets the error number -15004 in the ics scope.
-
WebCenter Sites UI uses these tags in many places. UI forms have not been changed to reflect the error message on the interface pages. As a result, updating a user profile (or other such operations) may erroneously indicate the operation was successful but in reality nothing changes.
-
-
REST Groups security must work as before. When accessing the REST resources make sure that the users have been assigned to proper groups.
Controlling User Access
WebCenter Sites manages users through access control lists (ACLs). By using ACLs, you can restrict access to tables in the WebCenter Sites database and the rendered pages served on your sites by WebCenter Sites. You must associate registered users with one or more ACLs for a site to which users log in with user names and passwords.
When a user first visits a site, WebCenter Sites creates a session and implicitly logs in the user as the standard default user, DefaultReader
. The identity of a user is updated (and any associated ACLs go into effect) when a USER.LOGIN
command is used and the user is authenticated against a password.
See these topics:
ACL Tags
WebCenter Sites provides a set of access control list tags (both XML and JSP versions) that you can use to create ACLs. You can use either the WebCenter Sites interface on the management system or the WebCenter Sites ACL tags to create the ACLs that you need for your user accounts on your management system. The following table lists the ACL tags:
Table 34-2 ACL Tags
Tag | Description |
---|---|
|
Creates an ACL. |
|
Deletes an ACL. |
|
Gathers fields into an ACL. |
|
Copies a field from an ACL. |
|
Retrieves a list of ACLs. |
|
Loads an ACL. |
|
Saves an ACL. |
|
Scatters a field from an ACL. |
|
Sets a field in an ACL. |
For more information:
-
ACL tags: See the Tag Reference for Oracle WebCenter Sites Reference.
-
ACLs in general: See Administering Oracle WebCenter Sites.
USER Tags
WebCenter Sites also provides the USER
tags (both XML and JSP versions) described in the following table. You use these tags on pages that log users in and out.
Table 34-3 User Tags
Tag | Description |
---|---|
USER.LOGIN
|
Logs a user in. |
USER.LOGOUT
|
Logs a user out. |
USER.SU
|
Logs the user in as a specific user to perform an operation such as creating an account or edit a user profile. |
WebCenter Sites and Encryption
WebCenter Sites includes a default key for encrypting passwords and other sensitive information. You can specify your own encryption key by using the Utilities
class encryptString
method. See the Java API Reference for Oracle
WebCenter Sites for information about Java methods that deal with encryption.
WebCenter Sites also supports Secure Sockets Layer (SSL), which allows encryption of information going to and from your web servers. See Implementing Security in Administering Oracle WebCenter Sites.