Skip to Content

Configuring realm identification for multiple service providers

As a SaaS administrator, activate the Multiple Service Provider (MSP) functionality for a tenant and then enable realm identification by specifying a pattern for a user's login and/or (starting with version 25.3.02) IP address. The MSP functionality helps the BMC Helix Single Sign-On server to identify the realm to which a user has access. After the realm is identified, the user can access all domains associated with the realm

The MSP functionality works for Auth Proxy-based integrations and agent-based integrations.

Tenant administrator access

Tenant administrators can access the MSP server-side settings for their tenants, and can change the mappings and their sequences. This access helps tenant administrators to get insights into the available mappings and manage them according to the business needs.

Important
The tenant administrator can only modify the patterns they have created and adjust the sequence of patterns created by the SaaS administrator.

To activate the MSP functionality for a tenant

As a SaaS administrator, perform the following steps:

  1. Log in to the BMC Helix SSO Admin Console.
  2. On the navigation panel, click Tenant.
  3. Edit a tenant for which you want to enable realm identification.
  4. In the tenant feature flags section, select the MSP server side check box.
  5. Click Save.

Identifying realms by a user name

The following figure provides an overview of how realm identification works when a user name pattern is configured:

User name pattern flow.jpg

After you enable the MSP functionality and activate user name-based realm identification, the following events occur:

Event

Description

1

A user opens an application URL.

2

The BMC Helix Single Sign-On server redirects the user to the MSP page and prompts the user to enter a user name or any meaningful value.

3

After the user enters their credentials, the server attempts to identify a realm to which the user has access, and one of the following events occurs:

  • If the server successfully identifies a realm, the user proceeds with the login activity and accesses domains in the realm to which they have access.
    The user accesses a domain by providing credentials based on the authentication configured for that realm.
  • If the server cannot identify a realm, the server displays the following error: Not possible to define realm. To troubleshoot this error, create the #login.matches(".*") user name pattern and add it as the last pattern in the list.

How user name patterns are used to identify a realm

After the user enters their login credentials, the server maps the user name to the user name patterns defined for different realms. A user name pattern is an expression defined inSpring Expression Language (SpEL). The expression must contain the #login keyword, which is a placeholder for the user name or any meaningful value that a user enters during runtime. Along with #login, you can use any of thestring class functions that return a boolean value to identify the realms that a user has access to.

Information
Real-life example

Allen, an administrator in Apex Global, defines the #login.endsWith(@apex.com) user name pattern for the Apex Global realm. Hannah, an end user, logs in to an application that is integrated with BMC Helix Single Sign-On, and the following events occur:

  1. Hannah enters the hannah@apex.com user name so that the server identifies her as a user who has access to the Apex Global realm.
  2. The BMC Helix Single Sign-On server maps hannah@apex.com with the #login.endsWith(@apex.com) user name pattern.
  3. The server finds that the user name Hannah provided matches the user name pattern defined for Apex Global.
  4. The server prompts Hannah to enter the credentials to complete the authentication process and grants her access to the application.
  5. The server authenticates Hannah according to the authentication settings defined for the realm.

To define a user name pattern for realm identification

A SaaS administrator can create or edit a user name pattern for all realms whereas a tenant administrator can create or edit a user name pattern for a realm where self-service is enabled.

As a SaaS or a tenant administrator, perform the following steps:

  1. On the navigation panel, click Realm. The Realm Configuration page is displayed where the Realms tab contains a list of tenant realms, and the MSP tab contains the MSP mappings that can be configured for any realm.
  2. Click the MSP tab.
  3. Click Add.
  4. In the Pattern field, specify a pattern with the #login.string method("value") format; for example, enter #login.endsWith("@local.com"). If you specify multiple patterns for the same realm, the first value in the list of user name patterns takes precedence. Note: A user name pattern must be unique for each realm.
  5. From the Realm list, select a realm that should be identified for the user name pattern you added.
  6. In the Actions column, click the confirmation icon.
  7. Click Save.
    User name pattern.png

