Configuring Remedy SSO agent
The Remedy Single Sign-On agent filters protected resources from unauthenticated logins. When the Remedy SSO agent detects an unauthenticated request, it redirects the user to Remedy SSO server web application. The agent defines the right domains for the users depending on their domains and also defines the right server to communicate in a multi server environment.
Remedy SSO agent uses the
401 Unauthorized HTTP response code for redirection to Remedy SSO server. In addition, Remedy SSO agent returns an HTML page with a form that is automatically redirected to Remedy SSO server.
You can configure the following agent settings in the rsso-agent.properties configuration file.
Remedy SSO agent deployment
Consider a scenario in which Remedy SSO is deployed in the same Tomcat with Mid Tier and SmartIT or BMC Digital Workplace in an high availability environment. In this case, in the rsso-agent.properties file, the property
sso-service-url must not be configured with a URL that uses the specific host name, such as If a customer wants to use Remedy SSO server in the same Tomcat, 'localhost' should be used as the host name of
sso-service-url property; for example, .
# Agent Identifier, representing an application integrated with BMC Remedy Single Sign-On, usually set application URL as its value. # The value should be same on different nodes in same application cluster, but should be different for different applications. # e.g. agent-id = http://midtier-hostname/arsys agent-id=midtier_agent
When an end user initiates log out from an application, Remedy SSO agent triggers the Remedy SSO logout flow if the logout link generated by the application matches the logout-urls pattern.
# Application URL to trigger BMC Remedy Single Sign-On logout. logout-urls=/shared/loggedout.jsp
You can specify a URL to which the user will be redirected after Remedy SSO completes the logout flow, perform one of the following steps:
Add the callback-url query parameter to the logout URL generated by the application, as shown in the following example:
Add the callback-url as an additional property to the rsso-agent.properties file.
If no callback-url is specified, and if no After logout URL is set in Remedy SSO Admin UI, Remedy SSO server logout page is displayed to the end user. If the After logout URL is specified in Remedy SSO Admin UI, the end user is redirected to that page.
When both options are used, callback-url as a query parameter has higher priority than callback-url property specified in the rsso-agent.properties file.
Remedy SSO redirects an end user only to the same domain as the application domain after the completion of the logout process. For example, if the application domain is bmc.com, any combination of <URL>.bmc.com is allowed.
Support for server-side actions
Remedy SSO supports execution of some specific actions on behalf of the integrated applications. An example of such an action is to allow users to change their passwords to access Remedy AR System server from Remedy SSO. Note that change password is the only action currently supported by this feature.
As client applications interact with Remedy SSO through Remedy SSO agent, the agent is provided the mechanism through the action support feature. The agent defines the action by using the predefined URL path mask. The default path mask is /_rsso/.
The following setting is enabled by default in the rsso-agent.properties configuration file. If the parameter is commented, the default value is used.
After identifying the action, Remedy SSO agent redirects the server-side actions to Remedy SSO server with the 401 or 200 status code and an auto-post HTML form. A 401 code indicates that the user is unauthenticated and a 200 code indicates that the user is authenticated.
The auto-post HTML issues the HTTP POST request with the URL and action parameters in the request body. All server-side actions get similar parameters that are provided for a basic login operation (currently covered by the /rsso/start servlet). The parameters will support all Remedy SSO agent-based features such as Multi-Service Providers (MSP) and preauthenticaion.
The server-side action handlers must be configured to dynamically match the action name. Hence the action handler must be added as the class, matching the action name to the class attribute.
Using action support as an integrated application administrator
As an administrator of an integrated application, you may include the following URL in the email that is triggered to the user to change their password. The user then clicks the URL to change their respective passwords.
<action-path>, which allows the grouping of some actions by categories, can be left blank.
URL example: /_rsso/server/change-password
Excluded URL pattern
# Application URL patterns NOT going through RSSO webagent filter excluded-url-pattern=.*\\.xml|.*\\.gif|.*\\.css|.*\\.ico|/shared/config/.*|/WSDL/.*|/shared/error.jsp|/shared/timer/.*|/shared/login_commn.jsp|/shared/view_form.jsp|/shared/ar_url_encoder.jsp|/ThirdPartyJars/.*|/shared/logout.jsp|/shared/doc/.*|/shared/images/.*|/shared/login.jsp|/services/.*|/shared/file_not_found.jsp|/plugins/.*|/shared/wait.jsp|/servlet/GoatConfigServlet|/servlet/ConfigServlet|/shared/HTTPPost.class|/shared/FileUpload.jar|/BackChannel.*|/servlet/LicenseReleaseServlet.*
Remedy SSO server user-facing URL
# RSSO webapp external url for redirection # To support multiple RSSO webapps, set the value to a comma separated string: each represents a 'domain to server url' mapping, with the format of <domain>:<url>, e.g. domain1:https://server1:8443/rsso,domain2:https://server2:8443/rsso sso-external-url=https://yourcompany.com/rsso
Remedy SSO server service URL
# RSSO webapp internal url for service call. Use HTTP instead of HTTPS protocol to avoid problems with handshake. # To support multiple RSSO webapps, set the value to a comma separated string, each represents a 'domain to server url' mapping, with the format of <domain>:<url>, e.g. domain1:http://server1:8080/rsso,domain2:http://server2:8080/rsso sso-service-url=http://rsso-lb.yourcompany.internal/rsso
Remedy SSO server user-facing (external) and service (internal) URLs can be the same or different. Both should point to the same servers where Remedy SSO is deployed. However, usually user-facing URLs should be protected by firewalls and an HTTPS connection due to security reasons. Meanwhile an internal service call is server-to-server and can be configured for HTTP only for the sake of performance.
If you still need to use HTTPS for Remedy SSO service URL, follow the steps described in Configuring SSL connection verification between RSSO server and RSSO agent.
Configuring SSL connection verification between Remedy SSO server and Remedy SSO agent
If Tomcat on Remedy SSO server is configured to support HTTPS connection by using self-signed certificate, perform the following steps:
- Import the self-signed certificate used by Remedy SSO server into the trust store on the application server which has integration with Remedy SSO agent.
For details about importing the certificate, refer to the documentation provided by your Java vendor.
Enable TLS/SSL checks during establishing HTTPS connection as follows:
- On the application server, open the rsso-agent.properties file.
On Remedy SSO agent server add the following setting in the rsso-agent.properties file:
- Set the com.bmc.rsso.tls.disable.checks flag to
Restart the application server.
If you have an integration with Remedy AR System, you must additionally set the system property com.bmc.rsso.tls.disable.checks to true for AREA plugin in rsso.cfg available in \ARSystem\Conf on the Remedy AR System server.
If you have Remedy SSO agent upgraded, by default the system ignores the self-signed certificate checks. To change the behavior, enable the TLS/SSL checks in the rsso-agent.properties file.
If you have fresh integration of Remedy SSO agent, by default the system checks the self-signed certificate.
If you have problems establishing the HTTPS connection, review Troubleshooting common errors and issues.
Session validation period
# Time during that cached token status will be used without verification at SSO server side. Default value is 3 min. #token-status-cache-timeout=180
Configuring domain entry page
# MSP-related flags # Flag to show realm-entry-page for the MSP deployments msp-deployment=true #msp-always-show-domain-entry-page=true
When set to true, msp-deployment enables the msp functionality.
The msp-always-show-domain-entry-page setting adds specific behavior for the msp-deployment functionality, and it should be set to true only if the msp-deployment is set to true.
Application context control
# If this property is set to true, the application context name will not be excluded for checking the excluded url pattern. #context-included=false
Agent supporting multiple servers
Remedy SSO agent is usually configured to communicate with only one Remedy SSO server. In such a configuration, the agent performs tasks, such as checking configuration, checking the Single Sign-On token, and redirecting logons and logoffs.
An advanced feature of Remedy SSO agent is that it supports communication with multiple Remedy SSO servers for different domains.
The mapping between a domain and a Remedy SSO server (<domain>:<url>) is defined through the following properties in the rsso-agent.properties file.
- Agent redirects the browser (user’s request) to this URL when it detects that the request needs to be authenticated.
- Agent redirects browser to this URL when it detects that the application logout is completed (that is, if the request refers to ‘logout-urls’).
- Agent uses this URL to call the Remedy SSO webapp APIs to:
- Retrieve configuration details, such as cookie name, cookie domain, and realm-domain mappings.
- Check whether the token cookie from the browser (user's request) is valid and if it is valid, retrieve Remedy SSO.
- Register Remedy SSO server to track other application agents. The tracking helps the agent to know the login status of other application agents prior to logging out.
- Agent uses this URL to call the Remedy SSO webapp APIs to:
To support multiple Remedy SSO servers on an agent, set the different values of the domain-to-server mapping as comma-separated strings. For example, assume that Remedy SSO server for the domain “firstcompany” is firstcompany-rsso.bmc.com and Remedy SSO server for the domain “secondcompany” is secondcompany-rsso.bmc.com. Then the properties definition will be as follows:
Enhanced support for load balancer
Remedy SSO supports the X-Forwarded-Proto and X-Forwarded-Host headers that might be sent by the load balancer with a request. Remedy SSO considers the information that comes from the headers while it is generating a login URL (pointing to Remedy SSO server) for the end user.
This feature keeps all external traffic secure even though the internal traffic (behind the load balancer) may not be secure.
Disabling Remedy SSO agent
# To disable Remedy SSO agent just set value to true. In this case the requests will not be processed by Remedy SSO. #skip-filter=false
In addition to disabling Remedy SSO agent, if the RSSOAuthenticator in Mid Tier is being used, find the following line in the config.properties (<MT>/WEB-INF/classes):
and replace the value of the
arsystem.authenticator property with the default value (
Switching Remedy SSO agent to the old-style 302 Redirect mode
# Old-style behavior to support user-agents that don't handle formRedirect using auto-post. # Agent responses 302 in redirect-mode=true # redirect-mode=true
Remedy SSO agent answers 401 Unauthorized with hidden auto-post form to the /rsso/start page instead of 302 Redirect. This breaks compatibility with some products and hence to support old-style behavior we have introduced the new parameter redirect-mode.
By default its value is false and Agent answers 401 Unauthorized. If this value is true Agent switches back to the old-style 302 Redirect behavior.