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 http://access.bmc.com:8080/rsso. 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, http://localhost:8080/rsso.

Agent identifier

# 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

Logout URL

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:

  http://application.bmc.com/arsys/shared/loggedout.jsp?callback-url=http%3A%2F%2Fwww.bmc.com

• Add the callback-url as an additional property to the rsso-agent.properties file.

  callback-url=http://www.bmc.com

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.

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.

action-path-mask=/_rsso

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.

/_rsso/server/<action-path>/<action-name>?<action-params>

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

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

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.

• sso-external-url
  • 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’).
• sso-service-url
• • 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.

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:

• sso-external-url=firstcompany:https://firstcompany-rsso.bmc.com:8443/rsso,secondcompany:https://secondcompany-rsso.bmc.com:8443/rsso
• sso-service-url=firstcompany:http://firstcompany-rsso.bmc.com:8080/rsso,secondcompany:http://secondcompany-rsso.bmc.com:8080/rsso

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):

arsystem.authenticator=com.bmc.rsso.plugin.authenticator.RSSOAuthenticator

and replace the value of the arsystem.authenticator property with the default value (com.remedy.arsys.session.DefaultAuthenticator).

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

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.

Related topic

Remedy SSO agent

Troubleshooting authentication issues