Configuring the BMC Helix SSO agent

As a BMC Helix Single Sign-On administrator, you can configure the BMC Helix SSO agent by setting up properties in the rsso-agent.properties file. By modifying this file, you configure integration of the BMC Helix SSO server with other BMC applications.

Tip

To apply changes to the BMC Helix SSO agent configuration, ensure that updated properties in the rsso-agent.properties file are not commented. Else, the default values are used.


General properties

The following table lists general properties that you modify for the BMC Helix SSO agent. For example, if you have BMC Helix SSO and an integrated BMC application deployed on different domains, you must set the multi-domain-support property to true.

ParameterDescription

agent-id

Identifies a BMC application integrated with BMC Helix SSO. You can specify any text value or an application URL for this property. If you have  BMC Helix SSO deployed in high-availability mode, 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. 

Example

# agent-id=http://midtier-hostname/arsys
skip-filter

Disables the BMC Helix SSO agent if the parameter is set to true. In this case, requests are not processed by BMC Helix SSO.

Example

# skip-filter=false

Important: 

If RSSOAuthenticator in Mid Tier is used, perform the following steps to disable the BMC Helix 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
multi-domain-support

If you have BMC Helix SSO and an integrated BMC application deployed on different domains, you must configure the BMC Helix 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, and then configure the values for auth-client-id and oauth-client-secret properties. For more information about how to configure multi-domain support, see Configuring BMC Helix SSO for applications hosted on different domains.

Example

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


token-timeout-synchronization

Important: This property is applicable only when multi-domain support is enabled.

If this property is set to true, the time difference between the BMC Helix SSO agent and the BMC Helix SSO server is ignored. This property, set in seconds, specifies the time offset between the BMC Helix SSO server and the BMC Helix SSO agent. For example, if the BMC Helix SSO  agent receives a token from the  BMC Helix SSO  server, and the token issue time according to the time set on the  BMC Helix SSO  agent  is future , the  BMC Helix SSO  agent accepts the token without any  errors .

By default,  token-timeout-synchronization is 10 seconds.

Example

# token-timeout-synchronization=10

preauth-type

Enables the BMC Helix SSO agent to expect JSON Web Token (JWT) in the authentication flow. Depending on how the integrated BMC application sends a JWT to BMC Helix SSO, configure the BMC Helix SSO agent to expect JWT by HTTP  GET or  POST method. By default, the GET method is configured.

Example

# preauth-type=get

For more information about the preauthentication authentication type, see Preauthentication.

action-path-mask

Enables end users to change their passwords by accessing the Action Request System  server from BMC Helix 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 BMC Helix SSO agent to enable end users to change their passwords.

msp-deployment

If this property is set to true, the realm entry page for Multi-Service Provider (MSP) deployments is displayed to end users in cases where the BMC Helix 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 property to true. This property works only when the multi-domain-support property is set to false.

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


Properties related to URLs 

The following table lists properties that enable you to modify URLs. For example, you can define an external URL to which a user who attempts to log in to an integrated BMC application is redirected. This is done by setting up the sso-external-url property.

sso-external-url

Defines a server user-facing (external) URL of the BMC Helix SSO server. The external URL can be the same or different from the internal URL, but both of these URLs must point to the same server where BMC Helix SSO is deployed. The external URL is the user-facing RSSO Server URL which may actually be the LB or ingress controller behind which the actual RSSO Server is deployed. This URL must be accessible by the end users

The  BMC Helix SSO agent redirects the browser (user’s request) to sso-external-url after detecting one of the following events: 

  • A request needs to be authenticated.
  • An application logout is completed (only if the request refers to logout-urls ).

To support multiple BMC Helix SSO web applications, set the value to a comma separated string: each represents an 'application FQDN' mapping, with the format of <application FQDN>:<url>.

Example

# <application FQDN>:https://<server1/rsso>,<application FQDN>:https://<server2/rsso>
sso-external-url=https://yourcompany.com/rsso
sso-service-url

Defines a service (internal) URL of the BMC Helix SSO server. Internal service calls are server-to-server. 

The BMC Helix SSO agent uses the  sso-service-url parameter to call the BMC Helix 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 BMC Helix SSO server to track other application agents. The tracking helps the agent know the login status of other application agents prior to logging out.

Example

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

For more information about troubleshooting the internal URL, see Troubleshooting.

Important

To support multiple BMC Helix SSO web applications, set the value to a comma separated string: each represents an application FQDN mapping, with the format of <application FQDN>:<url>.

Example

# <application FQDN>:https://<server1/rsso>,<application FQDN>:https://<server2/rsso>
sso-external-url=https://yourcompany.com/rsso

logout-urls

Identifies a BMC application URL that triggers BMC Helix SSO logout. If the logout link generated by the BMC application matches the logout-urls   pattern, the BMC Helix SSO agent triggers the BMC Helix SSO logout flow when an end user initiates a logout from this application.

Example

# logout-urls=/shared/loggedout.jsp
excluded-url-pattern

Defines which URLs must not go through the BMC Helix SSO web agent filter.

By default, the following configuration is applied:

# excluded-url-pattern=.*\\.xml|.*\\.gif|.*\\.css|.*\\.ico|/shared/config/.*|/WSDL/.*|/shared/error.jsp
context-included

