This documentation supports the 19.08 version of Remedy Single Sign-On.

To view an earlier version, select the version from the Product version menu.

Configuring Remedy SSO agent

This topic was edited by a BMC Contributor and has not been approved.  More information.

As an administrator of the server where an integration of Remedy Single Sign-On with an application is installed, you can configure the Remedy SSO agent by setting up properties in the rsso-agent.properties file.

Review the properties described in this topic to apply the required changes to the rsso-agent.properties file.

Note

When properties in the rsso-agent.properties file are commented, the default values are used.

Related topics

Remedy SSO agent

Integrating

Troubleshooting authentication issues

SSL/TLS Configuration How-To

Agent identifier

The agent-id identifies an application integrated with Remedy SSO. You can specify any text value or an application URL for the agent-id property. 

# e.g. agent-id = http://midtier-hostname/arsys
agent-id=midtier_agent

If you have Remedy SSO deployed in high availability mode, then you must specify the same value as agent-id on all nodes in the cluster. 

However, you must not use the same value for integration with other applications, because the agent identifier must be unique per integration with other applications. 

Logout URL

If the logout link generated by the application matches the logout-urls pattern, then the Remedy SSO agent triggers the Remedy SSO logout flow when an end user initiates a logout from an application.

By default, the following configuration is applied:

# Application URL to trigger BMC Remedy Single Sign-On logout.
logout-urls=/shared/loggedout.jsp

Excluded URL pattern

By setting the excluded-url-pattern parameter, you can define which URLs must not go through the Remedy SSO web agent filter.

By default, the following configuration is applied:

# 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.*

Application context control

The context-included property provides a means to enable or disable the option to check the application context by the Remedy SSO web agent filter.

To not exclude the application context from the excluded-url-pattern, set the context-included flag to true. By default, the following configuration is applied:

# context-included=false

Remedy SSO URLs 

Server user-facing (external) and service (internal) URLs of the Remedy SSO server can be the same or different. Both of these URLs should point to the same server where Remedy SSO is deployed. Due to security reasons, user-facing URLs are protected by firewalls and an HTTPS connection. Internal service calls are server-to-server and can be configured for HTTP only for the sake of performance.

Remedy SSO external URL

The Remedy SSO agent redirects the browser (user’s request) to the sso-external-url when it detects one of the following events: 

  • The request needs to be authenticated.
  • The application logout is completed (that is, if the request refers to logout-urls).
# 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 internal URL

The Remedy SSO agent uses the sso-service-url parameter to call the Remedy SSO web application APIs to perform the following tasks:

  • 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
  • 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.

Consider the following use cases when you configure the value for the sso-service-url parameter:

To avoid problems with handshake

Use the HTTP protocol instead of HTTPS to construct the URL:

sso-service-url=http://rsso-lb.yourcompany.internal/rsso

If due to some reasons, you need to use HTTPS for sso-service-url, follow the steps described in Configuring SSL connection verification between the Remedy SSO server and agent.

To support multiple Remedy SSO web applications

Set the value to a comma separated string, each representing a domain to the server URL mapping, with the <domain>:<server url> format.

sso-service-url=domain1:http://server1:8080/rsso,<domain2>:http://<server2:8080/rsso

For more details about this use case, see Connecting Remedy SSO agent to multiple Remedy SSO servers.

Session token validation period

The Remedy SSO agent provides the configuration parameter for defining the time during which the cached session token remains valid without verification by the   Remedy SSO server. By default, the token-status-cache-timeout is 3 minutes (180 seconds):

# token-status-cache-timeout=180

Use in-memory cache

The Remedy SSO agent provides the configuration property that enables to choose between HTTP session and in-memory cache to store the token data.

By default, the in-memory cache option is disabled:

# use-in-memory-cache=false


Note

After you enable the in-memory cache, you must restart an application integrated with Remedy SSO.

Preauthentication 

To configure the Remedy SSO agent to expect JSON Web Token (JWT) in the authentication flow, set the preauth-type parameter. Depending on how the third-party application  sends a JWT to Remedy SSO, configure the Remedy SSO agent to expect JWT by HTTP GET or POST method. By default, the GET method is configured:

preauth-type=get

Action path mask

Remedy SSO supports execution of some specific actions on behalf of applications integrated with Remedy SSO. Currently, only change password action is supported, which enables end users to change their passwords by accessing the Remedy AR System server from Remedy SSO:

The following setting is enabled by default in the rsso-agent.properties configuration file:

# action-path-mask=/_rsso

For more information about how to use this option, see Configuring the Remedy SSO agent to enable end users to change their passwords.

MSP functionality

To display the realm entry page for MSP deployments, set the msp-deployment flag to true. The MSP page is displayed to end users in cases where the Remedy SSO server cannot identify to which realm an end user belongs.

To always display the realm entry page for MSP deployments, set the msp-always-show-domain-entry-page to true.

# msp-deployment=true
# msp-always-show-domain-entry-page=true

Multi-domain support 

If you have Remedy SSO and an integrated application deployed on different domains, you must configure the Remedy SSO agent to support this deployment use case. For more information about this use case, see Deployment scenarios.

Set the multi-domain-support property to true to enable multi-domain support for the Remedy SSO agent, and then configure the values for auth-client-id and oauth-client-secret properties.

# multi-domain-support=true
# oauth-client-id=
# oauth-client-secret=

For more information about how to configure multi-domain support, see Configuring Remedy SSO for applications hosted on different domains.

Disabling the Remedy SSO agent

To disable the Remedy SSO agent, set the skip-filter parameter to true.

# 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

If the RSSOAuthenticator in Mid Tier is used, perform the following steps to disable the Remedy SSO agent:

  1. From the <MT>/WEB-INF/classes directory, open the config.properties file.
  2. Set the following value for the arsystem.authenticator parameter:
arsystem.authenticator=com.remedy.arsys.session.DefaultAuthenticator

Redirect mode

The Remedy SSO agent answers 401 Unauthorized with hidden auto-post form to the /rsso/start page instead of 302 Redirect. This breaks the compatibility with some products, and hence to support an old-style behavior, the redirect-mode parameter is used.

By default, its value is false and Agent answers 401 Unauthorized. If this value is true, the Remedy SSO agent switches back to the old-style 302 Redirect behavior.

# redirect-mode=true

Callback URL

To specify a URL to which the user must be redirected after the Remedy SSO completes the logout flow, set a value for the callback-url property. For example, set the value as follows:

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

Alternatively, you can 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

Note

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.

When both options are used, the callback-url as a query parameter has higher priority than the callback-url property specified in the rsso-agent.properties file.

If you do not specify the callback-url, and if you dot no specify the After logout URL for a realm in the Remedy SSO Admin UI, then the Remedy SSO server logout page is displayed to end users.

If you specify the After logout URL for a realm in the Remedy SSO Admin UI, end users are redirected to the specified URL page.

Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Saurabh Maheshwari

    Please check troubleshooting link for SSL connection. As per this link https://docs.bmc.com/docs/rsso1908/troubleshooting-common-errors-and-issues-879743344.html

    if you have an integration with BMC 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 Remedy AR System server

    Nov 09, 2019 10:58
    1. Olga Kutetska

      Hello, Saurabh!

      Thank you for pointing to the incomplete task description. I will update the page as soon as possible.

      Nov 12, 2019 05:40