C Username Reservation and Common Name Generation

This appendix contains the following topics:

Username Reservation
Common Name Generation

C.1 Username Reservation

When the request for user creation is submitted, the following scenarios are possible:

While the request is pending, another create user request is submitted with the same username. If the second request is approved and the user is created, then the first request, when approved, fails because the username already exists in Oracle Identity Manager.
While the request is pending, another user with the same username is directly created in the LDAP identity store. When the create user request is approved, it fails while provisioning the user entity to LDAP because an entry already exists in LDAP with the same username.

To avoid these problems, you can reserve the username in both Oracle Identity Manager and LDAP while the create user request is pending for approval. If a request is created to create a user with the same username, then an error message is displayed and the create user request is not created.

For reserving the username:

The USER ATTRIBUTE RESERVATION ENABLED system property must be set to TRUE for the functionality to be enabled. For information about searching and modifying system properties, see "Managing System Properties" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.
Reservation in LDAP is done only if reservation functionality is enabled, and LDAP is in sync with Oracle Identity Manager database. For information about synchronization between Oracle identity Manager and LDAP identity store, see "Integration Between LDAP Identity Store and Oracle Identity Manager" in Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager.
Note:
- If LDAP provider is not configured, then the reservation is done only in Oracle Identity Manager.
- When LDAP synchronization and user attribute reservation features are enabled, it is recommended to enable UID uniqueness in the directory server. Without this, user reservation in the directory does not work properly because while the user is reserved in the reservation container, the user with the same user ID can be created in the user container. This results is user creation failure when Oracle Identity Manager tries to move the user from the reservation container to the user container.

If user attribute reservation is enabled, the reservation happens in two phases:

In the first phase, an entry is created in Oracle Identity Manager database and a user is created in reservation container. This entry in Oracle Identity Manager database is removed after successful creation of user, rejection by approver, or request failure.

In the second phase, in LDAP, on successful creation, the user is moved to the reservation container. In other cases such as rejection by approver or request failure, the user is removed from the reservation container.

After the request-level and operation-level approvals are obtained for the create user request, the username is no longer reserved in the username container in LDAP. The username is moved to the container in which the existing users are stored. The user is also created in Oracle Identity Manager.

This section consists of the following topics:

Enabling and Disabling Username Reservation
Configuring the Username Policy
Writing Custom User Name Policy
Releasing the Username
Configuring Username Generation to Support Microsoft Active Directory

C.1.1 Enabling and Disabling Username Reservation

The username reservation functionality is enabled by default in Oracle Identity Manager. This is done by keeping the value of the USER ATTRIBUTE RESERVATION ENABLED system property to TRUE. You can verify the value of this system property in the System Configuration section of the Oracle Identity Manager System Administration Console.

To disable username reservation:

Log in to Oracle Identity System Administration.
In the left pane, under System Management, click System Configuration. The Advanced Administration opens in a new window.
In the left pane, click the search icon to search for all existing system properties. A list of system properties are displayed in the search results table.
Click User Attribute Reservation Enabled. The System Property Detail page for the selected system property is displayed, as shown in Figure C-1:

Figure C-1 The System Property Detail Page

Description of "Figure C-1 The System Property Detail Page"
In the Value field, enter False.
Click Save. The username reservation functionality is disabled.

C.1.2 Configuring the Username Policy

Username Policy is a plugin implementation for username operations such as username generation and username validation. You can change the default policies from the System Configuration section in Oracle Identity System Administration.

In case of a Create User usecase, the plugins are invoked only if the user login is not provided. In such a case, the plugin to be invoked is picked up from the system property, "Default policy for username generation". The custom user name policy is honored in all the following use cases:

Create Admin User
Create User Request
Reconciliation
Bulk Load

Table C-1 lists the predefined username policies provided by Oracle Identity Manager. In this table, the dollar ($) sign in the username generation indicates random alphabet:

Table C-1 Predefined Username Policies