Provides a means to enable or disable the option to check the application context by the BMC Helix SSO agent filter. To include the application context in excluded-url-pattern , set the  context-included  flag to true. By default, the following configuration is applied:

# context-included=false
callback-url

Identifies a URL to which a user must be redirected after BMC Helix SSO completes a logout flow. BMC Helix 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.

Example

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

Alternatively, you can add the callback-url query parameter to logout-urls  generated by the application:

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

If you combine callback-url with logout-urls , the callback-url as a query parameter has higher priority than the logout-urls  property specified in the rsso-agent.properties file.

If you do not specify both callback-url and After Logout URL for a realm in the  BMC Helix SSO Admin Console, the BMC Helix SSO  server logout page is displayed to end users.

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

For more information about After logout URL, see Configuring general settings for a realm.

redirect-mode

Enables the 302 Redirect error response on a session timeout.

On a session timeout, the BMC Helix SSO agent responds with a 401 Unauthorized error with a hidden auto-post form to the /rsso/start page instead of a 302 Redirect error, which breaks the compatibility with some products. 

Set this parameter to true to retain the 302 Redirect error.

# redirect-mode=true

By default, the value of this property is false and the BMC Helix SSO agent responds with a 401 Unauthorized error. 

Important: If the multi-domain support is enabled, the BMC Helix SSO agent responds with a 302 Redirect error, irrespective of the redirect-mode parameter setting. For more information about how to configure multi-domain support, see Configuring BMC Helix SSO for applications hosted on different domains.

ajax-requests-support

Enables handling backchannel requests such as AJAX requests.

Enable this parameter to enforce a no-redirect policy for the BMC Helix SSO agent on receiving a backchannel request such as AJAX.

# ajax-requests-support=true

On a session timeout, the BMC Helix SSO agent responds to the request with a 401 Unauthorized error, and t he BMC Helix SSO agent sends the following response header:

X-RSSO-RESPONSE: true

By default, the name of header in the request is X-RSSO-Ajax-Request. To change this name use the optional property ajax-request-header-identifier.

For more information, see  ajax-request-header-identifier .

Set this parameter to false for the BMC Helix SSO agent to respond based on the redirect-mode parameter setting on a session timeout.

(Optional) ajax-request-header-identifier

Customizes the header key value in the request header for identified requests.

By default, the value is set to X-RSSO-Ajax-Request.

# ajax-request-header-identifier=X-RSSO-Ajax-Request

Update the parameter value to use a custom header value in the following format

X-RSSO-Custom-Ajax-Request:<headerValue>

where <headerValue> is the string value displayed in the header response. 


Properties related to sessions

The following table lists properties that enable you to modify session configuration for the integration of BMC Helix SSO and a BMC application. For example, you can select a mode in which token data is stored. To perform this action, set the use-in-memory-cache property.

ParameterDescription

token-status-cache-timeout

Defines the time during which the cached session token remains valid without verification by the  BMC Helix SSO server. Time is indicated in seconds.

Example

# token-status-cache-timeout=180

use-in-memory-cache

Enables you to choose between an HTTP session and in-memory cache to store the token data. 

Important: After you enable the in-memory cache, restart the BMC application integrated with BMC Helix SSO.

Examples

# use-in-memory-cache=false
# use-in-memory-cache=true

(Optional)redis-uri

Configures the BMC Helix SSO agent with the Redis server. This configuration enables the BMC Helix SSO agent to log users out of all BMC Helix applications immediately when you use the single logout option.

Set the following parameter in the configuration file:

redis-uri=<redis_uri_value> ex. redis://host.bmc.com:6357 (redis :// [[username :] password@] host [: port] [/ database][? [timeout=timeout[d|h|m|s|ms|us|ns]] [&_database=database_]])

If you provide the redis-uri parameter, you must provide the redis-channel parameter. You can also provide the redis-password.

Important: The configuration values of the Redis server must be the same on the BMC Helix SSO server and agent.

For more information about configuring the BMC Helix SSO server with the Redis server, see Configuring BMC Helix SSO to support immediate logout from all applications.

(Optional)redis-channel

Defines the Redis channel for messaging.

Set the following parameter in the configuration file:

redis-channel=<redis_channel_value>


(Optional)redis-password

Defines the password required to access the Redis server. Defining a password is optional because the Redis server can be configured without a password.

Set the following parameter in the configuration file:

redis-password=<redis_password>



Troubleshooting

When you configure the value for the sso-service-url parameter, consider the use cases in the following table:

IssueWorkaround

Issues with handshake

When constructing the URL, use the HTTP protocol instead of HTTPS: 

# rsso-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 Disabling TLS checks between Helix SSO server and agent.

Permission issues for in-container configuration file modifications

You can insert any environment parameter for the rsso-agent.properties file by using the following format: 

${env:<VAR_NAME>}

$ export RSSO=http://localhost:port/rsso
and sso-service-url=${env:RSSO} in rsso-agent.properties gets resolved

Support of multiple BMC Helix SSO web applications

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

# <application FQDN>:https://<server1/rsso>,<application FQDN>:https://<server2/rsso>
sso-service-url=http://rsso-lb.yourcompany.internal/rsso

For more details about this use case, see Connecting the same BMC Helix SSO agent to different BMC Helix SSO servers.


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

Comments