6 Using Oracle Calendar with Directory Servers

The Oracle Calendar server can share information with other back end infrastructure components such as e-mail servers through the use of Oracle Internet Directory. Benefits include centralized user administration and consistency of information across multiple applications.

This chapter contains an overview of how the Oracle Calendar server interacts with Oracle Internet Directory, and a discussion of some more specific configuration issues. It also contains information about using third-party directory servers when using the calendar server in a standalone installation.

This chapter contains the following sections:

About Directory Servers
Granting Directory Server Access to Administrators
Using LDAP Groups and Distribution Lists
Specifying Fail Over Host for the Directory Server
About the Global Address List (GAL)
About the Common Address Book (CAB)
Securing Connections to the Directory Server
Changing the Attribute Used for Single Sign-On Login
When Does the Calendar Server Bind to the Directory Server?

About Directory Servers

Directory servers store information about users, and make this information available to various other services, such as e-mail or calendar applications. Directory servers like Oracle Internet Directory centralize user information; if an administrator must add or change user accounts, the task only needs to be done in one place. At the same time, user information is always kept consistent between all the applications that use the directory server; your user profile in your e-mail client, for example, will be the same as what you see in your calendar client.

Oracle Calendar server integrates with Oracle Internet Directory, which uses the Lightweight Directory Access Protocol (or LDAP) for accessing user records. Those records are kept in a hierarchical tree, in which each record is accessible through a particular path (called a Distinguished Name, or DN) that specifies the record's unique location in the tree. This is analogous to the way a file name and path specifies the location of a particular item in a file system.

What Is the Directory Schema?

Directory servers have schemas that define the information they store. These schemas consist, among other things, of objects and attributes. Objects are representations of real-world people or things, and attributes are defining characteristics of those objects. Directory servers come with preset schemas to represent people and things, providing attributes for names, addresses, phone numbers, and so on, that define a 'person'. You can also extend these schemas with new object classes and new attributes to reflect any information you care to store.

When you install Oracle Internet Directory as a part of Oracle Collaboration Suite, its infrastructure is preset with all the objects and attributes needed by the calendar server. For more information about standalone installations of the Oracle Calendar server with third-party directory servers, see "Calendar Extensions to the Directory Server Schema" in Chapter 8 of Oracle Calendar Reference Manual.

What Is the Base DN?

The calendar server requires a base DN, which is a location in the LDAP directory server under which all calendar users, resources and administrators will be located, and under which all directory searches will be performed.

This base DN is defined by the [LDAP] basedn parameter in the $ORACLE_HOME/ocal/misc/unison.ini configuration file. The location for resources in the LDAP directory relative to the calendar server base DN is specified in the unison.ini file by the [LDAP] resourcerelativedn parameter. The location for event calendar accounts are defined by [LDAP] eventcalrelativedn.

In a group search operation, it is possible to override the search base using the [LDAP]group_searchbase parameter in the $ORACLE_HOME/ocal/misc/unison.ini file. This is particularly useful if the directory group entries are stored in a central location.

For more information about server parameters, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.

Granting Directory Server Access to Administrators

Using calendar administration tools, calendar administrators have the ability to modify entries in the directory server. The level of access depends upon the access control restrictions set on your directory server.

Granting Access to Oracle Internet Directory Servers

When deployed with Oracle Collaboration Suite, the Oracle Calendar server creates two types of administrator entries: calendar application entity (CAE) and calendar instance administrator. These administrator entries are created at the time of installation, thus requiring no action from the Collaboration Suite administrator. The CAE entry is created under the subtree "cn=Application Entities, cn=Calendar, cn=Products, cn=OracleContext", where as the calendar instance administrator entry is created under "cn=Admins, cn=Calendar, cn=Products, cn=OracleContext, <subscriberdn>".

By default, the calendar instance administrator entry is not granted any explicit rights in the directory server. This entry is used for password validation only. The CAE entries have full access rights under the two calendar product containers, "cn=Calendar, cn=Products, cn=OracleContext" and "cn=Calendar, cn=Products, cn=OracleContext, <subscriber DN>". The CAE entry is also a member of the group "cn=OracleDASEditUser, cn=groups, <subscriber DN>" which grants it the right to modify user entries.

