Utilizing AD Authentication for the RCM Portal

Overview
Utilizing AD authentication with RCM is a critical component for any customer wanting to control who is accessing the RCM portal. Although any LDAP repository could be used for this, Im focusing this guide strictly on Active Directory. To begin this guide, Ill cover how RCM handles authentication and authorization.

Authentication / Authorization
For the uninitiated, authentication is the process of ensuring a user is who they claim to be and authorization is the process of providing access to information a validated user is supposed to have. RCM handles authorizations internally through the RACI model. This is derived from the configuration information provided; namely the Person ID and Managers ID. This correlation establishes who manages or is Accountab le (the A in RACI) for that individual. When you first enter the RCM portal (after a fresh install), there is no (true) authentication or authorization. All that is required is to supply credentials that exist in the internal configuration (eurekify.cfg). If you open this configuration, youll find two default accounts. The default administrator account is AD1\EAdmin. Enabling the authorization model is accomplished within the Portal through Administration > Settings > Properties Settings: sage.security.disable=false. This parameter enables the internal authorizations built within the RACI. This means a Manager logging into the portal will only see their subordinates. This is helpful in testing a campaign creation, but no authentication credentials are required, yet. RCM addresses authentication by capitalizing on external authentication services. For the purposes of this discussion, we will be using a corporate Active Directory server for authentication. The users credentials must exist within eurekify.cfg. Well discuss this issue in greater detail.

The Log-in Field

In order for RCM and AD to communicate during the authentication exchange, a field must exist within the eurekify.cfg that corresponds to the users account in AD. An issue arises where AD is expecting the following format: domain\userID. When importing AD information through the connector, the userID is provided, but not in the format defined above. Short of manually entering a Login ID for every user, there are two suitable options to ensure a Login ID exists for every user within the eurekify.cfg.

Option 1: Kettle Concatenation The first option is to create a separate Login Field through Kettle. This will concatenate a field with domain and the users AD login ID. Through a simple Kettle script, this will output to a new column. When defining your Universe, you will use this field for the Configuration login field. Option 2: Empty Login Field in HR Data The second option is to ensure there is an empty field in the HR Data that will be used to enrich the udb. During the Universe creation process, use this empty field as the Configuration login field. The next step is to run the Permissions Configuration Settings. During the import, you will receive a message that the login field must be populated. You can define the login field and create a set prefix. So, here you could use the PersonID (if it is also the AD login ID) and append it with \domain. Either option will work. It is really a personal preference. To prevent the users from having to enter domain\loginID at the portal login screen, you can set the default domain name within the portal. Note: This issue has been raised to CA Support. They are evaluating the possibility of making the default domain parameter reversible. This allows users to authenticate without appending domain name within Eurekify.cfg.

Authentication Credentials
In order to connect with the AD authentication service, a valid users credentials must be supplied (username and password). These will be established within two parameters within the portal. The login credentials must be the fully qualified DN (ex. CN=user,CN=Users,DC=domain,DC=local). Note: the fields in the example may vary based on the AD configuration. The password must be entered in the second parameter. RCM can encrypt this entry. For a customer production environment, it is recommended that an RCM account be created for this purpose.

Step-By-Step Guide
Option 1 To concatenate the PersonID and the domain name, a simple Kettle transformation must be used. The assumption is that these pieces of information are provided in the HR Data. The code within this transformation can be added to other transformations you utilize for the customers data. For this example, the following header represents the HR data provided within an Excel spreadsheet: USER_Name,PREFERRED_NAME,SITE_NAME,JOB_TITLE,SUPERVISOR_ID, Department,Company,email_address The domain is macedon and USER_Name is the loginID (and PersonID). The Kettle transformation for adding the login field is:

The HRDataInput is simply defining the input file.

Within the HRDataInput step, click the Fields tab. From this window, click Get fields from header row. This will update this screen with the correct fields from your file.

The next step is Select values. The purpose of this step is to rename the USER_Name field to PersonID. For your file, click Get fields to select to update with the correct Fieldnames.

The next step is the Modified Java Script Value which will concatenate the domain name and the user name. This script starts by defining the AD_Prefix variable. A double slash is required for Java to recognize the character /. The second step is to take the AD_Prefix and concatenate it with the PersonID. The result is a new field called LOGIN.

The final step is HR Data. This outputs the results of the transformation to a new file called MaceHR.txt.

Use this HR data file to enrich your udb and create your configuration. Continue to follow the standard steps to create your Master and Model configurations within the database. The Master and Model configuration well be using for the Universe creation looks like this: (note the LOGIN field is ready to go)

From the RCM Portal, navigate to: Administration > Settings > Universe Settings. Select Create New to define your universe.

Universe Name, Description, Master configuration name, Model configuration name, and Approved audit card are self explanatory (remember, in the options fields, you can hit the down arrow for selections). For Configuration login field, down arrow and select the Login ID field you created in your configuration. Add the remaining applicable options and click Save.

If you receive warnings, click Yes to fix the issues.

