CSA: Security, Passwords, LDAP, SSL, SSO, XSS, and FIPS

Manage security; including database server passwords, enable SSL, integrate with LDAP servers, and configure SSO.
ccppmop144
Manage security; including database server passwords, enable SSL, integrate with LDAP servers, and configure SSO.
2
 
Manage Database Server Passwords
Use a server password to access a single server. If the server is in a cluster, the server password does not grant access to other servers in the cluster.
Best Practice:
Change server passwords on each server regularly to minimize the risk of unauthorized access using a server password. Restart the services after you change certain passwords, such as the database server password.
Change the server passwords in the following places:
  • Database Server.
    See your third-party database documentation for more information.
  •  
    Clarity Project and Portfolio Management (PPM)
     properties.
To protect a server password file further, you can encrypt the password file.
Server Password Encryption
You can enable the AES encryption of server passwords through the properties.xml file. This encryption method requires that you to use a separate password (key) when encrypting the passwords in properties.xml. Keep this unencrypted key secure.
The advantage of server-side encryption is that you only have to secure one key, which is stored in a file accessible by the server. The key is only required at server startup. After 
Clarity Project and Portfolio Management (PPM)
is running, you can further secure the key file with another layer of encryption. If the file resides on removable storage, you can detach and lock the file in a safe.
The following procedure provides two key options:
  • System Key
    This option uses a hard-coded key that ships with the product. This option is the less secure of the two options. If the key for one 
    Clarity Project and Portfolio Management (PPM)
    installation becomes known, the key for all 
    Clarity Project and Portfolio Management (PPM)
    installations is known. This option discourages casual observers. If an employee is looking at the system key for innocent reasons, the employee does not see any passwords. However, an intruder trying to gain access to the system who has already gained access to files on the server can probably decrypt the passwords.
  • Custom Key
    This option requires that you create a key file and make it accessible to all servers running 
    Clarity Project and Portfolio Management (PPM)
    . The key file is properly secured so an intruder would be faced with the practically impossible task of decrypting the passwords without a key.
When you enable the server password encryption, any clear-text passwords in properties.xml automatically are encrypted the next time 
Clarity Project and Portfolio Management (PPM)
accesses the file. If you enable encryption and you edit properties.xml directly, you can enter passwords in clear text. The next time that the file is accessed, for example, when a service is deployed or started, the clear-text passwords are encrypted.
Encrypt Server Passwords
To encrypt server passwords, create a valid key file that it is accessible to the server and that contains the properties file. Each server must have access to either the key file (over the network) or a copy of it (on the server local disk).
Follow these steps:
  1. Log in to CSA.
  2. Open Home and click Servers.
    The servers page appears.
  3. Click the name of the server.
  4. Click the Security sub tab.
  5. Do one of the following tasks:
    • To enable encryption using a system key, select the Using System Key option at the Encrypt Passwords field.
    • To enable encryption using a custom key file, select the Using Custom Key File option. Then, enter the full path and file name to your custom key file in the Key File field.
      If you encrypt passwords with a custom key file, change the custom key file. Otherwise, your passwords are lost (cannot be decrypted). In this case, you must reenter the passwords.
  6. Save the changes.
Change Database Server Passwords
Follow these steps:
  1. Change your database server password on the database.
    See your third-party database documentation for more information.
  2. Change the database server password in CSA to the new password that you entered.
Change Database Server Password in CSA
Follow these steps:
  1. Log in to CSA.
  2. Stop the CA PPM Application (app) and CA PPM Background (bg) services by completing the following actions:
    1. Open Home, and click All Services.
    2. Select the check boxes next to CA PPM Application and CA PPM Background, and click Stop.
      The services are stopped.
  3. Open Home, and click Servers.
  4. Click the Properties icon to change the password for the server.
  5. Select the Database sub tab.
  6. In the Internal Connection: Niku section, complete the following fields, and save:
    • Password
      Enter a new password.
    • Confirm Password
      Enter the password again.
  7. Restart the CA PPM Background (bg) and CA PPM Application (app) services by completing the following actions:
    1. Open Home, and click All Services.
    2. Select the check boxes next to CA PPM Background (bg) and CA PPM Application (app), and click Start.
Enable Secure Sockets Layer (SSL) in Apache Tomcat
This information only applies to implementations that use the Apache Tomcat application server. For other servers, see your third-party vendor documentation.
SSL is a protocol for transmitting data between nodes. The protocol uses a cryptographic method to protect data from unauthorized access that is based on two keys: a public key that is known to everyone and a private (secret) key that is known only to the message recipient. When HTTP is used with SSL, it is referred to as HTTPS.
When SSL is enabled on the application service, all data moving between client applications (such as a web browser or Open Workbench) is encrypted. The data is encrypted before it is sent and decrypted before it is received. Without the SSL encryption, an unauthorized entity could read the data and could steal sensitive information such as user names and passwords.
Create Keystore Files
For testing purposes, use the private key that is included with 
Clarity Project and Portfolio Management (PPM)
. Before you place a system into production, create a keystore file for your private key and distribute the file to all application servers.
If you have a keystore file created using a process other than the one outlined here, you can still use the keystore file with 
Clarity Project and Portfolio Management (PPM)
.
Follow these steps:
  1. Generate a public and private key pair.
  2. Obtain a certified certificate.
  3. Import the reply from the certificate authority and replace your self-signed certificate with a chain of certificates.
  4. Distribute the file to all application servers.
Create Certificate Signing Requests (CSRs)
For production systems, replace the test certificate with a real, certified certificate. To obtain a certified certificate, create a certificate signing request (CSR) and send it to a certificate authority. The certificate authority generates a real certificate that authenticates your public key.
Use the Java command
keytool
to create the CSR. These steps provide the required Java parameters.
See the Oracle website for complete information about the parameters for this Java command.
Follow these steps:
  1. On the 
    Clarity Project and Portfolio Management (PPM)
     application server, open a command prompt, and issue the following command:
    keytool -certreq -keystore /<Clarity Home Directory>/config/.keystore -keyalg RSA -file ca_ppm.csr
  2. Define the following values:
    • -certreq
      Generates a certificate signing request (CSR).
    • keystore
      Specifies the path and filename of the keystore file. By default the keystore is named 
      .keystore
      and is located in the <Clarity Home Directory>/config/ directory.
    • keyalg
      Specifies the algorithm (RSA) to use when generating the key pair.
    • file
      Specifies the name (caclarityppm.csr) of the generated certificate request file.
  3. Using your web browser, go to your certificate authority website, and provide the contents of the CSR file you generated.
    Use the process that your certificate authority specifies. Your CSR is provided to you by your certificate authority.
  4. Copy the contents of the new certificate into a file on the 
    Clarity Project and Portfolio Management (PPM)
     application server (for example, caclarityppm.cer).
    Your private key remains unaffected.