For a given instance of a calendar server, the distinguished names of the CAE and of the calendar instance administrator are defined in the [LDAP] section of that instance's unison.ini configuration file. The distinguished name of the CAE is defined by the [LDAP] applicationentitydn parameter and the distinguished name of the calendar instance administrator is defined by [LDAP] admindn.

WARNING:

The calendar application entity and calendar instance administrator should never be modified manually.

Granting Access to Other Directory Servers

In a standalone Calendar Server installation, where the calendar server is installed with a third-party LDAP directory server, there are two ways to give directory access to administrator users.

One way is to grant default access control to an LDAP group which will be specified by the [LDAP]admingroup parameter. Calendar administrators can then inherit this right by becoming a member of this group. When the SYSOP grants administrative rights to a user, he must also add him to that group. For more information about the [LDAP]admingroup parameter, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.

The second way to give non SYSOP users access to the directory server is to provide a DN and a password which will be used by the calendar server to sign in to the directory for directory administrative write operations. Set the parameter [DAS] dir_usewritednforadmin to TRUE and set parameters [LDAP] writedn and [LDAP] writednpassword. Make sure the specified DN has full write access to the calendar user, resource and event calendar information in the directory. For more details about these parameters, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.

By default, calendar administrators have full access rights for all entries under the calendar base DN. If you are familiar with your LDAP directory server's access control information, you may want to configure it to restrict the administrator permissions.

Your directory server may or may not support access control restrictions at the necessary level of granularity. Consult your directory server documentation for details on configuring access control information. You must ensure that certain permissions remain at a minimum to avoid calendar client and server errors.

Using LDAP Groups and Distribution Lists

The Calendar Server supports directory groups. In order to expose groups to calendar clients, set the [LDAP] group_enable parameter in the unison.ini file. You can also add a corresponding filter to locate these groups using the [LDAP] groupfilter parameter. Users will be able to see all groups in the directory server, and any members of these groups who are also calendar users. These groups will appear to users as Public groups. By default, all groups in the directory server located under the calendar base DN will be listed in the calendar client. However, because the calendar client will only display calendar users, if a given LDAP group has only non-calendar users as members, that group will appear as an empty group, with no members.

Using the preceding parameters, you can control which groups in the directory should be accessible to the calendar user. One way is to create a custom object class (one with the name "calendargroup" for example) and add that custom object class to the group entries that you want to expose. The parameter [LDAP]groupfilter should then be set to: "(objectClass=calendargroup)".

If you have a deployment when group entries are centrally located, it is advisable to set the parameter [LDAP]group_searchbase to the subtree where the group entries are located. This will improve the performance of the group search operation.

The calendar server also supports dynamic groups. A dynamic group is a group where the membership information is stored in an LDAP URL. When the calendar server detects that the value of a group member is an LDAP URL, the calendar server will expand the URL to establish the group membership.

To expose dynamic groups to calendar clients, add a corresponding filter to locate that type of group using the [LDAP] groupfilter parameter. Also include the attribute that contains the URI to locate the members using the [LDAP]groupmemberlistattribute parameter.

Oracle Mail distribution lists can also be exposed to users as public groups if Oracle Collaboration Suite is installed. Users will then be able to use the distribution lists to send e-mails (Oracle Connector for Outlook) or to invite a group of users (Oracle Connector for Outlook and Oracle Desktop Calendar Clients). To give users access to these groups, set the [LDAP] group_dlfilter and [LDAP] group_dlenable parameters. For more information on these server parameters, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual. For more information on distributions lists, see also Chapter 10, "Managing Calendar Groups".

Specifying Fail Over Host for the Directory Server

You can specify an alternate directory server host to be used if your main host becomes unavailable. The unison.ini [LDAP] host parameter lists the directory server hosts in preferred order; if multiple hosts are listed and the first host listed becomes unavailable, the calendar server will instead attempt to connect to the next host listed.

