Securing Introscope using Local security

Local authentication is used by default in Introscope. If Local authentication is used, CA APM users and passwords are stored in users.xml. User details such as email and phone number are not maintained in the Local realm. The Local realm cannot maintain two users with the same name and same password, however can maintain two users having the same name but different passwords. If there are two users with the same name and different passwords, the Local realm sees these as separate users. For more information about defining users, groups, and generating passwords, see Configuring CA APM users and groups in users.xml.
apmdevops106
Local authentication is used by default in Introscope. If Local authentication is used, CA APM users and passwords are stored in users.xml. User details such as email and phone number are not maintained in the Local realm. The Local realm cannot maintain two users with the same name and same password, however can maintain two users having the same name but different passwords. If there are two users with the same name and different passwords, the Local realm sees these as separate users. For more information about defining users, groups, and generating passwords, see Configuring CA APM users and groups in users.xml.
Local authentication changes are dynamic: when a CA APM user attempts to log in, passwords are compared to users.xml file each time an authentication request is made. If you are migrating Introscope users from a previous Introscope installation, do not change the name or location of the users.xml file until after migration is complete.
2
2
Now that you have some background in Introscope security, you are ready to plan your security deployment.
Follow these steps:
  1. If needed, configure the Local realm as a security realms in realms.xml.
    The Local realm is the Introscope default ream in realms.xml.
  2. Set up users and groups with passwords in
    users.xml
    .
  3. Assign domain permissions in domains.xml.
  4. Assign Enterprise Manager server permissions in server.xml.
  5. Maintain Introscope security by adding, deleting, editing CA APM groups, users, domains, and servers with their associated permissions as needed.
Configuring Local authentication in realms.xml
Follow these rules when configuring realms.xml:
The Enterprise Manager will not start if any of these rules are not met.
  • The value of
    descriptor=
    is case-sensitive.
    • For example,
      descriptor=Local Users and Groups Realm
      is different from
      descriptor=local users and groups realm
      .
  • For Local realms, the value of
    descriptor=
    must be
    Local Users and Groups Realm
    .
  • In the case of multiple realms, the value of
    id=
    in the realms tag has to be unique for each realm. For example:
    <realm descriptor="EEM Realm" id="EEM" active="true">
    <property name="username">
    <value>EiamAdmin</value
    </property>
    <property name="host">
    <value>localhost</value>
    </property>
    <property name="appname">
    <value>APM</value>
    </property>
    <property name="enableAuthorization">
    <value>true</value>
    </property>
    <property name="plainTextPasswords">
    <value>false</value>
    </property>
    <property name="password">
    <value>YhCVozLDYThTJk3icaAaY9/5MhJRqQ1X</value>
    </property>
    </realm>
    <realm descriptor="Local Users and Groups Realm" id="Local Users and Groups" active="true">
    <property name="usersFile">
    <value>users.xml</value>
    </property>
    </realm>
Follow these steps:
  1. Open the realms.xml file in the
    <EM_Home>/
    config directory.
  2. Verify that this line is present as the third entry in realms.xml:
    <realm active="true" descriptor="Local Users and Groups Realm" id="Local Users and Groups">
  3. Set this property as appropriate.
    usersFile
    The file name relative to the
    <EM_Home>/
    config directory where users are stored. By default, this is users.xml.
  4. Save changes to the realms.xml file, and restart the Enterprise Manager to apply the changes.
