How to Configure Netreo to Use SAML 2.0 for User Management

When using SAML 2.0 authentication, users may no longer log in as regular web users using BMC Helix Network Management local user accounts.

Configuring SAML single sign-on in BMC Helix Network Management requires configuration both within BMC Helix Network Management itself and within your identity provider account.

Adding and configuring applications in an identity provider is highly specific to each provider, and these instructions are not specific to any single provider. Check your identity provider's documentation for the most up to date information on how to add an application to your account and configure their service appropriately.

1. Log in to BMC Helix Network Management as a user with the SuperAdmin access level.
2. Go to the main menu and select Administration > Users > Authentication Settings to navigate to the Authentication Settings page.
3. In the TYPE field of the Authentication panel select SAML (2.0) from the pull-down menu. The SAML configuration options become visible.
   • Three URLs are automatically provided in the Service URLs for Your Identity Provider panel that can be used to add an application and configure their service to work with BMC Helix Network Management. These URLs are specific to each BMC Helix Network Management instance.
     • AUDIENCE (ENTITYID) URI
       The signature to identify BMC Helix Network Management as the service provider.
     • ACS (CONSUMER) URL
       (Assertion Consumer Service) The BMC Helix Network Management endpoint to provide as a response to a successful login through the identity provider. Sometimes referred to as recipient.
     • SINGLE LOGOUT URL
       The BMC Helix Network Management endpoint used to log a user out of BMC Helix Network Management simultaneously when the identity provider logs the user out of their BMC Helix Network Management session. Your identity provider must support federated logout to use this endpoint.
4. Now log in to your identity provider and create a new application.
   • Adding and configuring applications is highly specific to each identity provider. Contact your identity provider or refer to their documentation for specific instructions.
     • For Okta refer to https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm
     • For OneLogin refer to https://www.onelogin.com/getting-started/free-trial-plan/add-apps-saml
     • For Azure Active Directory refer to https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso
5. In the configuration area for your application:
   • For the Audience (or Entity ID) field in your identity provider application configuration, copy the AUDIENCE (ENTITYID) URI value from BMC Helix Network Management and paste it into the appropriate field.
   • For the Recipient (or ACS Consumer) fields in your identity provider application configuration, copy the ACS (CONSUMER) URL value from BMC Helix Network Management and paste it into the appropriate fields.
     • Some identity providers combine the recipient and ACS consumer into a single field, while others use separate fields. The same value is used for both.
     • BMC Helix Network Management does not use ACS URL validation. Consult your identity provider documentation for the proper value to use in the validator field, if present. (Wildcard is a common value.)
   • For the initiator field select Service Provider.
   • For the name ID format select Email.
   • For signature element select Both.
   • Set all remaining options as appropriate for your organization (timeout duration, etc.).
6. In the Identity Provider Configuration panel in BMC Helix Network Management:
   • Copy the issuer URL from your identity provider and paste that value into the ENTITY ID field.
     • (This value is likely found in the SSO section of the application you created above. Look for metadata in the URL to identify the correct URL to copy.)
   • Copy the login endpoint URL from your identity provider and paste that value into the LOG IN URL field.
     • (This value is likely found in the SSO section of the application you created above. Look for login or sso in the URL to identify the correct URL to copy.)
   • Copy the X.509 certificate string from your identity provider and paste it into the X509 CERTIFICATE STRING field.
     • (This value is likely found in the SSO section of the application you created above. Copy/paste the string exactly as provided by the identity provider. Leave newlines intact. Do not attempt to format the string.)
   • If you are using Azure SAML, you may need to select OFF for the INCLUDE SUBJECT IN REQUEST field.
     • Azure SAML doesn't accept how regular SAML is processed. In a typical SAML environment, one of the objects sent back is the subject, but Azure won't accept that object when it's in the payload. Since Azure may require the subject parameter to be omitted from the login request, the toggle should be OFF when using Azure AD. If you wish to follow the normal SAML 2.0 standard the toggle should be ON.
7. If you have an Active Directory account associated with your identity provider account, BMC Helix Network Management supports the use of a user permission mapping attribute key and values. This allows you to provide a higher BMC Helix Network Management user access level to certain accounts. All other accounts default to the "User" access level, which has the least privileges. (These must initially be set up as parameters in the identity provider application you created above. Then the matching attribute key and attribute values must be added to BMC Helix Network Management using the following steps.)
   1. In the User Mapping Permissions panel in BMC Helix Network Management:
      1. In the ATTRIBUTE NAME field enter the name of the Active Directory group attribute key configured in your identity provider application.
      2. For each BMC Helix Network Management user access level  field enter the attribute value configured in your identity provider application that corresponds to the group that you wish to have that access level.
         • BMC Helix Network Management supports the use of user groups containing additional nested groups.
   2. If you do not provide user mapping permissions here, all users will be logged in to BMC Helix Network Management at the "User" access level.
8. Select Save.

All user log-ins are now managed by your identity provider. However, any logged in users must log out and log back in again for the change to take effect.