Policy Name	Expected Information	Username Generated
oracle.iam.identity.usermgmt.impl.plugins.EmailIdPolicy	E-mail	E-mail value is used as the auto-generated user name
oracle.iam.identity.usermgmt.impl.plugins.LastNameFirstInitialLocalePolicy	First name, last name, and locale	last name + first initial_locale, last name + middle initial + first initial_locale, last name + $ + first initial_locale (all possibilities of single random alphabets), last name + $$ + first initial_locale
oracle.iam.identity.usermgmt.impl.plugins.FirstInitialLastNameLocalePolicy	Firstname, Lastname, Locale	first initial + lastname_locale, first initial + middle initial + first name_locale, first initial + $ + lastname_locale, first initial + $$ + lastname_locale
oracle.iam.identity.usermgmt.impl.plugins.LastNameFirstInitialPolicy	Firstname, Lastname	lastname+firstInitial, lastname+middleinitial+firstInitial, lastname+$+firstInitial ( all possibilities of single random alphabets) , lastname+$$+firstInitial
oracle.iam.identity.usermgmt.impl.plugins.FirstInitialLastNamePolicy	Firstname, Lastname	firstInitial+lastname, firstInitial+middleInitial+firstname, firstInitial+$+lastname, firstInitial+$$+lastname
oracle.iam.identity.usermgmt.impl.plugins.LastNameFirstNamePolicy	Firstname, Lastname	lastname.firstname, lastname.middleinitial.firstname, lastname.$.firstname ( all possibilities of single random alphabets) , lastname.$$.firstname
oracle.iam.identity.usermgmt.impl.plugins.FirstNameLastNamePolicy	Firstname, Lastname	firstname.lastname, firstname.middleinitial.lastname, firstname.$.lastname (all possibilities of single random alphabets) , firstname.$$.lastname
oracle.iam.identity.usermgmt.impl.plugins.DefaultComboPolicy	Any one of the following: - Email - Firstname, Last Name - Last name.	If e-mail is provided, then username is generated based on the e-mail. If e-mail is not available, then it generates username based on firstname and lastname by appending a user domain to it. If first name is not available, then it generates the username based of the last name only by appending a user domain to it. The user domain is configured as the Default user name domain system property, and the default value is @oracle.com
oracle.iam.identity.usermgmt.impl.plugins.LastNamePolicy,	Lastname	lastname, middle initial + lastname , $ + lastname, $$ + lastname
oracle.iam.identity.usermgmt.impl.plugins.LastNameLocalePolicy	Lastname, Locale	lastname_locale, middle initial + lastname_locale , $ + lastname_locale, $$ + lastname_locale
oracle.iam.identity.usermgmt.impl.plugins.FirstNameLastNamePolicyForAD	Firstname, Lastname	firstname+lastname, substring of firstname+lastname+$, substring of firstname+ substring of lastname+$
oracle.iam.identity.usermgmt.impl.plugins.LastNameFirstNamePolicyForAD	Lastname, Firstname	lastname+firstname, lastname+substring of firstname+$, substring of lastname+ substring of firstname+$

The policy implementations generate the username, check for its availability, and if the username is not available, then generate other username based on the policy in the order mentioned in Table C-1, and repeat the procedure. The dollar ($) sign in the username generation indicates random alphabet. If any of the expected information is missing, then the policies generate errors.

Values must be provided for all the parameters of the username generation format. If any of the parameters are not provided, then Oracle Identity Manager generates an error. For example, If the firstname.lastname policy is configured and the firstname is not provided, then the error would be "An error occurred while generating the Username. Please provide firstname as expected by the firstname.lastname policy".

The username generation is exposed as public APIs in User Manager. Oracle Identity Manager provides an utility class for accessing the functionality of generating user names. The class that contains utility methods is as shown:

oracle.iam.identity.usermgmt.api.UserManager

The UserManager class exposes the following public API for username generation and validation:

//Method that will generate username based on default policy

    public String generateUserNameFromDefaultPolicy(Map<String,  Object> attrMap)
 throws UserNameGenerationException,  UserManagerException;

//Method that will generate username based on policy

    public String generateUserNameFromPolicy(String policyId,  Map<String, Object> 
attrMap) throws UserNameGenerationException,  UserManagerException;

//Method that will check whether username is valid against default policy

    public boolean isUserNameValidForDefaultPolicy(String userName,  Map<String, 
Object> attrMap) throws UserManagerException;

//Method that will check whether username is valid against given policy

    public boolean isUserNameValidForPolicy(String userName, String  policyId, 
Map<String, Object> attrMap) throws  UserManagerException;

//Method to return all policies (including customer written)

        public List<Map<String, String>> getAllUserNamePolicies(Locale locale)

//Method that will return policy description in given locale

    public String getPolicyDescription(String policyID, Locale locale)

Table C-2 lists the constants defined in oracle.iam.identity.usermgmt.utils.UserNameGenerationUtil to represent the policy ID of the default username policies:

Table C-2 Constants Representing Policy IDs