Install Certificate Signing Requests
Import the reply from the certificate authority and replace your self-signed certificate with a chain of certificates. At the bottom of the chain is the certificate that the certificate authority issues to authenticate your public key. The next certificate in the chain is one that authenticates the certificate authority public key.
Use these steps to create a keystore file containing your private key which is paired with the signed certificate from your certificate authority.
Follow these steps:
  1. Open the 
    Clarity Project and Portfolio Management (PPM)
     application server, open a command prompt, and issue the following command:
    keytool -import -keystore /<Clarity Home Directory>/config/.keystore -keyalg RSA -file ca_ppm_source.cer -trustcacerts
    You may be required to import your certificate authority’s root intermediate certificate into your keystore file before you import your certificate. See your certificate authority third-party documentation for more information.
  2. Enter the keystore password and press Enter.
  3. Enter
    yes
    .
Distribute the Keystore File to Application Servers
If you have more than one server with application services, distribute the keystore to all servers.
Follow these steps:
  1. Log in to CSA.
  2. Stop all services by completing the following actions:
    1. Open Home, and click All Services.
    2. Select all the services, and click Stop.
  3. Open Distribute, and click Distribute All.
  4. Check the box next to all servers, and click Distribute.
  5. Restart all services by completing the following actions:
    1. Open Home, and click All Services.
    2. Select all the services, and click Start.
    The keystore file is distributed to the servers with application services.
Set the Keystore File Location and Password
Repeat these steps for each server in the cluster.
Follow these steps:
  1. Log in to CSA.
  2. To change the server, click the Properties icon.
  3. Click the Security sub tab.
  4. Complete the following fields, and save:
    • SSL Keystore
      Enter the location of the keystore file. If you leave the field empty, the default value of
      <Clarity Home Directory>/config/.keystore
      is used.
    • SSL Password
      Enter the keystore password (the default value is
      keystore
      ).
    • Confirm Password
      Enter the keystore password again.
  5. Stop and restart all services by completing the following actions:
    1. Open Home, and click All Services.
    2. Click the Select All icon to select all services, and click Stop.
    3. Click the Select All icon to select all services, and click Start.
Create Private Keys
The Java command
keytool
is used to generate a public and private key pair. These steps provide the required Java parameters.
For complete information about the parameters for this Java command, see the Oracle website.
If you have a keystore file that is created using another process, you can also use the file with 
Clarity Project and Portfolio Management (PPM)
.
Follow these steps:
  1. Open the 
    Clarity Project and Portfolio Management (PPM)
     application server, open a command prompt, and generate a public and private key pair by issuing the following command:
    keytool -genkey -keystore /<Clarity Home Directory>/config/.keystore -keyalg RSA -storepass keystore
  2. Define the following values:
    • -genkey
      This option generates a keystore if one does not exist. The keystore contains the public and dummy public key.
    • keystore
      Specifies the path and filename of the keystore file. By default the keystore is named 
      .keystore
      and is located in the
      /<Clarity Home Directory>/config/
      directory.
    • keyalg
      Specifies the algorithm that you use when generating the key pair (RSA in this example).
    • storepass
      The password that is used to protect the keystore (which must be at least six characters). This password is provided to all commands that access the keystore.
  3. When prompted, enter the appropriate information about your organization.
  4. Press Enter when prompted to enter the key password. The key password and the keystore password must be the same.
Enable SSL for 
Clarity Project and Portfolio Management (PPM)
Servers
The SSL Handling setting determines how the application behaves regarding SSL. The setting contains the following options:
  • Derive from Port Settings (implied)
    Derived from whether web server ports are enabled or disabled. This setting emulates SSL behavior from earlier releases (before Version 13.0).
  • SSL is used but processed externally (external)
    Specifies that the load balancer or other prior endpoint terminates the SSL outside of the app server.
  • Switch to HTTPS only for sensitive pages (hybrid)
    Specifies that 
    Clarity Project and Portfolio Management (PPM)
     actively switches between HTTP and HTTPS for secure and nonsecure pages.
  • Support both HTTP and HTTPS without switching (both)
    Specifies both HTTP and HTTPS are enabled. Do not try to switch between the two.
  • Support only HTTPS (full)
    Specifies all SSL. Everything is encrypted. Switch to SSL if necessary.
  • Support only HTTP (none)
    Specifies no SSL. Everything is in the clear.
These steps explain how to set up the SSL handling with the option Support only HTTPS. If you select Derived from Port Settings as your SSL Handling option, the following extra field settings for each application instance are required:
  • HTTP Enabled
    Clear the check box.
  • HTTPS Enabled
    Select the check box.
Complete these steps for all the servers for which you want to enable SSL.
Follow these steps:
  1. Log in to CSA.
  2. Open Home, and click All Services.
  3. Click the name of the server that you want to configure.
  4. Click the Properties tab.
  5. Click the Application sub tab.
  6. In the Application Server section, complete the following field:
    • SSL Handling
      Select the option that is named
      Support only HTTPS
      .
  7. In each Application Instance
    section that is associated with the server, complete the following fields:
    • HTTPS Port
      Enter the port that you want to use for the HTTPS traffic.
    • HTTPS Entry URL
      Enter the HTTPS URL (including the port).
      Example:
      https://clarity.mycompany.com:8443
  8. Save your changes.
  9. Stop and restart the application services by completing the following actions:
    1. Open Home, and click All Services.
    2. Select each service that you want to stop, and click Stop.
    3. Select each service that you want to restart, and click Start.