Because, by default, the Calendar server maintains a persistent connection to the directory server, the Calendar server will not attempt to reconnect to the primary directory server when it becomes available again. Instead it will wait for the next recycle time, specified in the parameter [DAS]dir_connectrecycletime. Once the recycle time is reached, the calendar server will terminate the current directory server connection and attempt to reestablish a connection to the primary directory server. If the primary directory server is available at that time, it will establish the connection, otherwise it will connect to the secondary directory server again.

For more information about the [LDAP] host parameter, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.

About the Global Address List (GAL)

The Global Address List, or GAL, is the interface used by Calendar clients to select users (including non-calendar users), resources and event calendars from the directory server. When a user uses the GAL, it attempts to display all the entries in the directory, regardless of whether the entry has been provisioned to Calendar. Users can filter out some entries. This filtering is performed on the client interface after all the entries have been downloaded to the client.

The Oracle Connector for Outlook works with the Calendar Server to improve the efficiency of the GAL. The server caches the GAL entries to reduce the number of requests made to the directory server. Parameters can be set in the server configuration file to control the cache and how GAL requests are serviced.

In the [CWS] section of the unison.ini file, the parameter galsyncinterval controls the frequency of the cache refresh. In the [ENG] section, gal_enable, gal_enumsize, gal_enablegroupsearch, gal_enableldapsearch, gal_refreshintimes, and gal_view let you control other aspects of the GAL. For more information about these server parameters, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.

About the Common Address Book (CAB)

The Common Address Book, or CAB, is a personal address book that is stored in a central location on Oracle Internet Directory. Personal contacts that are created in the CAB using various Calendar clients are subsequently accessible through other Oracle Collaboration Suite components, such as Oracle WebMail.

This feature can be enabled/disabled by configuring the [ENG] cab_enable parameter in the $ORACLE_HOME/ocal/misc/unison.ini file. For more information about this parameter, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.

Note:

The Common Address Book feature is not available in Oracle Calendar standalone deployments.

Client Interfaces

At the time of release, the following Oracle Calendar clients will be able to interface with the Common Address Book:

Oracle Connector for Outlook
Oracle Calendar Desktop Clients
Oracle Calendar Sync for Palm
Oracle Calendar Sync for Pocket PC

When accessing address books, Calendar clients will be accessing a cached copy of the CAB from the Calendar server. All read operations will be pulled from Calendar server's cached copy of the Common Address Book whereas all modifications made to the CAB from a Calendar client will immediately be written to Oracle Internet Directory, and then written to the Calendar server's cached copy of the CAB. As a result, Oracle Internet Directory will always be kept up to date.

Synchronization with Oracle Internet Directory

In order to keep information up to date, the CAB on the Calendar server needs to be synchronized with the Oracle Internet Directory. The synchronization of the Common Address Book is done in segments, at different times. Each user's Common Address Book is synchronized, on average, based on the value assigned to the [ENG] cab_syncinterval parameter, in the $ORACLE_HOME/ocal/misc/unison.ini file. For more information about this parameter see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.

Synchronization of the Common Address Book is triggered in three possible ways: by the Calendar server's CWS daemon, by Directory Integration Platform (DIP) notifications, and manually by using the unidssync utility.

CWS Initiated Synchronization

This type of synchronization is a regular background task and can be configured in the Calendar server's $ORACLE_HOME/ocal/misc/unison.ini file. The [CWS] cabsynctime parameter enables you to configure a list of times at which the Common Address Book synchronization is initiated. For more information on this parameter, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.
DIP Initiated Synchronization

This type of synchronization can be viewed as a push synchronization. The Calendar server receives an asynchronous notification from the Oracle Internet Directory DIP. Once the notification has been received by the Calendar server, the synchronization will be processed.
Manual Synchronization

A manual synchronization can be performed using the unidssync utility with the -absync option. This option can be used to force a synchronization of a specific user's Common Address Book or the entire Common Address Book. For more information about this utility and option, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.

Note:

