Adding realm support on Linux in a clustered environment

A realm is a group of users from one or more user registries that form a coherent group within IBM® WebSphere® Portal. Realms allow flexible user management with various configuration options. A realm must be mapped to a Virtual Portal to allow the defined users to log in to the Virtual Portal. When you configure realm support, complete these steps for each base entry that exists in both your LDAP and database user registry to create multiple realm support.

Before you begin

Before you configure realm support, you must add all LDAP user registries and database user registries, that you use to create a single realm or multiple realms, to the federated repository. If you are going to create multiple realms, you must create all required base entries within your LDAP user registries and database user registries. All base entry names must be unique within the federated repository.

In a stand-alone server environment, you can complete the following task when the servers are either stopped or started. In a clustered environment, start the deployment manager and node agent and verify that they are able to synchronize.

About this task

Complete the following steps to add realm support to your user registry model:

Procedure

  1. Before you configure security, you must use the IBM WebSphere Application Server backupConfig task to create and store a backup of the IBM WebSphere Portal configuration; see backupConfig command for information.
  2. Use a text editor to open the wkplc.properties file, in the wp_profile_root/ConfigEngine/properties directory.
  3. Required: Enter a value for the following parameters in the wkplc.properties file under the VMM realm configuration heading:
    Note: See the properties file for specific information about the advanced parameters.
    • realmName
    • securityUse
    • delimiter
    • addBaseEntry
  4. Save your changes to the wkplc.properties file.
  5. Run the ./ConfigEngine.sh wp-create-realm -DWasPassword=password task, from the wp_profile_root/ConfigEngine directory to add a realm to the Virtual Member Manager configuration.
    Important: To create multiple realms, ensure that your federated repository contains the unique base entries. Stop and restart the appropriate servers for your installation environment, and then update the wkplc.properties file with the base entry information and rerun the wp-create-realm task. Repeat these steps until all realms are created.
  6. Stop and restart the appropriate servers to propagate the changes. For specific instructions, see Starting and stopping servers, deployment managers, and node agents.
  7. Enter a value for the following parameters in the wkplc.properties file under the VMM realm configuration heading and then save your changes:
    Note: See the properties file for specific information about the advanced parameters.
    • realmName
    • realm.personAccountParent
    • realm.groupParent
    • realm.orgContainerParent
  8. Run the ./ConfigEngine.sh wp-modify-realm-defaultparents -DWasPassword=password task, from the wp_profile_root/ConfigEngine directory to update the default parents per entity type and realm.
    Important: Stop and restart the appropriate servers for your installation environment before you rerun this task for any additional entity types and realms.
  9. Stop and restart the appropriate servers to propagate the changes. For specific instructions, see Starting and stopping servers, deployment managers, and node agents.
  10. Optional: Complete the following steps to add more base entries to the realm configuration:

    For example, you have two more base entries (base entry 1 and base entry 2) to add to the realm you created. You must update the wkplc.properties file with the information from base entry 1 and then run this task. Then, update the properties file with the information for base entry 2 and then run this task.

    1. Use a text editor to open the wkplc.properties file, in the wp_profile_root/ConfigEngine/properties directory.
    2. Enter a value for the following parameters in the wkplc.properties file under the VMM realm configuration heading:
      Note: See the properties file for specific information about the advanced parameters.
      • realmName
      • addBaseEntry
    3. Save your changes to the wkplc.properties file.
    4. Run the ./ConfigEngine.sh wp-add-realm-baseentry -DWasPassword=password task, from the wp_profile_root/ConfigEngine directory to add more LDAP base entries to the realm configuration.
    5. Stop and restart all necessary servers to propagate your changes.
  11. Optional: Complete the following steps to replace the WebSphere Application Server and WebSphere Portal administrator user ID; if you change the default realm this step is needed:
    1. Create a user in the Manage Users and Groups portlet to replace the current WebSphere Application Server administrative user.
    2. Create a user in the Manage Users and Groups portlet to replace the current WebSphere Portal administrative user.
    3. Create a group in the Manage Users and Groups portlet to replace the current group.
    4. Run the ./ConfigEngine.sh wp-change-was-admin-user -DWasPassword=password -DnewAdminId=newadminid -DnewAdminPw=newpassword task, from the wp_profile_root/ConfigEngine directory to replace the old WebSphere Application Server administrative user ID and group ID with the new user and group.
      Important: You must provide the full distinguished name (DN) for the newAdminId and newAdminGroupId parameters.
      Additional parameter for stopped servers: This task verifies the user against a running server instance. If the server is stopped, add the -Dskip.ldap.validation=true parameter to the task to skip the validation.
    5. Verify that the task completed successfully. Stop and restart all servers.
    6. Run the ./ConfigEngine.sh wp-change-portal-admin-user -DWasPassword=password -DnewAdminId=newadminid -DnewAdminPw=newpassword -DnewAdminGroupId=newadmingroupid task to replace the old WebSphere Portal administrative user ID and group ID with the new user and group.
      Important: You must provide the full distinguished name (DN) for the newAdminId and newAdminGroupId parameters.
      Additional parameter for stopped servers: This task verifies the user against a running server instance. If the server is stopped, add the -Dskip.ldap.validation=true parameter to the task to skip the validation.
    7. Verify that the task completed successfully. Stop and restart all servers.
  12. Optional: Complete the following steps to set the realm you created as the default realm:
    Remember: Only users that are defined in base entries that exist in the default realm are able to log in to WebSphere Portal. If a user cannot log in to WebSphere Portal, check whether the base entry that contains the user exists in the default realm. You can run the wp-query-realm-baseentry task to see what base entries are part of the default realm. If the default realm is missing the base entry, run the wp-add-realm-baseentry task to add the base entry to the default realm.
    1. Use a text editor to open the wkplc.properties file, in the wp_profile_root/ConfigEngine/properties directory.
    2. For defaultRealmName, type the realmName property value you want to use as the default realm.
    3. Save your changes to the wkplc.properties file.
    4. Run the ./ConfigEngine.sh wp-default-realm -DWasPassword=password task, from the wp_profile_root/ConfigEngine directory to set this realm as the default realm.
    5. Stop and restart all necessary servers to propagate your changes.
  13. Optional: Complete the following steps to query a realm for a list of its base entries:
    1. Use a text editor to open the wkplc.properties file, in the wp_profile_root/ConfigEngine/properties directory.
    2. For realmName, type the name of the realm you want to query.
    3. Save your changes to the wkplc.properties file.
    4. Run the ./ConfigEngine.sh wp-query-realm-baseentry -DWasPassword=password task, from the wp_profile_root/ConfigEngine directory to list the base entries for a specific realm.
  14. Optional: Complete the following steps to enable the full distinguished name login if the short names are not unique for the realm:
    Tip: Run this task if the administrator name is in conflict with another user name in the attached repository. This command allows the Administrator to log in using the fully distinguished name instead of the short name.
    1. Use a text editor to open the wkplc.properties file, in the wp_profile_root/ConfigEngine/properties directory.
    2. Enter a value for realmName or leave blank to update the default realm.
    3. Save your changes to the wkplc.properties file.
    4. Run the ./ConfigEngine.sh wp-modify-realm-enable-dn-login -DWasPassword=password task, in the wp_profile_root/ConfigEngine directory to enable the distinguished name login.
      Note: After you run this task to enable the full distinguished name login, run the ./ConfigEngine.sh wp-modify-realm-disable-dn-login -DWasPassword=password task to disable the feature.
    5. Stop and restart all necessary servers to propagate your changes.

What to do next

If you created your clustered environment, including the additional nodes, and then completed the steps in this task, you must now run the update-jcr-admin task on the secondary node. See the related links section for instructions.