Enable SSL for Password-Protected Pages
You can enable SSL for only those pages that contain user passwords. With this configuration, users are automatically redirected between secure and insecure pages in the application. The redirection is made possible by enabling HTTP and HTTPS simultaneously.
With this configuration, both ports on the UNIX operating systems must be greater than 1024. As an exception, you can use the regular port numbers if you use a SUDO command to launch the services with root-like permissions. This exception does not apply when using load balanced or proxied installations. In those cases, use custom port ranges. In non-production environments, you can still choose not to use a load balancer (with optional SSL offloading). You could still use the traditional ports less than 1024.
Follow these steps:
  1. Log in to CSA.
  2. Open Home, and click Servers.
  3. Click the Properties icon of the server you want to configure.
  4. Click the Application sub tab.
  5. In the Application Server section, complete the following field:
    • SSL Handling
      Select the option
      Switch to HTTPS only for sensitive pages
      .
  6. In each Application Instance
    section that is associated with the server, complete the following fields:
    • HTTP Enabled
      Select the check box.
    • HTTPS Enabled
      Select the check box.
    • HTTPS Port
      Enter the port that you want for HTTPS traffic.
      For UNIX, the HTTP and HTTPS port numbers must be greater than 1024 unless you use a SODU command.
    • HTTP Entry URL
      Enter the HTTP URL (including port).
      Example:
      http://ca_ppm.mycompany.com:8080
    • HTTPS Entry URL
      Enter the HTTPS URL (including port).
      Example:
      https://ca_ppm.mycompany.com:8443
  7. Configure more servers.
  8. Stop and restart each application service:
    1. Click the Services tab.
    2. Select each service that you want to stop, and click Stop.
    3. Select each service that you want to restart, and click Start.
Configure 
Clarity Project and Portfolio Management (PPM)
to Work with SSL Off-loaders
On an SSL application service, data moving between client applications is encrypted before being sent, and the data is decrypted before being received. This encryption can cause slower performance.
If an external SSL off-loader such as a load balancer or a reverse proxy is used, the SSL off-loader encrypts HTTP traffic for 
Clarity Project and Portfolio Management (PPM)
. The off-loader communicates with the client using HTTPS. This setup can provide a performance improvement but requires some configuration in both the off-loader device and in 
Clarity Project and Portfolio Management (PPM)
.
Ensure that any SSL off-loader that you use has a URL-rewriting function that is enabled.
Follow these steps:
  1. Log in to CSA.
  2. Open Home, and click Servers.
  3. Click the Properties icon for the server that you want to configure.
  4. Click the Application sub tab.
  5. In the Application Server section, complete the following field:
    • SSL Handling
      Select the option that is named
      SSL is used but processed externally.
  6. For each application instance other than the 
    Clarity Project and Portfolio Management (PPM)
     application server instance, complete the following settings:
    • HTTP Enabled
      Specifies that HTTP is used to communicate. Select the check box.
    • HTTP Entry URL
      Indicates the URL that you want to use for traffic between 
      Clarity Project and Portfolio Management (PPM)
      and a client. An SSL off-loader becomes the front end to 
      Clarity Project and Portfolio Management (PPM)
      similar to the way a load balancer is the front end in a multiple-server environment. Because the SSL off-loader URL is secure, enter an HTTPS URL in this field using the following format:
      https://<hostname>:CA Portal.
    • HTTPS Enabled
      This check box does not apply when you are using an SSL off-loader. Clear this check box.
  7. Save the changes.
Integrate 
Clarity Project and Portfolio Management (PPM)
with Lightweight Directory Access Protocol (LDAP) Servers
A Lightweight Directory Access Protocol (LDAP) interface to authorize access across all applications can be beneficial. A central directory server controls access so that users can have one user name and password for all applications. The following options are supported:
  • LDAP v2 (simple) protocol uses a small subset of LDAP functionality including authentication (clear text or SSL), binding, and searching.
  • LDAP v3 control for paged-results as defined in RFC 2696.
To synchronize users between your directory server and 
Clarity Project and Portfolio Management (PPM)
, users are fetched from the directory server in a batch. The LDAP configuration settings of 
Clarity Project and Portfolio Management (PPM)
specify the batch size.
Cookies that are session-based carry a token that is used to access session data. The token is persisted in the cache for single application environments or in a database for clustered environments. The user web browser must accept cookies from 
Clarity Project and Portfolio Management (PPM)
, which are session-based, so they are not written to disk. When the user logs out, session information in the database and cache that correspond to the cookie are deleted.
When you integrate 
Clarity Project and Portfolio Management (PPM)
with an LDAP server, you get the following benefits:
  • Simplification of the user name and password administration. IT only has to manage one user name and password pair for a user.
  • Authentication support. IT only has to support one place where users can have authentication problems.
  • Improvement in the usability. Users only have to remember one user name and password.
  • Improvement in the user management. The user name and email information can be stored in LDAP.
  • Security enhancement. Using one user name and password makes it easier to use complex passwords and to change them more often. The likelihood of choosing a familiar password is reduced when there is only one password to remember.
The LDAP - Synchronize New and Changed Users job synchronizes LDAP entries. The job then stores the last date and time the job ran successfully and stores information in the MN_DIRECTORY_SERVERS database table. During the next background job run, the job synchronizes entries. The job synchronizes only recently created or changed user entries where the timestamp is greater than the value found in the CMN_DIRECTORY_SERVERS.LAST_SYNC_DATE property.
Clarity Project and Portfolio Management (PPM)
 does not verify whether a user in a group or in a search that CSA specifies is active or inactive in LDAP. 
Clarity Project and Portfolio Management (PPM)
checks only whether a user is present in a 
Clarity Project and Portfolio Management (PPM)
group or whether an attribute being searched for is present in 
Clarity Project and Portfolio Management (PPM)
.
Nested 
Clarity Project and Portfolio Management (PPM)
groups are not recognized. Before you run LDAP synchronization jobs, ensure that users are associated with 
Clarity Project and Portfolio Management (PPM)
groups that the CSA search can find. Users in nested 
Clarity Project and Portfolio Management (PPM)
groups are not checked when the LDAP synchronization jobs are run.
A user who is deactivated on the LDAP server is deactivated in 
Clarity Project and Portfolio Management (PPM)
the next time the synchronization job runs. If a user is reactivated on the LDAP server, the user is not reactivated in 
Clarity Project and Portfolio Management (PPM)
; you are required to reactivate the resource.
Configure 
Clarity Project and Portfolio Management (PPM)
to Work with LDAP
Clarity Project and Portfolio Management (PPM)
 does not recognize nested groups in LDAP. Before you run the
LDAP - Synchronize New and Changed Users
job or the
LDAP - Synchronize Obsolete Users
job, ensure that your users are associated with a group that the CSA search can find. Users in groups that are nested inside the LDAP 
Clarity Project and Portfolio Management (PPM)
 group are not checked when the LDAP synchronization jobs are run.