realms.xml syntax with Local authentication enabled
Here is example code from a realms.xml file.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<realms xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="0.1" xsi:noNamespaceSchemaLocation="realms0.1.xsd">
<realm descriptor="Local Users and Groups Realm" id="Local Users and Groups" active="true">
<property name="usersFile">
<value>users.xml</value>
</property>
</realm>
About using multiple files for security realms
If you have only one file listed in realms.xml file for all your security realms, you can ignore this topic.
You may set up multiple realms if, for example, you want a default realm that gives a user basic permissions and a second realm that gives different permissions. Or your organization may have two LDAP servers, and you want to test security both of them. Or perhaps your organization has been using Local security and you want to keep it in place as you move to CA EEM.
When two files are listed as security realms in realms.xml, the first file is used during the authentication and authorization process. If you have two users named User A that have the same password, realms.xml will use the password it finds in the first file listed. For example, if you have listed users.xml before CEM45.xml, then realms.xml will have authentication performed using the password in users.xml.
In the case of Local realm user details such as email and phone number are not maintained in users.xml and CEM45.xml. In addition, the Local realm cannot maintain two users having the same name and same password. However, the Local realm can maintain two users having the same name but different passwords.
Similarly, if you have two users named User A that belong to different user groups in users.xml and CEM45.xml, then realms.xml will use the user group it finds in the first file listed. For example, let’s say you have listed users.xml before CEM45.xml. In users.xml, you have a user named Admin in the CEM System Administrator user group. In the CEM45.xml, you have a user named Admin in the CEM Analyst user group. In this case, then realms.xml will use the users.xml user group, and give the user named Admin privileges associated with the CEM System Administrator user group.
Configuring CA APM users and groups in users.xml
Define a username and password for each user and group.
When creating an
admin
user, keep in mind users and permissions are case insensitive. If a user logs in using the login name of
admin
or
Admin,
the permissions for that user role are applied.
The default CA APM user configuration defines the following users:
  • Admin with no password
  • Guest with Guest as the password
Follow these steps:
  1. Navigate to the
    <EM_Home>/
    config directory.
  2. Open the users.xml file.
  3. Define a user name using this user and group naming property.
    All XML tags are case-sensitive.
    For example, syntaxes for a user and group, see users.xml syntax for users and users.xml syntax for groups.
  4. Set a password for each user or group using this property.
    All XML tags are case-sensitive.
    password
    The user password.
    These rules apply to this property:
    • Any characters except quotation marks
    • By default, passwords are encrypted and not in clear-text or obfuscated (can optionally generate encoded passwords).
    • Password characters can be legal XML characters.
    • A password value can be empty.
    Best Practice: Follow the password policies for your organization.
    The passwords in the users.xml file that are used for Local authentication are stored as encrypted. You have the option of generating encrypted passwords using the SHA2Encoder utility, or letting Introscope generate them automatically. The SHA2 scripts that Introscope provides take input as plain text and output the encrypted form.
    • Follow the instructions in step 5 (Set an encrypted password manually), when these conditions apply to your situation:
      • You have already encrypted a number of users in
        users.xml.
      • You want to change only one or a few passwords.
    • Otherwise, change all user passwords back to clear text.
    • Follow the instructions in step 6 (Set a plain text password), when this condition applies to your situation
      • You are creating or changing many users and passwords at once.
  5. Set an encrypted password manually.
    1. Set
      plaintextPasswords="false"
      in the users.xml file.
    2. Run the appropriate script located in the
      <EM_Home>/tools
      directory.
      • For Windows,
        SHA2Encoder.bat
        <password>
      • For UNIX,
        SHA2encoder.sh
        <password>
      When running the SHA2Encoder.sh script, use a backslash to escape any special characters in your password. For example, if your password is
      pa$word
      , place a backslash before the dollar sign ("$") character to make the script run correctly. The correct command line is:
      ./SHA2Encoder.sh pa\$word
    3. Copy the generated encrypted password, and paste it into the second line of the users.xml file.
      For example,
      <user password="5b5ab9639b79259f54bc39515540aeaf" name="john"/>
  6. Set a plain text password and let Introscope automatically generate an encrypted password.
    1. Set
      plaintextPasswords="true"
      to the
      users.xml
      file.
      When you set
      plainTextPasswords="true",
      Introscope encrypts every password. Set all passwords to plain text otherwise Introscope encrypts already encrypted passwords.
    2. Set the password of every user to plain text.
      For example,
      <user password="John Jones Password" name="john"/>
      The next time the Enterprise Manager reads the users.xml file (either on start-up or when authenticating a user), it performs these actions:
    • The Enterprise Manager rewrites users.xml with the plain text passwords encrypted.
    • The Enterprise Manager resets the
      plainTextPasswords
      attribute to
      false.
  7. For more users or groups, repeat step 3 to define a user name and step 4 to set a password for each user.
  8. Save and close the users.xml file.
    Changes to contents of the users.xml file do not require an Enterprise Manager restart.
