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:
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 and SystemUserAttrs 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:
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.
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.
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.
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 45-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 and Directory Services Code Samples.
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:
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 generally involves two steps:
DIR.SEARCH on the userid to get the entry name.DIR.GETATTRS to get the attributes of the user in question.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 the peopleParent property. This tag is inefficient on large user databases.
For large user databases, use the DIR.CHILDREN tag to walk the hierarchy. The DIR.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.
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>
Any of the directory tags can cause a range of directory errors to be set. See the Tag Reference for Oracle WebCenter Sites 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.
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.
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:
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 and oracle.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.).
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 the wcs_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 to user-repository.json.
SampleUser.java: Holds the user information in the memory.
SampleUserRepository.java: This class implements the oracle.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.
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.
The UserDirectory interface provides a read-only access to the user directory because all user maintenance operations are performed in a central directory system.
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.
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:
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 45-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.
ACLs in general: See Administering Oracle WebCenter Sites.
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 45-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 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.