Before you implement LDAP, select a compatible LDAP server.
Set Up 
Clarity Project and Portfolio Management (PPM)
for LDAP Authentication
You must set up 
Clarity Project and Portfolio Management (PPM)
for LDAP authentication for each server that is running an application service. To complete these steps successfully, you must understand how to configure an LDAP server. If you have a cluster of 
Clarity Project and Portfolio Management (PPM)
servers, repeat these steps on each server in the cluster.
Follow these steps:
  1. Create a resource as the test user you can use to access 
    Clarity Project and Portfolio Management (PPM)
    as an LDAP user.
    The test user must have the same user ID in 
    Clarity Project and Portfolio Management (PPM)
    as the user LDAP sAMAccountName in Microsoft Active Directory or the UID for other LDAP implementations.
  2. Decide how to define the LDAP users who are granted access to 
    Clarity Project and Portfolio Management (PPM)
    .
    You can enable the group authentication by specifying a group, or by creating an attribute/value combination on the LDAP, or both. You can define this setting from the security
    Server: Properties
    page in CSA.
  3. Define the LDAP server properties.
  4. Set up
    Clarity Project and Portfolio Management (PPM)
     to authenticate.
  5. Stop and restart all 
    Clarity Project and Portfolio Management (PPM)
    services.
Define the LDAP Server Properties
You can define the LDAP server properties in CSA.
Follow these steps:
  1. Log in to CSA.
  2. Click the Properties icon of the server you want to set up.
  3. Click the Security sub tab.
  4. In the
    LDAP Server section, complete the fields:
    • URL
      Defines the LDAP server URL. If your LDAP server is SSL-enabled, use the LDAPS protocol in the URL (rather than the default LDAP protocol).
    • Root Context
      Defines the LDAP naming context, for example: "ou=People, dc=niku, dc=com".
    • Search User
      Defines the user name with the appropriate credentials for binding to the LDAP server.
    • Password
      Defines the password and confirms it in the Confirm Password field.
    • Search Filter
      Defines the search filter string (as defined in RFC 2254).
    • Date/Time Format
      Defines the date and time format that the LDAP server uses.
    • Group Name
      Enables the group authentication. Enter the group name and at the Group Identifier field, enter the group ID.
    • Allow non-LDAP users
      Indicates that access to
      Clarity Project and Portfolio Management (PPM)
      is allowed using alternate authentication methods.
  5. Click Save.
  6. Stop and restart all 
    Clarity Project and Portfolio Management (PPM)
    services by completing the following actions:
    1. Open Home, and click All Services.
    2. Click the Select All icon to select the check box next to each service, and click Stop.
    3. Click the Select All icon to select the check box next to each service, and click Start.
  7. Click Save.
Set Up 
Clarity Project and Portfolio Management (PPM)
to Authenticate
You can set up 
Clarity Project and Portfolio Management (PPM)
to authenticate the user information about the LDAP server when users log in.
Follow these steps:
  1. Log in to the CSA.
  2. Open Home, and click Servers.
  3. Click the Properties icon for the server you want to set up.
  4. Click the Application sub tab.
  5. In the Application Server section, select Use LDAP, and save.
LDAP Synchronization
The following LDAP synchronization jobs work together to synchronize 
Clarity Project and Portfolio Management (PPM)
with LDAP:
  • LDAP - Synchronize New and Changed Users job
    This job synchronizes LDAP records with 
    Clarity Project and Portfolio Management (PPM)
    records by synchronizing the users that you add to the LDAP 
    Clarity Project and Portfolio Management (PPM)
     group. The job also makes the users active on the 
    Clarity Project and Portfolio Management (PPM)
    server. If you use the search filter option and you change an attribute to one used by 
    Clarity Project and Portfolio Management (PPM)
    , the user is activated on the 
    Clarity Project and Portfolio Management (PPM)
    server. The activation occurs the next time that the job runs. The job then stores the last date and time the job ran successfully in the CMN_DIRECTORY_SERVERS database table. The job synchronizes only recently created or changed user entries. For the synchronization, the timestamp has to be greater than the value found in the CMN_DIRECTORY_SERVERS.LAST_SYNC_DATE field.
  • LDAP - Synchronize Obsolete Users job
This job inactivates users that you remove from the LDAP 
Clarity Project and Portfolio Management (PPM)
 group on the LDAP server or whose record no longer contains the chosen search attribute. This job does not verify whether a user found in the LDAP 
Clarity Project and Portfolio Management (PPM)
 group or in the search that CSA specifies is active or inactive in LDAP. To inactivate users in 
Clarity Project and Portfolio Management (PPM)
using the job, remove the users from the LDAP 
Clarity Project and Portfolio Management (PPM)
 group or remove the search attribute that is specified in CSA. These synchronization jobs function properly if you have correctly configured the LDAP Server and LDAP Attribute Mapping sections in CSA.
You are required to select a schedule for each job.
Best Practice:
Run these jobs nightly.
To synchronize the database with the directory server, delete all rows from CMN_DIRECTORY_SERVERS database table and run the background job again. You can also run the job for a specific group so that only the records for those users are affected.
Force the LDAP - Synchronize New and Changed Users Job to Perform a Full Synchronization
You may need to override the behavior of the
LDAP - Synchronize New and Changed Users
job, and you can force a full synchronization.
Follow these steps:
  1. Delete the row from CMN_DIRECTORY_SERVERS database table.
  2. Run (or schedule) the job again.
Troubleshoot LDAP
Here are some common LDAP issues and the ways to address them:
  • To debug the LDAP authentication process, enable debug messages that the security component logs. Stop all background services except the one on which you are enabling debug messages. Restart the background service so that the changes take effect and see the log file (bg-ca.log).
  • When you review the 
    Clarity Project and Portfolio Management (PPM)
    logs for error messages, LDAP-specific error codes can display.
    See your third-party LDAP documentation for descriptions of LDAP-specific error codes.
  • If you cannot log in to 
    Clarity Project and Portfolio Management (PPM)
    using an LDAP user name and password, consider this information:
    • Are you using an active LDAP account that also exists as an active account in 
      Clarity Project and Portfolio Management (PPM)
      ?
    • Have you enabled the LDAP configuration by selecting the Use LDAP field on the application server properties page in the CSA?
    • Did you enter the correct user ID in the Search User field and the correct password in the Password field on the security server properties page in the CSA?
    • Refer to the log files for more specific messages.
    • Processing time for the
      LDAP - Synchronize Obsolete Users
      job and the
      LDAP - Synchronize New and Changed Users
      job depends on the number of users that are loaded from the directory service into 
      Clarity Project and Portfolio Management (PPM)
      . Specifically, large numbers can slow processing times.