If there are any errors in the users.xml file, the Enterprise Manager does not start.
users.xml syntax for users
<users>
<user password="adb831a7fdd83dd1e2a39ce7591dff8" name="Guest"/>
<user password="" name="Admin"/>
</users>
users.xml syntax for groups
<groups>
<group description="Administrator Group" name="Admin">
<user name="Admin"/>
</group>
</groups>
users.xml syntax with encrypted passwords
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<principals xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" plainTextPasswords="false" version="0.3" xsi:noNamespaceSchemaLocation="users0.3.xsd">
<users>
<user password="adb831a7fdd83dd1e2a39ce7591dff8" name="Guest"/>
<user password="" name="Admin"/>
</users>
<groups>
<group description="Administrator Group" name="Admin">
<user name="Admin"/>
</group>
</groups>
</principals>
Configuring Introscope Domain Permissions in domains.xml
Permissions are applied when a CA APM user or group logs in. If changes are made while a CA APM user or group are logged in, the changes are not recognized until the next login attempt. This means if permissions are changed during a session, Introscope does not terminate the session.
Introscope permissions are dynamic; the Enterprise Manager checks the
domains.xml
and
server.xml
files whenever a login attempt is made. Thus, permissions changes can be made without restarting the Enterprise Manager.
Users are given permissions on domains in the following order:
  • All permissions listed in each domain that specify the user.
  • All permissions listed in each domain for any group to which the user belongs.
Additionally these rules are applied when accessing the domain:
  • The
    SuperDomain
    is treated like any other domain in terms of permissions.
  • Any permissions granted to a user or group with access to the SuperDomain also allows them to use these privileges in all user-defined domains.
  • One user or group can have multiple permissions for a single domain.
  • One user or group can have permissions in multiple domains.
Follow these steps:
  1. Using an XML editing program, open the domains.xml file in the <
    EM_Home
    >/config directory.
  2. For each domain, define permissions for a user or group, using these properties.
    If a user or group has multiple permissions, use one line for each user/permission pair.
    read
    Users or groups can view all agents and business logic in the domain.
    This permission includes tasks such as:
      • Viewing Investigator tree (which shows agents in the domain user has access to)
      • Viewing dashboards in the Workstation Console
      • Viewing metric and element data in the Investigator Preview pane, including default Top N Filtered Views for certain resources in the Investigator tree
      • Viewing any Management Module, agent, or element settings
      • Viewing alert messages
      • Refreshing historical data in a historical Data Viewer, and zoom in and out
      • Changing historical date range options for historical Data Viewer
      • Showing/Hiding metrics in a graph
      • Moving metrics in a Data Viewer to the back or front
      • Changing group and user preferences (setting a home dashboard, displaying management module names with dashboard names)
        Users or groups with read permission can see all commands in the Workstation. The commands that they do not have access to are disabled.
    write
    A user or group with write permission can do everything permitted by read permission can, and can also:
      • view all agents and business logic in the domain
      • create and edit dashboards
      • edit all monitoring logic in a domain
    run_tracer
    Users or groups can start a transaction trace session for an agent.
    This permission also requires the assignment of read permission.
    historical_agent_control
    Users or groups can mount and unmount agent/s.
    This permission also requires the assignment of read permission.
    live_agent_control
    Users or groups can shut off reporting for metrics, resources, and agents within a domain
    This permission also requires the assignment of read permission.
    dynamic_instrumentation
    User or group can perform dynamic instrumentation. For information about dynamic instrumentation, see Using Dynamic Instrumentation.
    thread_dump
    User or group can see and use the Thread Dumps tab.
    For information about using and configuring thread dumps, see APM Workstation and Configure Java Monitoring.
    full
    Users or groups have all possible permissions for the domain.
    All XML tags are case-sensitive.
  3. Repeat step 2 (For each domain, define…) for any additional users or groups.
  4. Save and close the domains.xml file.
    When a CA APM user logs in, the Enterprise Manager checks the domains.xml file to see if the user has the appropriate domain permissions.