When the Common Address Book is updated using a non-Calendar client, such as Oracle WebMail, the modification is made on Oracle Internet Directory. As such, the modification may not immediately be propagated to the Calendar server's cached copy of the Common Address Book. The Calendar server will be updated within the time value assigned to the [ENG] cab_syncinterval parameter, in the $ORACLE_HOME/ocal/misc/unison.ini file.

Determining Address Book Type

In certain cases, Calendar users can have different types of address books. This is likely a result of time elapsed since upgrade from a previous version of Calendar.

A user attribute exists in order to verify the type of address book that is associated with a specific Calendar user. The attribute that will reveal this information is called ABSTATUS. In order to see this user attribute for a specific user or all users, use the $ORACLE_HOME/ocal/bin/uniuser utility. When using the utility, you must specify the -ext flag in order to view the ABSTATUS attribute.

Securing Connections to the Directory Server

For greater security, the connections between your calendar server and directory server will be protected by default using the Secure Sockets Layer (SSL) protocol. Without the use of SSL, passwords may be sent across the network in clear text.

In a Collaboration Suite installation, the calendar server will configure and establish an SSL connection to Oracle Internet Directory if it is available.

In a standalone Calendar Server installation, the following procedures are required to establish an SSL connection to a third-party directory server.

Make sure your calendar server is not running before you proceed.
Run Netscape Navigator on the calendar server host, and access your directory server using its secure port. For example:
```
https://<yourDSname>:<yourSSLport>/
```
In the pop-up site certificate window, select Accept the certificate forever.
Find the cert<X>.db file on your system (likely in the netscape/users/<username> directory). Note the location of this file.
Edit your $ORACLE_HOME/ocal/misc/unison.ini file, and add or modify the following parameters:
```
[LDAP]
security=TRUE
secure-port=636  (encryption port set on your directory server)
certdbpath="<path_including_file>"  (the value from Step 3)
```
Note:
The Calendar instance owner must have read access to the file specified in the certdbpath parameter.

For more information about these parameters and their correct values for your operating system, see "Calendar Server Parameters" in Chapter 3 of Oracle Calendar Reference Manual.
Restart your calendar server. All further communications with the directory server will use SSL.

Changing the Attribute Used for Single Sign-On Login

In a Oracle Collaboration Suite installation, one directory server attribute is designated as the attribute that the Oracle Internet Directory uses to authenticate Oracle Application Server Single Sign-On (SSO) logins. The calendar server configuration file stores this information with the parameter attr_uid in the [LDAP] section. This parameter controls the directory server attribute the calendar server uses as a unique user identifier.

If you change this attribute at any time on the directory server after you have installed the calendar server, it is vital that you perform the following calendar server configuration change. Otherwise, users will be unable to sign in using Web clients, and the integrity of your calendar database may be threatened.

Stop all calendar servers in your network.
Edit the $ORACLE_HOME/ocal/misc/unison.ini file on each calendar server host in the network, and modify the value of the following parameter:
```
[LDAP]
attr_uid = <attribute_used_for_login>
```
Restart all servers stopped in Step 0.
Run the following command from the $ORACLE_HOME/ocal/bin directory
```
% unidssync -remote -n <masternode>
```

When Does the Calendar Server Bind to the Directory Server?

In a standalone Calendar Server installation, when users query the calendar server for lists of other users, resources, or groups, the calendar server binds to the directory server using the "anonymous" profile.

If your directory server does not permit anonymous binding, or if you want to prevent the calendar server from binding anonymously, you can use the [LDAP] binddn and [LDAP] bindpwd parameters in the calendar server configuration file unison.ini to specify a directory server user account and password with which to bind.

This bind DN will be used for all read access to the directory server (such as user and resource searches). However, users and administrators still bind to the directory server as themselves when performing modifications to user, resources, or event calendar records.

Remember that you must encrypt the value of the bind password before including it in the unison.ini file. Use the uniencrypt utility with the -s argument, and include the entire output, enclosed within double quotation marks as the parameter value. For details on the use and syntax of uniencrypt, see "Calendar Server Utilities" in Chapter 6 of Oracle Calendar Reference Manual.