Troubleshoot LDAP Sync Jobs
When an LDAP synchronization job or authentication process does not work as expected, do any of the following tasks:
  • Check the LDAP synchronization log files in the /niku/Clarity/logs/ldapsync directory.
  • Check the *users*.xml file. This file contains a list of user names that are extracted from the LDAP server. If this file is missing, the communication between 
    Clarity Project and Portfolio Management (PPM)
     and the LDAP server was unsuccessful.
  • Check the *sync*.xml file. This file contains the results from a gateway user import session. If this file is missing, the communication between 
    Clarity Project and Portfolio Management (PPM)
     and the gateway was unsuccessful.
  • Enable debug messages in the security component by completing the following steps:
    1. Edit
      bg-logger.xml
      and add the
      com.niku.security
      category.
    2. Set the priority to
      debug
      .
    3. Restart the CA PPM background (bg) service so that the changes take effect.
    4. Check the bg-ca.log file.
    5. If you have multiple bg services in your cluster, shut down all but one. Having only one bg service ensures that the job is running on the server that you are debugging. You can also enable debugging on all the services individually.
Check the LDAP Synchronization Logs
Check the LDAP synchronization transaction logs in the following directory:
<Clarity Home Directory>/logs/ldapsync
Log files that are related to New and Changed Users jobs are:
  • ldapusers_nm_*.xml: List of users that are found in the directory server to be synchronized with 
    Clarity Project and Portfolio Management (PPM)
    .
  • ldapsync_nm_*.xml: List of the Success/Error/Warning messages for this sync job.
Log files that are related to the
LDAP - Synchronize Obsolete Users
job are:
  • ldapusers_ia_*.xml: List of the users to be inactivated in 
    Clarity Project and Portfolio Management (PPM)
    .
  • ldapsync_ia_*.xml: List of the Success/Error/Warning messages for this sync job.
Enable Debugging Messages
The security component logs debugging messages. Stop all CA PPM Background (bg) services in your implementation except the one on which you are enabling debug messages. Restart the CA PPM Background (bg) service so that the changes take effect and see the log file (bg-niku.log).
Follow these steps:
  1. Log in to CSA.
  2. Open Home, and click Servers.
  3. Click the Logs icon for the server you want to enable debugging messages.
  4. Click the Edit Configuration sub tab.
  5. In the Categories section, click Add Category.
  6. Enter the following value for the new line item:
    • Name
      Enter
      com.niku.security
      .
    • Priority
      Select Debug from the drop-down.
  7. Save the changes.
    The debugging messages are enabled.
Configure LDAP and SSL
When an LDAP server is running with the Secure Socket Layer (SSL), you are required to configure LDAP and SSL. The 
Clarity Project and Portfolio Management (PPM)
administrator installs the trusted security certificate for the LDAP server on the computer that is running the CA PPM Background (bg) services. To install the certificate, use the keytool that ships with the Java 7 JDK.
Issue the following commands from the command prompt:
keytool -import -v -trustcacerts -alias <alias> -file <certificate file name> -keystore cacerts
Example:
$cd $JAVA_HOME/jre/lib/security $keytool -import -v -trustcacerts -alias NikuLdapServer -file TrustedRootCert.der -keystore cacerts
Configure Single Sign-On (SSO)
Single sign-on (SSO) is an authentication process that allows users access to multiple systems using a single username and password. With SSO, once the server uses LDAP directory information to authenticate a user identity, it allows access to the requested information according to the user access privileges.
You can set up SSO to integrate 
Clarity Project and Portfolio Management (PPM)
with the internal portal application to which the user authenticates. SSO takes away the need for users to enter their username and password repeatedly when switching between applications. The portal application has links (URLs) to other internal applications. Once the portal application is invoked, users are not prompted with authentication dialogs but are taken directly into the application. The portal application has an SSO plug-in that directs users to log in to the portal, then takes them to the appropriate application. This way, users cannot bookmark a page and then later return to it without first logging in.
SSO provides the following benefits:
  • Username/Password Administration. IT only has to manage one username/password for a user.
  • Authentication Support. IT only has to support one place where users can have authentication problems.
  • Usability. Users only have to remember one username and password, and only have to log in once.
  • Security. One username and password make it easier to use complex passwords and to change them more often. The chance of a user choosing a familiar password is reduced when there is only one password to remember.
Best Practice
If you are using CA SiteMinder or other SSO software, set the configuration to allow angle bracket characters (< and >) in the URL. For example, if you are using SiteMinder, disable CssChecking. Otherwise, a URL that contains angle brackets produces an error when 
Clarity Project and Portfolio Management (PPM)
 passes it. Angle brackets can appear in a URL, possibly created by a process that uses conditions such as <, <=, >, or >=).
