New Features and Enhancements
The following topics describe the new features and enhancements introduced in Prime Home 5.2.1:
Single Sign On using SAML 2.0
With this new Release, the ACS now requires a key store to enable the SAML/SSO feature. To generate a new key store for a client:
Step 1 Run the following command:
keytool -genkey -alias ciscoprimehome -keyalg RSA -keystore samlKeystore.jks -keysize 2048 -validity <num_days_before_expiring>
What is your first and last name?
What is the name of your organizational unit?
What is the name of your organization?
What is the name of your City or Locality?
What is the name of your State or Province?
What is the two-letter country code for this unit?
Is <enteredinformation> correct?
Enter key password for <ciscoprimehome>
(RETURN if same as keystore password):
Note Cisco recommends using 2048 as the key size. However, if there are key size issues with ADFS, please change the size to 1024.
Note In the above prompt for the key password, you only need to enter a value if you want the key password to be different from the keystore password. If you enter a different value here please note it down and change in the below SAML SSO configuration (Step 6).
Step 2 Export the certificate by running the following command:
keytool -export -alias ciscoprimehome -file ciscoprimehome.crt -keystore samlKeystore.jks
Certificate stored in file <ciscoprimehome.crt>
Note You must use the configurator version that accompanies Prime Home 5.2.1.
Step 3 If SAML SSO is enabled, the following must be carried out:
a. Create the FederationMetaData.xml and keystore (e.g. samlKeyStore.jks) file and ensure they are located in the webapps/prime-home/WEB-INF/classes directory
b. Configure the following parameters as part of the node properties (Values given below are provided for example purposes only):
Step 4 Configure TLS for tomcat by navigating to the SSO page using this address: h ttps://<IP address or domain name>[:<port>]/prime-home/samlsso, and adding the following parameters to the conf/server.xml file
scheme="https" secure="true" SSLEnabled="true"
Note Note that this step is not necessary if TLS is configured on Apache and Load Balancers already.
Step 5 Restart the ACS.
Cross Site Request Forgery
The new cross site request forgery (CSRF/XSRF) enhancement provides an attack mitigation feature for Portal users such as CSRs and Administrators. A new user type named Integration User has been added to the list of Portal Users and should be used if the anti-CSRF token cannot be used. Note that the Integration User can’t log in through the regular Portal log in page.
The Integration User, unlike the CSR and Administrators, can have basic authentication on any end point. In order to create this authentication:
Step 1 Create a token for the Integration User and store it in the database. Prime Home transfers the XSRF token to clients through document object and store it as a cookie. This token must be in HTTP headers for all requests of method type PUT, POST, DELETE.
Step 2 Validate the token from header “X-XsrfSessionHeader” on the server side to confirm proper access.
Allow administrative passphrase lifetime limit
A new global parameter has been added to configure the passphrase time limit: Global.ACS.PassphrasePolicy.PassphraseLifetimeLimit (Min value = 0 Max value = 90 Default should be 90) Note that passphrase expiry validation will not be performed if the value is set to ‘0’. You should set to 1 to ensure that users change the passphrase immediately upon login.
On expiration, a change password screen will be provided and password last updated time will be updated on successful password change by the user.
Passphrase expiration does not apply to Control Panel users.
Check new passphrases against a dictionary
A new global parameter has been added to configure the dictionary: Global.ACS.PassphrasePolicy.CheckDictionary (value: true/false, default value is false)
The default dictionary selected is PassphraseDict.txt
The passphrase will be checked against the dictionary and if it is located there, then the new passphrase will be rejected. If required, another dictionary can be configured by an administrator.
Indicate status at login
Prime Home now displays last login time and IP address at the bottom of the screen.
Limit old password reuse
Users are no longer allowed to use old passphrases.
Administrators can configure the limit in globals: Global.ACS.PassphrasePolicy.OldPassphraseLimit (min: 2 to max: 10, default is 2, disable is 0)
New error message on failed login
Previously, error messages for login attempts with invalid usernames was shown in browsers as "SecuritySession/invalid user was not found". Now, the error message has been changed to "This username/passphrase combination could not be authenticated”. So now, for all login failures (bad username or bad passphrase), there is one consistent error message.
Logging only valid usernames for failed login attempts
User names for failed login attempts will now be logged only if the user names are valid. This will prevent logging of passphrases when user accidentally uses it in the username field.
Display configurable banner before login
Prime Home can now display a configurable banner before login. To support this, a REST endpoint service was created for reading the banner content from the Global configuration. The banner is displayed on the login page for both the Prime Home portal and the Control Panel.
To configure this feature:
Portal login page: Global.Banner.csrLogin
Control Panel login page: Global.Banner.ctrlPanel
Note If the banner content length is less than 300 it will be displayed directly in the login screen. If it exceeds this limit, it will be displayed in a pop up box.
Limit session lifetime
New Global settings have been added to configure absolute session timeout (in minutes).
Active sessions are tracked and checked with session timeout setting. The global parameter to set the session life time is: Global.UserInterface.Portal.AbsoluteTimeoutMinutes : duration in minutes
Default value is 60 minutes if not configured or set incorrectly.
Note It is not possible to disable this parameter. However, you can set it to 1440 and it will allow a session up to 24 hours.
JSESSIONID is now HTTP-only cookie
JSESSIONID is no longer accessible via client scripts.
Secure system and root passwords
To prevent persistence of default credentials, the default password for root/system user in DDL is now a random string so that 'root' cannot be logged in without setting the passphrase. The passphrase change tool is integrated inside the cluster manager (configurator).
It is no longer possible to install the product with the default ‘root’ passphrase. The shell script cv-change-user-password.sh will be used to set a new passphrase for 'root'. This script invokes the passphrase change tool.
To configure the root password:
Step 1 Add a cluster property system_user_password which is auto-generated by the configurator. The generated password will be stored in the DB using password change tool automatically.
Step 2 Assign the context parameter modules-remote.password with cluster property system_user_password which will be used by ACS.
Step 3 Add a new cluster property db_port to config.json. The default value is 3306.
Step 4 In the configurator/bin directory, run the cv-change-user-password.sh script.
cv-change-user-password.sh [DB_USER] [DB_PASSWORD] [DB_HOST] [SCHEMA] [DB_PORT] [TARGET_USER] ([TARGET_USER_PASSWORD] optional).
For example: sh cv-change-user-password.sh primehome prime123 clearvision acs52 3306 root
Securing publicly accessible Prime Home resources
Prime Home no longer supports unauthenticated access to the following APIs:
Permission changes for CSR resources
The CSR permission level defined in resource.xml has been removed for the following REST endpoints:
Passphrase expiration warning
A new passphrase expiration warning for users will be displayed to users 10 days before expiration. The warning will be displayed for 30 seconds after user logs in to the portal.
Provide random passphrases
Administrators can now generate random passphrases for portal users. The passphrase will be generated in the client side based on the passphrase complexity configured in globals below: (either true/false, default is false):
Once the random passphrase has been generated, the passphrase strength will be checked and based on that, the green OK button will be visible.
Clicking on the generate passphrase button converts the passphrase field to a text field so that the generated passphrase will be shown to the end user.
If this user types any key in the passphrase field then it will be turn back into a passphrase field to obscure the text in the Portal.
A new feature has been added which limits the number of invalid login attempts coming from a particular source IP in a given period of time.
If the user enters incorrect credentials more than 3 times within 5 minutes, they will be locked out of the Portal for five minutes.
The globals to configure are:
Global.ACS.PassphrasePolicy.FailedAttemptDuration (default value 5) values are taken as minutes
Global.ACS.PassphrasePolicy.FailedAttemptLimit (default value = 3).
Support syslog for all possible log events
Prime Home now supports using syslog to collect application log events.
To enable syslog, the SYSLOG appender must be configured.
To disable syslog configuration, remove the syslog entry from the entry in log4j.rootLogger element of the log4j.properties
The following syslog configuration is required in the log4j.properties (An overlay needs to be created to replace the log4j.properties file with the changes.
log4j.rootLogger=warn, file, SYSLOG
log4j.appender.SYSLOG = org.apache.log4j.net.SyslogAppender
log4j.appender.SYSLOG.syslogHost = 127.0.0.1
log4j.appender.SYSLOG.layout = org.apache.log4j.PatternLayout
log4j.appender.SYSLOG.layout.ConversionPattern = %d [%t] %-5p %c- %m%n
log4j.appender.SYSLOG.Facility = LOCAL
Carry out the following:
Step 1 Log in as system account root user:
Step 2 Check the status of the rsyslog service: sudo service rsyslog status
Step 3 Stop the service by issuing the command: sudo service rsyslog stop
Step 4 Edit the rsyslog configuration file: vi /etc/rsyslog.conf
Step 5 Ensure the below UDP syslog reception is uncommented
Step 6 Check the file /var/log/messages for the syslog update.
Step 7 To disable syslog, remove the SYSLOG appender from log4j.rootlogger.
Using the Bug Search Tool
Bug Search is used for getting information about Prime Home bugs. Bug Search allows you to:
- Quickly scan bug content
- Configure e-mail notifications for updates on selected bugs
- Start or join community discussions about bugs
- Save your search criteria so you can use it later
When you open the Bug Search page, check the interactive tour to familiarize yourself with these and other Bug Search features.
Step 1 Access the Bug Search tool.
a. Go to https://tools.cisco.com/bugsearch
b. At the Log In screen, enter your registered Cisco.com username and password; then, click Log In. The Bug Search page opens.
Note If you do not have a Cisco.com username and password, you can register for them at http://tools.cisco.com/RPF/register/register.do.
Step 2 To search for bugs in the current release:
a. Enter Prime Home 5.2.1 in the Search For field and hit Return. (Leave the Product, Software Type, Release, and Show Bugs fields empty.)
b. When the search results are displayed, use the filter and sort tools to find the types of bugs you are looking for. You can search for bugs by severity, by status, how recently they were modified, according to the number of support cases associated with them, and so forth.
If you know the bug ID, simply enter it in the Search For field and hit Return.