Remedy SSO Agent
Remedy Single Sign-On (Remedy SSO) agent is designed as an HTTP request filter to identify unauthenticated requests and redirect those requests to successfully complete Remedy SSO server authentication.
When initializing, the agent requests the Remedy SSO server to get a configuration. The important configuration element is the authentication cookie name.
After getting the HTTP request, the agent defines whether the user is already authenticated by looking for the authentication cookie in the request. If the authentication cookie is not present, the agent identifies the realm based on the application domain from application URL and domain parameter in the application URL or provided by the user. After that, the user is redirected to the Remedy SSO server to pass authentication based on the realm settings.
If authentication cookie is present, the agent validates it by making a service call to the Remedy SSO server. This validation is made on a regular basis and the validation period can be configured to not impact performance. If validation is successful, the request passes to the application. Otherwise it is redirected to the Remedy SSO server to pass the authentication process again.
Starting from version 9.1.04, Remedy SSO agent uses the
401 Unauthorized HTTP response code for redirection to Remedy SSO server. In addition, Remedy SSO agent also returns an HTML page with a form that is automatically redirected to the Remedy SSO server.
In previous versions, the redirection code 302 was used.
You may configure the following agent settings in the rsso-agent.properties configuration file.
# 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.
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.*
RSSO 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
RSSO 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 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.
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
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
Disabling RSSO 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 config.properties (<MT>/WEB-INF/classes):
and replace the value of
arsystem.authenticator property with the default value (
Agent supporting multiple servers
The Remedy SSO web 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 web agent 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 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.
To support multiple Remedy SSO servers on an agent, set the different values of 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
Starting from version 9.1.04, Remedy SSO supports the X-Forwarded-Proto and X-Forwarded-Host headers which might be sent by the load balancer with a request. Remedy SSO considers that information from headers while generating a login URL (pointing to Remedy SSO server) for the end user.
This allows to keep all external traffic secure even though the internal traffic (behind the load balancer) may not be secure.
Remedy SSO agent deployment
Consider the scenario wherein Remedy SSO is deployed in the same Tomcat with Mid Tier or SmartIT_BMC Digital Workplace in an HA environment. Then, in the rsso-agent.properties file, the property
sso-service-url must not be configured with URL using the specific hostname; for example, . If a customer wants to use the RSSO server in the same Tomcat, 'localhost' should be used as the hostname of
sso-service-url property; for example, .