If you do not create any user name patterns, the login process for a user runs as usual.

Identifying realms by an IP address

The following figure provides an overview of how realm identification works when an IP address pattern is configured:

IP address pattern flow.jpg

After you enable the MSP functionality and activate IP address-based realm identification, the following events occur:

Event

Description

1

A user opens an application URL.

2

The BMC Helix Single Sign-On server checks whether the user's IP address matches the specified rule. A user is not redirected to the MSP page.

3

After the server finishes checking the user's IP address, one of the following events occurs:

  • If the IP address matches the rule, the user proceeds with the login activity and accesses domains in the realm to which they have access.
    The user accesses a domain by providing credentials based on the authentication configured for that realm.
  • If the IP address does not match the rule, the server displays the following error: Not possible to define realm. To troubleshoot this error, verify whether the ID address defined in the rule is included in the X-Forwarded-For header. 
  • If the IP address does not match the rule, and the rule includes user name restrictions, the user is redirected to the MSP page.

How IP address patterns are used to identify a realm

When the user opens an integrated application URL, the server maps the IP address to the IP address patterns defined for different realms. An IP address pattern is an expression defined inSpring Expression Language (SpEL). The expression must contain the #clientIPRange(...) keyword, which is a placeholder for the IP address or a range of IP addresses.

Information
Real-life example

Rohit, an administrator in Centary, defines the #clientIPRange.include("172.28.133.25-172.28.145-180") IP address pattern for the Centari realm. Charlotte, an end user, opens an application that is integrated with BMC Helix Single Sign-On, and the following events occur:

  1. The BMC Helix Single Sign-On server maps Charlotte's IP address 172.28.133.25 to the #clientIPRange.include("172.28.133.25-172.28.145-180") IP address pattern.
  2. The server finds that Charlotte's IP address matches the IP address pattern defined for Centari.
  3. The server prompts Charlotte to enter the credentials to complete the authentication process and grants her access to the application.
  4. The server authenticates Charlotte according to the authentication settings defined for the realm.

To define a user's IP address pattern for realm identification

A SaaS administrator can create or edit an IP address pattern for all realms whereas a tenant administrator can create or edit an IP address pattern for a realm where self-service is enabled.

As a SaaS or a tenant administrator, perform the following steps:

  1. On the navigation panel, click Realm. The Realm Configuration page is displayed where the Realms tab contains a list of tenant realms, and the MSP tab contains the MSP mappings that can be configured for any realm.
  2. Click the MSP tab.
  3. Click Add.
  4. In the Pattern field, specify a pattern with the #clientIPRange.include("IP address 1", "IP address 2", "IP address 3") format; for example, enter #clientIPRange.include("172.28.133.25"). You can also specify a range of IP addresses, for example, #clientIPRange.include("172.28.133.25-172.28.140.197") or increase the complexity of the rule by adding a user name pattern in the same line; for example, #clientIPRange.include("172.28.133.25-172.28.140.197")&&#login.equals("LD"), meaning that only users with an IP address from within the given range and having the "LD" as a user name will have access to the integrated BMC Helix application. If you specify multiple patterns for the same realm, the first value in the list of user name patterns takes precedence.
  5. From the Realm list, select a realm that should be identified for the IP address pattern you added.
  6. In the Actions column, click the confirmation icon.
  7. Click Save.

           IP address pattern.png

If you do not create any IP address patterns or combine them with user name patterns, the login process for a user runs as usual.

To change the sequence of MSP server-side mappings

As a SaaS or a tenant administrator, you can change the sequence of the MSP server-side mappings by performing the following steps:

  1. Log in to the BMC Helix Single Sign-On Admin Console.
  2. On the navigation panel, click Realm.
  3. Click the MSP tab.
    The available mappings between patterns and realms are displayed.
  4. To change the sequence of mappings in the list, click the Up arrow Up arrow.pngor the Down arrow Down arrow.png.
  5. Click Save.

 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC Helix Single Sign-On 25.3