Policy Name	Constant
EmailIDPolicy	EMAIL_ID_POLICY
LastNameFirstInitialLocalePolicy	FIRSTNAME_LASTNAME_POLICY
FirstInitialLastNameLocalePolicy	LASTNAME_FIRSTNAME_POLICY
LastNameFirstInitialPolicy	FIRSTINITIAL_LASTNAME_POLICY
FirstInitialLastNamePolicy	LASTNAME_FIRSTINITIAL_POLICY
LastNameFirstNamePolicy	FIRSTINITIAL_LASTNAME_LOCALE_POLICY
FirstNameLastNamePolicy	LASTNAME_FIRSTINITIAL_LOCALE_POLICY
DefaultComboPolicy	DEFAULT_COMBO_POLICY
LastNamePolicy	LASTNAME_POLICY
LastNameLocalePolicy	LASTNAME_LOCALE_POLICY
FirstNameLastNamePolicyForAD	FIRSTNAME_LASTNAME_POLICY_FOR_AD
LastNameFirstNamePolicyForAD	LASTNAME_FIRSTNAME_POLICY_FOR_AD

When called to generate username, the policy classes expect the attribute values to be set in a map by using the key constants defined in the oracle.iam.identity.utils class.Constants. This means that a proper parameter value must be passed to call the method by using the appropriate constant defined for it, for example, the FirstName parameter has a constant defined for it.

The default username policy can be configured by using the Oracle Identity System Administration. To do so:

Navigate to the System Configuration section.
Search for all the system properties.
Click Default policy for username generation. The System Property Detail page for the selected property is displayed, as shown in Figure C-2:

Figure C-2 The Default Username Policy Configuration

Description of "Figure C-2 The Default Username Policy Configuration"

The XL.DefaultUserNameImpl system property is provided for picking up the default policy implementation. By default, it points to the default username policy, which is oracle.iam.identity.usermgmt.impl.plugins.DefaultComboPolicy displayed in the Value field.
In the Value field, enter oracle.iam.identity.usermgmt.impl.plugins.POLICY. Here, POLICY is one of the policy implementations.
Note:
All the plug-ins must be registered with Oracle Identity Manager by using the /identity/metadata/plugin.xml file. A sample plugin.xml file is as shown:
```
<plugins pluginpoint="oracle.iam.identity.usermgmt.api.UserNamePolicy">        <plugin
pluginclass="oracle.iam.identity.usermgmt.impl.plugins.LastNameFirstNamePolicy"
version="1.0" name="LastNameFirstNamePolicy"/>
</plugins>
```
Click Save.

C.1.3 Writing Custom User Name Policy

You can write your own policies by adding new plug-ins and changing the default policies from the System Configuration section in Oracle Identity System Administration.

See Also:

"Developing Plug-ins" for information about the plug-in framework

The UserManager exposes APIs for username operations. The APIs take the user data as input and return a generated username. The APIs make a call to plug-ins that return the username. This allows you to replace the default policies with custom plug-ins with your implementation for username operations.

Note:

For user name generation and validation, public APIs are exposed in UserManager.
While creating the policy, ensure that the attributes used in generating the username are defined in the request data set.

You can write your own username policies by implementing the plug-in interface, as shown:

package oracle.iam.identity.usermgmt.api;

public interface UserNameGenerationPolicy extends
 oracle.iam.identity.usermgmt.api.UserNamePolicy {
public String getUserName(Map<String, Object> reqData) throws UserNameGenerationException;
public boolean isGivenUserNameValid(String userName, Map<String, Object> reqData);

//methods inherited from old user name policy interface
//oracle.iam.identity.usermgmt.api.UserNamePolicy
public String getUserNameFromPolicy(HashMap<String, String> reqData) throws UserNameGenerationException;
public boolean isUserNameValid(String userName, HashMap<String, String> reqData);
public String getDescription(Locale locale);

}

This plug-in point is exposed as a kernel plug-in that takes request data as input and returns the username. Each plug-in expects some information and generates username based on that information provided.

Note:

Oracle Identity Manager provides an abstract implementation of the oracle.iam.identity.usermgmt.api.UserNameGenerationPolicy interface as the oracle.iam.identity.usermgmt.api.AbstractUserNameGenerationPolicy class name. Therefore, you need not implement the following two methods:

public String getUserNameFromPolicy(HashMap<String, String> reqData) throws UserNameGenerationException;

public boolean isUserNameValid(String userName, HashMap<String, String> reqData);