Follow these steps:
  1. Configure your SSO server and proxy server to point at 
    Clarity Project and Portfolio Management (PPM)
    and to have it pass an authentication token that contains a valid 
    Clarity Project and Portfolio Management (PPM)
    username.
    Configure the SSO server so that the entry URL is:
    http://<server>/niku/nu#action:npt.overview
  2. Log in to CSA, and from Home, click Servers.
  3. Click the name of the server you want to set up.
  4. Click the Application sub tab.
  5. To use LDAP, in the Application Server section, select the Use LDAP checkbox.
    If LDAP is enabled, nonbrowser clients use the same user name and password.
  6. In the Application Instance section, select the Use Single Sign-On checkbox, and click Save.
  7. Click the Security tab.
  8. In the Encryption section, complete the following fields:
    • SSL Keystore
      Defines the path to the keystore file.
      Example:
      <pathtokeystore>/server.keystore).
    • SSL Password
      Defines the keystore password. Once entered, confirm at the Confirm Password field.
  9. In the LDAP Server section, complete the following fields:
    • URL
      Defines the LDAP server URL.
    • Root Context
      Defines the LDAP server naming context, for example: "ou=People, dc=niku, dc=com".
    • Search User
      Defines the user name with the appropriate credentials for binding to the LDAP server.
    • Password
      Defines the LDAP server password. Once entered, confirm it again at the Confirm Password field.
    • Batch Size
      Enables the synchronous operation. Set the batch size using the following criteria:
      • 0. Allows all results that are received from the server as they are generated.
      • A non-zero number. Messages are blocked until
        n
        messages are received from the server. The enumeration proceeds while more messages are queued.
      • The default batch size is 1. An enumeration of search results from a synchronous search operation returns messages as they are received from the server.
    • Search Filter
      Defines the search filter string (as defined in RFC 2254).
    • Date/Time Format
      Defines the date and time format that is used on the LDAP server.
    • Group Name
      Defines the group that is enabled for the group authentication.
    • Group Identifier
      Specifies the group ID for the group that is enabled for the group authentication.
    • Allow non-LDAP users
      Indicates if non-LDAP users are allowed to access the application using an alternative authentication method.
  10. In the LDAP Attribute Mapping section, complete the following fields:
    Username
    Specifies the attribute for the user name.
    First Name
    Specifies the attribute for the first name.
    Last Name
    Specifies the attribute for the last name.
    Full Name
    Specifies the attribute for the last name.
    Email Address
    Specifies the attribute for the email address.
    Modify Time Stamp
    Specifies the attribute for the modification of the time stamp.
  11. In the Single Sign-on section, complete the following fields:
    Token Name
    Specifies the HTTP cookie that 
    Clarity Project and Portfolio Management (PPM)
    accepts as a valid authentication token for initiating a user session.
    Token Type
    Specifies the token type. Values are: 
      Cookie.
    The token is contained in a cookie. 
      Header.
    The token is contained in the message header. 
      Parameter.
    The token is provided in a parameter.
    Logout URL
    Defines the fully qualified URL that displays when the user logs out.
    Authentication Error URL
    Defines the fully qualified URL that displays when the user cannot be authenticated.
  12. Save the changes.
  13. Restart the application, and log in to 
    Clarity Project and Portfolio Management (PPM)
    as an application administrator.
    The system settings page appears.
Use LDAP with SSO
You can use LDAP with Single Sign-On (SSO).
Best Practice:
While SSO does not require LDAP to be enabled, use LDAP with SSO for the following reasons:
  • Nonbrowser clients get most of the SSO benefits.
  • With SSO only, user information such as names and email must still be managed within 
    Clarity Project and Portfolio Management (PPM)
    . With LDAP, this data is kept in the directory server.
Use LDAP without SSO
SSO gives little extra benefit over LDAP. Users must enter their username and password to log in to 
Clarity Project and Portfolio Management (PPM)
, but every other benefit still applies with LDAP. The system configuration is much simpler for LDAP alone. With LDAP, there is no need for a proxy or SSO server, and only one 
Clarity Project and Portfolio Management (PPM)
instance is required.
Set Options for Cross-Site Scripting (XSS) Vulnerability
Cross-Site Scripting (XSS) attacks insert malicious scripts into otherwise trusted web sites. A cross-site scripting attacker uses a web application to send malicious code, generally in the form of a browser side script, to an end user. These attacks succeed when a web application uses input from a user in the output it generates without validating or encoding the input.
The end-user browser does not know that the script is malicious and executes the script. Because the browser thinks the script came from a trusted source, the malicious script can access any cookies, session tokens, or other sensitive information. To prevent XSS attacks, use XSS user input validation and XSS user input restrictions.
XSS User Input Validation
Clarity Project and Portfolio Management (PPM)
 validates that all user input that is sent back to the browser is safe from XSS. The product compares the user input to a set of string patterns that are commonly used for XSS. If any part of the user input matches one of the common patterns, 
Clarity Project and Portfolio Management (PPM)
 restricts (escapes) the XSS string in the user input.
The product restricts the XSS string by placing escape characters before and after the string. These characters are visible to the end user. The escape characters instruct the browser to ignore any script or HTML tag that is attached to the user input.
By default, the XSS detection is turned on. URL attributes and site links are exempt from this check. For more information about changing these settings, see Set XSS User Input Restrictions.
Set XSS User Input Restrictions
The user input that contains one of the common XSS patterns must be escaped before it is included in the output page. This output encoding ensures that the user input is treated as text and not active content that can be executed. Administrative options allow you to turn XSS restrictions (escaping) on or off.
To change the setting for any option, you execute database SQL statements.
Follow these steps:
  1. Access the CMN_OPTION_VALUES database table.
  2. Update the table entry for the particular option. For information about each option, see the option descriptions.
  3. Flush the cache.
XSS Restriction Option
This option restricts the XSS string in the user input if the string matches a pattern in the CMN.XSS.PATTERNS option. This system option applies to the entire 
Clarity Project and Portfolio Management (PPM)
 application, except the URL attributes and site links. You can set restrictions for URL attributes and site links through separate options.
  • RESTRICT.APP.XSS
    Values = True (restrictions are on), False (restrictions are off)
    Default = True
The HtmlPortlet content is not restricted (escaped). HTML portlets execute any script in HTML content, which is the expected behavior.
To change the RESTRICT.APP.XSS option, update the CMN_OPTION_VALUES database table using the following SQL statement:
update cmn_option_values set value='false|true' where option_id = (select id from cmn_options where option_code=' RESTRICT.APP.XSS')
URL Attribute Value Option
This option restricts the URL attribute value (that you created with Studio) if the value matches a pattern in the CMN.XSS.PATTERNS option.
  • RESTRICT.URL.ATTR.XSS
    Values = True (restrictions are on), False (restrictions are off)
    Default = False
To change the RESTRICT.URL.ATTR.XSS option, update the CMN_OPTION_VALUES database table using the following SQL statement:
update cmn_option_values set value='false|true' where option_id = (select id from cmn_options where option_code=' RESTRICT.URL.ATTR.XSS')
Site Links Option
This option restricts the Site Links entry value if the value matches a pattern in the CMN.XSS.PATTERNS option.
  • RESTRICT.SITE.LINKS.XSS
    Values = True (restrictions are on), False (restrictions are off)
    Default = False