After you create your Universe, the next step is to import all the users into RCMs internal configuration. This configuration is called eurekify.cfg. To accomplish this, we go to Adminstration > Permissions Configuration Settings > Update Permissions configuration with universe users. This imports all the users in the Universe into eurekify.cfg. If you open this file in the RCM tools, youll see everyones entry. Be sure Correlate Manager Login/ID is selected.

The results will appear beneath the selection options. In this case, we want to add all the users that were found. Click Add All Users and select Auto assign default role.

You will receive a confirmation that the users were added.

With the users now populated within the eurekify.cfg, you now need to create RACI. I will not go into a detailed explanation of RACI here; I recommend you read through the description in the RCM Step-By-Step Guide. Suffice to say, RACI establishes the authorizations for within RCM. To accomplish this, navigate to Administration > RACI > Create RACI. Select your Universe and click Create RACI. You will receive confirmation the RACI was created.

To continue, go to the section Configure Authentication for the next steps. The following section describes Option 2 for creating the Universe with the LOGIN field.

Option 2 In this second option, we were given the same HR data spreadsheet.

Here, we will use Excel to add an additional colu mn named LOGIN. There will be no entries in this column.

Next, save this file as a comma delimited (.csv) file.

Use this HR data file to enrich your udb and create your configuration. Continue to follow the standard steps to create your Master and Model configurations within the database. The Master and Model configuration well be using for the Universe creation looks like this: (note the LOGIN field is empty)

From the RCM Portal, navigate to: Administration > Settings > Universe Settings. Select Create New to define your universe.

Universe Name, Description, Master configuration name, Model configuration name, and Approved audit card are self explanatory (remember, in the options fields, you can hit the down arrow for selections). For Configuration login field, down arrow and select the Login ID field that is currently empty in your configuration. Add the remaining applicable options and click Save.

If you receive warnings, click Yes to fix the issues.

After you create your Universe, the next step is to import all the users into RCMs internal configuration. This configuration is called eurekify.cfg. To accomplish this, we go to Adminstration > Permissions Configuration Settings > Update Permissions configuration with universe users. This imports all the users in the Universe into eurekify.cfg. If you open this file in the RCM tools, youll see everyones entry. Be sure Correlate Manager Login/ID is selected.

The results will appear beneath the selection options. In this case, we will need to fix the users since their login field data is missing. For the Use Field, select PersonID and Use Prefix is domain \ (in this case macedon\). Be sure to update the model configuration as well.

After fixing the users, you can add them into the configuration by clicking Add All Users. Be sure to select Auto assign default role.

You will receive a confirmation that the users were added.

With the users now populated within the eurekify.cfg, you now need to create RACI. I will not go into a detailed explanation of RACI here; I recommend you read through the description in the RCM Step-By-Step Guide. Suffice to say, RACI establishes the authorizations for within RCM. To accomplish this, navigate to Administration > RACI > Create RACI. Select your Universe and click Create RACI. You will receive confirmation the RACI was created.

The following section will describe the details for configuring authentication within the RCM portal. These steps are consistent regardless of the option chosen.

Configure Authentication
Now its time to configure authorization. Navigate to Administration > Settings > Properties Settings. In the bottom search pane, filter on sec. Special note: One of the properties well be setting up later misspells security: (ws.secutiry.manager.password).

To turn on RCM security (enable authorization), Edit the sage.security.disable parameter. The default is set to true; which means security is disabled or not active. Change this value to false. You will need to change the Type to Database Property. To change Home Directory Properties, you will need to manually edit the eurekify.properties file (NOT recommended). Note: You do NOT need to restart the JBoss service for these changes to take effect. If you log off and back in with a non-privileged user that exists in the eurekify.cfg (no password necessary, yet), youll notice that the user cannot see the Administration menu. We now, want to enable authentication. We will be editing multiple properties. VERY SPECIAL NOTE: You will now have to supply a valid password for the AD1\EAdmin built in account. This is defaulted to eurekify. It can be changed by editing the sage.admin.password property (filter on password). With the sec filter active, edit the following properties: sage.security.disable.ADAuthentication = false (enables the AD Authentication service) ws.security.ldap.server = the host name of the AD server ws.security.manager.dn = the user / system account to connect to the AD server. Format must be the fully qualified AD name. For example: CN=macear,CN=Users,DC=Macedon,DC=local (Note: some testing indicates that domain\username will work here). ws.secutiry.manager.password = the password for the above account. This can be encrypted (highly recommended)

Next, we want to filter on domain. Edit the sage.default.domain parameter. Enter the domain name of the domain controller. This will prevent users from having to prefix their login credentials with domain \. Upon completion of these steps, you will now be challenged for a valid AD username and password. As a further note: to add a user into the EAdmin role, drag and drop the applicable users to the EAdmin role (middle pane) in the RCM Data Management client tool. Be sure to remove write protection prior to accomplishing this. Also, you can create your own internal roles by dragging and dropping resources to the new role. Finally, the author would like to thank, Srinivasan Mali Vanamali for his development of the Kettle script contained within.