Create the plug-in ZIP with lib (containing the JAR) and plugin.xml, and then register it by performing the procedure in section "Registering and Unregistering Plug-ins By Using the Plugin Registration Utility". The following is a sample plugin.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<oimplugins>
<plugins pluginpoint="oracle.iam.identity.usermgmt.api.UserNamePolicy">
<plugin pluginclass="oracle.iam.identity.usermgmt.impl.plugins.CustomDepartmentNumberEmployeeNumberPolicy" version="1.0" name="CustomDepartmentNumberEmployeeNumberPolicy"/>
</plugins>
</oimplugins>

The following are the guidelines on while writing custom user name policies:

Policies should implement the new interface oracle.iam.identity.usermgmt.api.UserNameGenerationPolicy.
Custom user name policies must be re-entrant. This means that the custom code in the policy should return the same user login if approver has updated an attribute that does not contribute in generating the user login.

For sample implementation please refer below:

package oracle.iam.identity.usermgmt.impl.plugins;

import java.util.Locale;
import java.util.Map;

import oracle.iam.identity.exception.UserNameGenerationException;
import oracle.iam.identity.usermgmt.api.AbstractUserNameGenerationPolicy;
import oracle.iam.identity.usermgmt.api.UserManagerConstants;
import oracle.iam.identity.usermgmt.api.UserNameGenerationPolicy;

public class CustomDepartmentNumberEmployeeNumberPolicy extends AbstractUserNameGenerationPolicy implements UserNameGenerationPolicy {


          private String departmentNumberKey = UserManagerConstants.AttributeName.DEPARTMENT_NUMBER.getId();

          private String employeeNumberKey = UserManagerConstants.AttributeName.EMPLOYEE_NUMBER.getId();

          @Override
          public String getUserName(Map<String, Object> reqData)
                                    throws UserNameGenerationException {

          String departmentnumber = reqData.get(departmentNumberKey) == null ? null : reqData.get(departmentNumberKey).toString();

          String employeeNumber = reqData.get(employeeNumberKey) == null ? null : reqData.get(employeeNumberKey).toString();
           
          // Required in case of approver edit. If approver has not modified any attribute which contributes in user name generation , then return same old user login

          //Check if user data is not changed using checkForSameUserLogin method present in AbstractUserNameGenerationPolicy, then return same user login

          //OR use Map<String, Object> existingData = (Map<String, Object>) reqData.get(oracle.iam.identity.usermgmt.api.UserManagerConstants.EXISTING_DATA ) to implement your own comparison logic

          // If existingData is NULL, it means generate a new user login. If it is not NULL, then it means policy is invoked during approver edit.

          // If it is NOT NULL, Compare value of participating attributes from existingData and reqData. If same, return same user login as present in existingData ; otherwise generate a new user login.

          String oldUserLogin = checkForSameUserLogin(reqData , new String[]{departmentNumberKey , employeeNumberKey});
               if(oldUserLogin!=null)
                    return oldUserLogin;

               // TODO: DO basic validations. Also, Ensure newly generated user name is unique and not reserved. You may use utility methods in oracle.iam.identity.usermgmt.utils.UserNamePolicyUtil for preforming validations.
               return departmentnumber + "-" + employeeNumber;
          }

          @Override
          public boolean isGivenUserNameValid(String userName, Map<String, Object> reqData) {
               // TODO : custom implementation
               return true;
}

@Override
public String getDescription(Locale locale) {
               return "User Name Generation Policy using department number and employee number";
     }

}

C.1.4 Releasing the Username

The username is released in the following scenarios:

When the request is approved, and the user is successfully created in Oracle Identity Manager and provisioned to LDAP, and the username from the reserved table is removed. The reserved username is removed after successful user creation after the approvals. The reserved entry in LDAP is removed and the actual user is created.
If the request is rejected, then the reserved entry of username in LDAP and Oracle Identity Manager is removed.
If the request fails while or before creating a user in Oracle Identity Manager or LDAP, then the reserved username is deleted.

C.1.5 Configuring Username Generation to Support Microsoft Active Directory

In Oracle Identity Manager deployment with LDAP synchronization is enabled, where Microsoft Active Directory (AD) is the data store, the User Login attribute in Oracle Identity Manager is mapped to the uid attribute in LDAP, which in turn is mapped to the sAMAccountName attribute. The sAMAccountName attribute is used as login for all AD-based applications. There is a limitation on the maximum length supported for value contained in the sAMAccountName attribute in AD. It cannot exceed 20 characters.

Oracle Identity Manager accepts user name as an input at the time of user creation and it can be more than 20 characters. Because AD does not support user name of more than 20 characters, Oracle Identity Manager can be configured to generate the user name, which consists of less than 20 characters.

