Mapping realm URLs to an agent for multiple realms

Before you add a realm and edit the authentication details, you can automate the mapping of the agent URLs to specific realms in the Agent Editor Console for multi-tenancy support. This mapping helps the BMC Atrium Single Sign-On server in identifying the requests coming from different tenants. The URLs specified on the Realms tab in the Agent Editor Console provides the mapping for each tenant.

Before you begin

You must first add an agent on the AR System server by running the BMC Atrium Single Sign-On installer for integration. This agent is used for mapping realm URLs. For more information, see Running the BMC Atrium Single Sign-On installer on the AR System server.

To map realm URLs automatically

In the BMC Atrium SSO Console, click Agent Details.
The Agent Manager console is displayed.
Click the WebApp tab.
For more information about agent editor properties, see Agent editor properties in multi-tenant environment.
From the Realm drop-down list, select the realm that you want to map to the web agent.
Click Add.
The selected realm is displayed in the Agents list.

To add a realm to the mapping list manually

In the BMC Atrium SSO Console, click Agent Details.
The Agent Manager console is displayed.
Click the Realms tab.
From the Realms drop-down list, select the realm that you want to map to the web agent.
Click Add.
The selected realm is displayed in the mapping list above the Realms drop-down list.

Agent editor parameters

The agent manager provides an agent panel that allows you to edit, delete, and search for an agent as well as provides the agent name, realm, and the state. The state indicates whether the agent is running or is down. When you search for an agent, *, returns all the names and applies to all the columns in the agent panel. Finding the filter string within any of these values selects the agent to be returned for display. This feature allows you to filter the list of agents by specifying a value, for example, Running.

Configuring agent editor properties

The agent editor allows you to modify the configuration of an agent. By modifying the agent configuration, you can resolve problems caused by environment difficulties. For example, with a remote host, the host may report their FQDN (Fully Qualified Domain Name) incorrectly using a plain name such as machine instead of machine.bmc.com. You can also associate realms to an agent using agent editor.

Select an agent in the Agent Details console and click Edit. The The Agent Editor is displayed. You can configure agent editor properties using the following tabs:

Agent tab

Parameter	Description
Notification URL	The URL where the agent receives notifications from the server about session logouts. This URL is products base URI with "/atsso" added at the end. For example, https://sample.bmc.com/arsys/atsso.
Status	Determines whether the agent is enforcing Single Sign-On authentication (active) or not (inactive)
Logging Level	The level of logging agent performs in the product
Redirect Limit	The number of times that the agent redirects the browser to the server for authentication before signaling an error. Value 0 suggests no limit.
Password and Confirm Password	Password used to access agent's configuration in the BMC Atrium Single Sign-On server.
Enable Cache	Option used to enable session cache. You may face performance issues if you disable cache.

WebApp tab

Parameter	Description
Cookie Name	The cookie name is the cookie that agent will check for the BMC Atrium Single Sign-On session token. It should match the cookie name of the server configuration. Note: To ensure browser compatibility, the cookie name should contain only alphanumeric and underscore characters.
Web App Logout URI	Specifies the URI that signifies a logout event for the web app. The Web Agent maps the server hostname (which is used by user to access a protected application) to the full logout URL. For example, arsys/shared/loggedout.jsp is appended to the default URL.
Realm	Select the realm from the list of available realms in the list.

FQDN Mapping tab

The FQDN mapping allows the agent to fix the URL used to access the application in order to get the browser to send cookies to the application. The Single Sign-On session is identified through cookies. When a URL is not using a FQDN host name, the browser does not know the domain of the server and therefore, won't send any cookies to the server.

Parameter	Description
Enable	Select this check box to enable the fields on the FQDN Mapping tab. You must clear this check box for using multi-tenancy. For more information about enabling multi-tenancy, see Enabling-and-disabling-multi-tenancy-support.
FQDN of Agent Host	When enabled, the FQDN entered is the FQDN of the host where the agent is located. Enabling FQDN mapping causes the agent to perform the forwarding from the entered host names to the entered FQDN.
Trigger host list and Trigger Host Name	The hosts that will trigger the FQDN redirection to occur. The Trigger host list allows you to remove the host from the list. Trigger Host Name allows you to add a host to the Trigger host list.

Realms tab

You can attach multiple realms to an agent using this tab. You can modify or detach the realm details using Edit or Delete.

Parameter	Description
Automatically Include New Realms	Select this check box if you want to automatically add the realm to the Realms tab when a new realm is created from the Realms panel. The Login and Logout URLs will be automatically included in the realm details when the realm is added.
Note: The following parameters will appear in the WebApp tab and not in the Realms tab if multi-tenancy is disabled.
Name	Name of the Realm
UserId Validation	If you want to validate that the User ID is in email format (for example, user@domain.com), select this check box.
Login and Logout URI	Login and Logout URIs are the locations that the agent will send the user's browser when the user wants to log on to their respective applications. When an agent is federated, the login and logout URL for the agent must be modified to interact with the IdP. You can set two different URL formats: Tenant default realm URLs — This format is used when you are using any other type of authentication in BMC Atrium Single Sign-On. https://<fqdn>:<port>/atriumsso/UI/Login?realm=<realm-name> https://<fqdn>:<port>/atriumsso/UI/Logout?realm=<realm-name> SAMLv2 URLs — This format is used when you are using SAMLv2 for authentication in BMC Atrium Single Sign-On. {{code language="none"}} https://<fqdn>:<port>/atriumsso/spssoinit?metaAlias=<metaAlias>&idpEntityID=<idp> https://<fqdn>:<port>/atriumsso/samlv2/jsp/spSingleLogoutInit.jsp?idpEntityID=<idp> {{/code}} Note: If you want to provide a customized landing page after the user logs out of the application, add the following to the logout URLs: For Tenant default realm Logout URL - &goto=customized_logoutURL. For example, https://tenant.onbmc.com:8443/atriumsso/UI/Logout?realm=tenant&goto=http://www.bmc.com For SAMLv2 Logout URL - &RelayState=customized_logouturl. For example, https://tenant.onbmc.com:8443/atriumsso/saml2/jsp/spsSingleLogoutInit.jsp?idpEntityID=IDP&RelayState=http://www.bmc.com
Login Probe and Logout Probe	The probe validates that the destination is accessible before sending the user to the location. If they are not, the agent tells the user that the Single Sign-On system is inaccessible. The probe should be turned off in environments where the URI cannot be contacted from the agent's environment, such as when the URI contains a host that is to be accessed using a reverse proxy.

Not enforced tab

Parameter	Description
Name	Name of the Realm
Not Enforced URI	The Not Enforced URI list allows you to launch URLs without authentication. For example, you may want to open images, css or javascript files without authentication. The URI field allows you to add a URI to the Not Enforced URI list. Adding URI to the list — Enter the URI and click Add. Deleting URI from the list — Select the URI and click Remove.