If there are any syntax or other errors in the domains.xml file, the Enterprise Manager does not start.
Default domains.xml syntax for CA APM user and group domain permissions
In the default domain configuration:
  • the user or group,
    Admin
    has full permission in the SuperDomain.
  • the user or group,
    Guest
    has read (view only) permission in the SuperDomain.
SAP user or group permissions vary slightly and are as follows:
  • the user or group,
    sapsupport
    has full permission in the SuperDomain.
  • the user or group,
    Admin
    has read (view only) permission in the SuperDomain.
  • the user or group,
    sapsupport
    is a member of the CEM System Administrator and Admin groups, and is therefore granted permission to access the CEM console.
Here is the syntax for configuring user or group permissions for a domain:
<grant group="Admin" permission="full"/>
<grant user="Guest" permission="read"/>
domains.xml Syntax for Optional CA APM Domain Configuration
The following configured domain permissions example gives domain permissions to the following users:
  • bsmith,
    full
    permission in HRApplication domain
  • fjones,
    read
    and
    run_tracer
    permissions in HRApplication domain
  • jlo,
    write
    permission in SuperDomain
  • pdiddy,
    read
    permission in SuperDomain
  • swonder,
    dynamic_instrumentation
    permissions
  • cstevens,
    thread dump
    permissions
The domains.xml file would look like this example:
<?xml version="1.0" encoding="UTF-8"?>
<domains xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="domains0.3.xsd" version="0.3">
<domain name="HRApplication" description="">
<agent mapping="(.*)HRAppAgent(.*)" />
<grant user="bsmith" permission="full" />
<grant user="fjones" permission="read" />
<grant user="fjones" permission="run_tracer" />
<grant user="swonder" permission="dynamic_instrumentation" />
<grant user="cstevens" permission="thread_dump" />
</domain>
<SuperDomain>
<agent mapping="(.*)"/>
<grant user="jlo" permission="write"/>
<grant user="pdiddy" permission="read"/>
</SuperDomain>
</domains>
Configuring Enterprise Manager server permissions in server.xml
These server permissions are defined for activities relating to operation of the Enterprise Manager.
  • shutting down the Enterprise Manager
  • publishing MIB files
  • accessing the APM Status console
Follow these steps:
  1. Using an XML editing program, open the server.xml file in the
    <EM_Home>
    /config directory.
  2. Define permissions for each CA APM user or group, using these properties as appropriate.
    : All XML tags are case-sensitive.
    shutdown
    Users or groups can shut down the Enterprise Manager.
    publish_mib
    A user or group can publish SNMP collection data to an MIB.
    To have an MIB to publish, a user must create an SNMP Collection. This task requires write access to the domain to which the SNMP Collection is saved.
    apm_status_console_control
    Users or groups can see the APM Status alert icon, use the APM Status console, and run APM Status console CLW commands..
    Users who want to view active clamp metric information in the metric browser tree must have domains.xml SuperDomain permission.
    full
    Users or groups have all possible Enterprise Manager server permissions..
  3. Repeat step 2 (Define permissions for each CA APM user…) for any additional users.
  4. Save and close the server.xml file.
    If there are any syntax or other errors in the server.xml file, the Enterprise Manager does not start.
server.xml syntax for server permission
Here is the syntax for configuring user permissions for a server:
<grant user="username" permission="full">
A user or group can have multiple permissions for the Enterprise Manager. To grant a multiple permissions, use one line for each user/permission or group/permission pair.
server.xml syntax for default server configuration
In the default server configuration, the "Admin" user or group has full permission.
server.xml syntax for optional server configuration
This example shows how to give different permissions to different CA APM users:
  • bsmith,
    shutdown
    permission
  • tjones,
    publish_mib
    permission
  • cstevens,
    apm_status_console_control
    permission
The server.xml file looks like this example:
<?xml version="1.0" encoding="UTF-8"?> <server xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="users0.1.xsd" version="0.1">
<grant user="bsmith" permission="shutdown" />
<grant user="tjones" permission="publish_mib" />
<grant user="cstevens" permission="apm_status_console_control" />
</server>