Configuring Remedy SSO agent
The agent filters protected resources from unauthenticated logins. When the agent detects an unauthenticated request, it redirects the user to the Remedy Single Sign-On (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.
The Remedy SSO agent uses the
401 Unauthorized HTTP response code for redirection to the Remedy SSO server. In addition, the Remedy SSO agent returns an HTML page with a form that is automatically redirected to the Remedy SSO server. In the previous versions, the redirection code 302 was used.
You can configure the following agent settings in the rsso-agent.properties configuration file.
Remedy SSO agent deployment
Consider the scenario wherein Remedy SSO is deployed in the same Tomcat with Mid Tier or 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 the 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, the 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 the RSSO 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 the Remedy SSO Admin UI the Remedy SSO server logout page is displayed to the end user. If the After logout URL is specified in the 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 the 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, the Remedy SSO agent redirects the server-side actions to the 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 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.
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
The 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 the 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 the 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 the Remedy SSO server for the domain “firstcompany” is firstcompany-rsso.bmc.com and the 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 the 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 the 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 the 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
Starting from 9.1.04 RSSO 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.