To change the RESTRICT.SITE.LINKS.XSS option, update the CMN_OPTION_VALUES database table using the following SQL statement:
update cmn_option_values set value='false|true' where option_id = (select id from cmn_options where option_code=' RESTRICT.SITE.LINKS.XSS')
Common XSS Patterns Option
This option defines the string patterns that are commonly used for XSS. You can add values to this option to include more string patterns.
  • CMN.XSS.PATTERNS
    String patterns = </script> <script(.*?)> <script>(.*?)</script> alert(.*?) eval\\((.*?)\\) expression\\((.*?)\\) javascript: onerror(.*?)= onload(.*?)= src[\r\n]*=[\r\n]*\\\"(.*?)\\\" src[\r\n]*=[\r\n]*\\\'(.*?)\\\'
To add patterns, access the CMN_OPTION_VALUES database table and include the new patterns in the CMN.XSS.PATTERNS option.
Example: Add the new pattern “onfocus” to the CMN.XSS.PATTERNS option
Oracle
CMN_OPTION_VALUES_INS_SP('CMN.XSS.PATTERNS','true','true','onfocus(.*?)=',1);
MSSQL
EXEC CMN_OPTION_VALUES_INS_SP 'CMN.XSS.PATTERNS','true','true','onfocus(.*?)=',1
External URLs
The externalUrl property is an optional application setting that provides support for external or federated authentication schemes in notification messages. When externalUrl is not specified, 
Clarity Project and Portfolio Management (PPM)
 notification messages that contain URLs use the standard entryUrl property. The standard entryUrl property points directly to the 
Clarity Project and Portfolio Management (PPM)
 server. The externalUrl property causes the request to first route to an external server which provides the login authentication for the session. The external server redirects the original request back to 
Clarity Project and Portfolio Management (PPM)
 using Single Sign On. This method ensures that the user does not have to log in to 
Clarity Project and Portfolio Management (PPM)
 directly. When the user clicks a notification link, the external authentication happens and the request is forwarded to 
Clarity Project and Portfolio Management (PPM)
. If the user is already logged in, the request is forwarded automatically without any interruption.
The external URL does not replace the standard entry URL; rather, it works with the standard entry URL. The two URLs build a compound URL that includes external and internal addresses, encoded to ensure that embedded URLs are passed correctly. The authentication route can include multiple servers so, generally, URLs include query parameters that tell each server where to redirect after processing the request.
The externalUrl property supports the following macros:
  • ${entryurl}
    Inserts the current entryUrl configuration property.
  • replace(regex,replacement,text)
    Replaces all instances of 'regex' with 'replacement' in 'text'.
  • encode()
    Replaces the text with UTF-8 encoded text.
Macros can be combined and nested.
Specify the restricted XML characters such as ampersands using the equivalent entity name (, &amp;). Failure to do this can prevent all 
Clarity Project and Portfolio Management (PPM)
 services from starting.
Example: Building an External URL
The authentication route for a particular environment determines the externalUrl. The authentication route includes specifically the addresses of each server in the route and the parameters that each server requires. Before you set this value, determine your route by gathering the information.
For example, consider the following environment:
  • Server 1
    Purpose
    : External Authentication Server
    Address
    : http://auth.somecompany.com
    Required Parameters
    : REDIRECT
    Description
    : Authenticates (invoking login if necessary), then redirects to the address specified in the REDIRECT parameter
  • Server 2
    Purpose
    : Internal Authentication Server
    Address
    : http://sso.mycompany.com
    Required Parameters
    : TARGET
    Description
    : Invokes internal Single Sign On then routes the request to the address specified in the TARGET parameter.
  • Server 3
    Purpose
    :
    Clarity Project and Portfolio Management (PPM)
    Application Server
    Address
    : http://clarity.mycompany.com
    Required Parameters
    : All standard 
    Clarity Project and Portfolio Management (PPM)
    parameters
    Description
    : Address specified in entryUrl.
To summarize, requests go first to http://auth.somecompany.com, which is the external identity management system. Then the requests go to the internal Single Sign On server at http://sso.mycompany.com, and finally requests go to the server at http://clarity.mycompany.com.
Follow these steps:
  1. The construction of the external URL starts when you by add the first stop, the external authentication server:
    externalUrl=http://auth.somecompany.com
    This server requires one parameter, REDIRECT, which tells the server where to route the request after processing. In this example, the request is to go to the Internal Authentication Server:
    externalUrl=http://auth.somecompany.com?REDIRECT=http://sso.mycompany.com
  2. The internal SSO server requires one parameter, TARGET, which contains the standard 
    Clarity Project and Portfolio Management (PPM)
     entry URL. The ${entryurl} macro automatically expands to the current entryUrl setting when notifications are sent:
    externalUrl=http://auth.somecompany.com?REDIRECT=http://sso.mycompany.com?TARGET=${entryurl}
  3. The external URL is almost complete, but there is one remaining step.
    The REDIRECT parameter for Server 1 contains characters that must be UTF-8 encoded so that they can be passed on a query string safely. The encode macro addresses that:
    externalUrl=http://auth.somecompany.com?REDIRECT=encode(http://sso.mycompany.com?TARGET=${entryurl})
    Server 2 also has a parameter that must be encoded:
    externalUrl=http://auth.somecompany.com?REDIRECT=encode(http://sso.mycompany.com?TARGET=encode(${entryurl}))
    The encode() macros are nested. The nesting causes the inner one to be double-encoded, which means the UTF-8 encoded text is encoded a second time. This double encoding is necessary because Server 1 decodes the entire REDIRECT parameter on the first stop, and Server 2 expects a UTF-8-encoded parameter. The encoding macro can be nested as many times as is necessary to ensure that the final parameter has the correct encoding.
The Request Lifecycle
When a new 
Clarity Project and Portfolio Management (PPM)
 email notification is generated, the externalUrl and entryUrl properties are used to generate an appropriate click-through URL for the event. The standard URL (without using externalUrl) can look like:
http://clarity.mycompany.com/niku/nu#action:timeadmin.currentTimesheet
With externalUrl enabled as in this example, the generated URL would look like:
externalUrl=http://auth.somecompany.com?REDIRECT=http%3A%2F%2Fsso.mycompany.com%3FTARGET%3Dhttp%253A%252F%252Fclarity.mycompany.com%252Fniku%252Fnu%2523action%253Atimeadmin.currentTimesheet
The previous example is a URL that points to Server 1, and a single parameter with the Server 2 and Server 3 addresses and properties UTF-8 encoded (the entry URL twice). When a user clicks this URL, the request is sent to Server 1 (http://auth.somecompany.com). Server 1 decodes the parameter (all of the text after REDIRECT=) into:
http://sso.mycompany.com?TARGET=http%3A%2F%2Fclarity.mycompany.com%2Fniku%2Fnu%23action%3Atimeadmin.currentTimesheet
Server 1 uses the URL to redirect to Server 2. The parameter string for Server 2 is still encoded even though the entire query string was decoded by Server 1. That example shows the effect of the double encoding. Server 2, in turn decodes the TARGET parameter to produce:
http://clarity.mycompany.com/niku/nu#action:timeadmin.currentTimesheet
The preceding URL is the final. The URL is decoded and ready for 
Clarity Project and Portfolio Management (PPM)
 to process. Along the way, Server 1 and Server 2 performed their authentication duties. When the request finally reaches 
Clarity Project and Portfolio Management (PPM)
, it contains the appropriate Single Sign On authentication token to identify the user. Aside from generating the correct URL when the notification is produced, 
Clarity Project and Portfolio Management (PPM)
 has no involvement in the authentication process.
Troubleshooting External URLs
The key to troubleshooting a problematic external URL is understanding the values each server in the chain expects. Once you know, you can ensure that the URLs and parameters are properly encoded at each point. You can manually verify a given notification URL using the following steps.
Follow these steps:
  1. Obtain a UTF-8 decoding utility. A simple utility can be downloaded.
  2. Generate a notification email using the current external URL setting.
  3. Examine the URL and verify that the first part of the URL points to Server 1. The first part of the URL includes everything up to the first question mark character.
  4. Discard everything up to and including the first question mark, leaving the parameter string that was passed to Server 1.
  5. Decode the remaining string once using the UTF-8 decoding utility.
    The decoded string represents the parameters that are passed to Server 1. Verify that the parameters are correct.
  6. Discard the parameter name (REDIRECT in our example), and verify that the first part of the URL points to Server 2. Again, everything up to the question mark is included in the first part of the URL.
  7. Once again, discard everything up to the question mark and then decode the remaining string once.
  8. Verify the following points:
    • The first part of the URL points to the 
      Clarity Project and Portfolio Management (PPM)
       server.
    • The remaining query string contains standard 
      Clarity Project and Portfolio Management (PPM)
       parameters.
    • The parameters are not encoded.
How does 
Clarity Project and Portfolio Management (PPM)
track user sessions?
A session-based cookie carries a token that is used to access the session data that is persisted in the following locations:
  • Cache (for a single app environment)
  • Database (for a clustered environment)
Does this place any limitations on our environment?
The end-user web browser must accept cookies from the 
Clarity Project and Portfolio Management (PPM)
application. The cookies are session-based, so they are not written to disk.
Are load balancers or clusters influenced by this technique?
Load balancing and clustering work fine with this technique. Many companies load-balance and cluster 
Clarity Project and Portfolio Management (PPM)
.
Can a session be hijacked inadvertently or deliberately?
To steal a user session maliciously, one would have to either snoop the HTTP traffic to pick out the headers containing the authentication cookie. This token, however, is valid only while the real user is logged in. Once the user logs out, session information in the database/cache that 
Clarity Project and Portfolio Management (PPM)
corresponds to the cookie value is deleted.
How can I keep session IDs out of logs?
As a security measure, you can configure 
Clarity Project and Portfolio Management (PPM)
 to prevent session ID values from appearing in your log files. To prevent these values from appearing, edit the logger.xml file. Replace the log pattern (%u:%s:%a) with the pattern (%U:%a).
The following examples show the results of using both log patterns in the logger.xml file.
Example: (%u:%s:%a)
This line of code shows how the pattern to display the session ID value appears in the logger.xml file.
<param name="ConversionPattern" value="%-5p %d{ISO8601} [%t] %c{2} (%u:%s:%a) %m\r\n"/>
This pattern produces records in a log file with the session ID value. The following record from the app-ca.log that shows the session ID value (bolded):
DEBUG 2014-08-18 19:52:02,949 [http-bio-80-exec-3] odf.view (clarity:admin:
5077018__8DF3B2A0-F398-4A4B-BC35-E9A012065CE0
:npt.overview) Adding view FILTER_VIEW_LOADER::USER:NIKU.ROOT to transient cache
Example: (%U:%a)
This line of code shows how the pattern to prevent the session ID value appears in the logger.xml file.
<param name="ConversionPattern" value="%-5p %d{ISO8601} [%t] %c{2} (%U:%a) %m\r\n"/>
This pattern produces a record in a log file without the session ID value. The following example is a record from the app-ca-service.log that shows no session ID value.
DEBUG 2014-08-18 19:52:02,494 [http-bio-80-exec-3] in.service (admin:npt.overview)
Clarity Project and Portfolio Management (PPM)
supports the additional logging patterns in the following table if the layout is set to NikuLayout in the logger.xml for an appender.
 
Pattern Option
Purpose
u
Creates the user ID with the tenant ID in the log.
Example: (%u) creates the output (clarity:admin) in the log.
U
Creates the user ID in the log.
Example: (%U) creates the output (admin) in the log.
s
Creates the session ID in the log.
Example: (%s) creates the output (5077018__8DF3B2A0-F398-4A4B-BC35-E9A012065CE0) in the log.
a
Creates the action ID in the log.
Example: (%a) creates the output (npt.overview) in the log.
For more information about log4j version 1.2 supported patterns, see the API documentation for Class PatternLayout at https://logging.apache.org.
Enabling FIPS 140-2 Mode of Operation
FIPS 140-2 is a standard that describes U.S. federal government requirements for encrypting sensitive data. If your CA PPM application (app) server vendor is Apache Tomcat, you can enable 
Clarity Project and Portfolio Management (PPM)
to operate in a FIPS 140-2 compliant mode. This operating mode uses a FIPS 140-2 compliant encryption module that is used for encryption operations during the server operation. Examples are using the SSL protocol and encrypting passwords, as defined on the security server properties page.
When operating 
Clarity Project and Portfolio Management (PPM)
in a FIPS 140-2 compliant mode, there are extra operational restrictions that you must follow.
See the
Supported Environment
table in the
RSA BSAFE CryptoJ 6.2.0.1 Release Notes
documentation for details about the restrictions.
Follow these steps:
  1. Log in to CSA.
  2. Open Home, and click Servers.
  3. Click the name of the server you want to configure.
  4. Click the Security sub tab.
  5. Select the FIPS 140-2 Mode Enabled check box, and click Save.
  6. Stop and start each application service.