When AD is used as data store, you can configure the autogeneration of user name by setting the value of the XL.DefaultUserNamePolicyImpl system property to any one of the following:

FirstNameLastNamePolicyForAD: Generates the user login by prefixing a substring from the first name to that of the last name
LastNameFirstNamePolicyForAD: Generates the user login by prefixing a substring from last name to that of the first name

See "Administering System Properties" for information about the XL.DefaultUserNamePolicyImpl system property and setting values of system properties.

Note:

If AD is the data store, then any one of the FirstNameLastNamePolicyForAD or LastNameFirstNamePolicyForAD policies must be used. Any other user name generation policy will fail to generate the user name.

C.2 Common Name Generation

The generation of the Common Name user attribute value in Oracle Identity Manager is described in the following sections:

Common Name Generation for Create User Operation
Common Name Generation for Modify User Operation

C.2.1 Common Name Generation for Create User Operation

In an LDAP-enabled deployment of Oracle Identity Manager, Fusion applications such as Human Capability Management (HCM) does not pass the common name via SPML request. Given that the common name is a mandatory attribute in LDAP and Oracle Identity Manager is setup to use it as the RDN, Oracle Identity Manager must generate a unique common name.

Based on the description on Common Name, it is the user's display name consisting of first name and last name. Therefore, Oracle Identity Manager generates the Common Name with the help of a common name generation policy that specifies the Common Name in the "firstname lastname" format.

To configure common name generation in Oracle Identity Manager, set the value of the XL.DefaultCommonNamePolicyImpl system property to oracle.iam.identity.usermgmt.impl.plugins.FirstNameLastNamePolicy. For information about the XL.DefaultCommonNamePolicyImpl system property and setting the value of a system property, see "Managing System Properties" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.

The following are the details of the FirstNameLastNamePolicy:

Expected information: Firstname, Lastname
Common Name generated: firstname.lastname, firstname.$.lastname (all possibilities of single random alphabets), firstname.$$.lastname and so on until a unique common name is generated

Note:
The common name must be reserved until the user is created by the request so that multiple requests generated simultaneously having same first and last names do not generate the same common name.

C.2.2 Common Name Generation for Modify User Operation

When the user profile is modified, one or more attributes can change. HCM cannot filter out and send only the modified data to Oracle Identity Manager because it does not have the old user attributes and cannot determine which ones are modified. Therefore, all attributes including the common name (CN) are passed to Oracle Identity Manager by the SPML request. Because the CN changed, Oracle Identity Manager attempts a modify operation (modrdn) in the directory resulting in DN change. Because of this unintended DN change, the group membership DN becomes stale resulting in the user loosing membership in that group. This subsequently results in authorization failure. This happens when referential integrity is turned off in the LDAP server, and therefore, the referenced groups are not updated when the RDN of the user changes. Therefore, referential integrity must be turned on in the target LDAP server. Otherwise, the group memberships become stale. The referential integrity issue is also applicable to roles. Groups are also members of other groups and any RDN changes must be reflected as well.

You can turn on the referential integrity by setting the value of the XL.IsReferentialIntegrityEnabled system property to TRUE. For information about this system property, see "Managing System Properties" in the Oracle Fusion Middleware Administrator's Guide for Oracle Identity Manager.

Table C-3 lists the possible scenarios when RDN is modified:

Table C-3 RDN Modification Scenarios

Referential Integrity in LDAP	XL.IsReferentialIntegrityEnabled	Result of Modify Operation (modrdn)
Disabled	FALSE	Oracle Identity Manager generates an error and operation fails.
Disabled	TRUE	Modify operation passes from Oracle Identity Manager and RDN is changed in LDAP. However, the group references are not updated and are stale. This configuration is not recommended.
Enabled	FALSE	Oracle Identity Manager generates an error and modify operation fails. This property must be set to TRUE in Oracle Identity Manager because referential integrity is enabled in LDAP.
Enabled	TRUE	Modify operation passes and RDN is updated. In addition, the references for the DN are updated in LDAP.
Multiple directories with roles and users stored in separate directories. Referential integrity property is not relevant here.	FALSE	Modify operation fails from Oracle Identity Manager. This is not supported by LDAP. Therefore, FALSE is the recommended value in Oracle Identity Manager for the property.
Multiple directories with roles and users stored in separate directories. Referential integrity property is not relevant here.	TRUE	Modify operation passes and RDN is modified. However, because LDAP does not support referential integrity in multiple directories, the group references are stale and must be manually updated.