Defining System Settings

This procedure describes how to configure IdP configuration,and LDAP configuration.

Begin

  1. From the Configuration domain, click and then select System Settings.

    The System Settings pane appears.

  2. Configure an Identity Provider (IdP), as described in Configuring Authentication with an IdP.

  3. Configure LDAP authentication, as described in Configuring Authentication with LDAP.
  4. Click Save.

Configuring Authentication with an IdP

This procedure describes how to configure authentication with an Identity Provider (IdP) for all Control-M users. This enables you to authenticate multiple external users with one configuration instead of creating individual internal users in Control-M.

To set up SSO authentication for Control-M Web through an Apache proxy server, see Configuring SSO Authentication through a Proxy Server (Deprecated).

Begin

  1. From the Identity Provider (IdP) drop-down, toggle on Enable SAML 2.0.

  2. Toggle on Force Authentication, if you want to force users to re-authenticate at login, even if they have an open SSO session in the IdP.

  3. Copy the following field values by clicking and paste them in your IdP application configuration.

    • Single sign-on URL: Defines the IdP URL(s) or SAML Endpoint, where Control-M redirects users to sign in.

      If you need to modify the external base URL if Control-M/EM is behind a reverse proxy or the load balancer name is different from the internal hostname, you need to log in to the Control-M/EM server host and run the following command:

      util --setIdpValveExternalBaseURL <base url>

      where

      • <base url> is https://<hostname>:<port>.

      • <port> is the https_port from the CONFIG_HA database table.

      • <hostname> is the hostname with the domain name.

      • <hostnameS> is the hostname.

      • If you are working in a High Availability environment, you need to copy the Single Sign-on URL from both the primary and secondary to your IdP. The secondary URL appears after at least one failover occurs.

    • Audience URI (Service Provider entity ID): Defines the Service Provider URI that is used for verification.

  4. From your IdP, you need to define the groups attribute.

    The attribute value must be the group names defined in the IdP (case-sensitive).

  5. Generate the XML meta-data from your IdP and insert the XML file path with a file saved locally or provide the meta-data document endpoint URL.

    If you disable SAML 2.0, you cannot remove the XML meta-data file.

  6. After you have completed this procedure, you need to map the groups from the IdP to rolesClosedAn authorization entity that grants permissions to associated users to access different functionality, as described in Adding a Role.

    All Control-M users that connect to the web interface, CCM, or Control-M client are now authenticated with SAML 2.0. All Control-M users that access CLI utilities are authenticated with user/password and not with SAML 2.0.

  7. Log in with a local Control-M/EM user to the following to bypass IdP settings and connect to Control-M directly:

    https://<host>:<port>/local

  8. Add new roles or update existing roles with groups from your IdP.

Configuring Authentication with LDAP

This procedure describes how to configure authentication with LDAP for all Control-M users. This enables you to authenticate multiple external users with one configuration instead of creating individual internal users in Control-M.

  1. From the Active Directory (LDAP) drop-down, toggle on Enable LDAP.

  2. In the Domain field, click , and type the Domain Name of the Active Directory that you want to use to authenticate Control-M users.

  3. In the LDAP Directory Search User field, name of the user that runs the search action for users that log in.

    If this field is not defined, then the LDAP Directory Search Base field must have a value.

    cn=admin,dc=company,dc=us,dc=com.

  4. In the LDAP Directory Search Password field, type the password of the user specified in the LDAP Directory Search User field.

    The value of this field can be empty if the Search user does not have a defined password.

  5. From the Communication Protocol drop-down list, select one of the following transmission protocols that LDAP uses to connect to Control-M/EM:

    • TCP

    • SSL

    BMC recommends that you configure the SSL between Control-M clients and Control-M/EM servers before you define LDAP, as described in Configuring SSL on Control-M Web Server.

  6. In the LDAP Directory Server Type, select which LDAP configuration is used for authentication.

    The values in the drop-down list are taken from the DirectoryServiceType.cfg configuration file located in the ctm_em/etc directory. This file contains the names of the default types used by the system parameters, including a set of default parameters that define the standard configuration of the specific type. For more information, see DirectoryServiceType.cfg Parameters.

  7. In the Server Host Name and Port field, define the hostname and port number values for the computer where the LDAP Directory Server is located.

    It is not mandatory to set the port value for this system parameter. If the port is empty, the default value 389 (or 636 for SSL communication) is used.

    You can also define multiple active directory servers. This enables Control-M/EM to perform authentication against backup active directory servers when the primary server is unavailable.

  8. In the LDAP Directory Search Base field, define the starting domain name for the user search in the directory tree structure.

    This field must have a value if the LDAP Directory Search User field is left blank. Otherwise the default value is the domain where the search user is located.

    sales.company.us.com or dc=sales,dc=company,dc=us,dc=com

DirectoryServiceType.cfg Parameters

The following table describes the parameters listed in the DirectoryServiceType.cfg file.

After you edit any of the parameters in this table and save the DirectoryServiceType.cfg configuration file located in the ctm_em/etc directory, you must refresh the various components and servers with the changes.

Parameter

Description

Default Value

DirectoryUsersDnAttr

Defines the LDAP users distinguished name attribute name defined in the directory schema

  • AD: distinguishedName

  • Other: dn

DirectoryUsersIDAttr

Defines the LDAP user attribute required to log in to Control-M/EM

  • AD: sAMAccountName

  • Other: cn

DirectoryGroupIDAttr

Defines the LDAP attribute used when looking for group names.

  • AD: sAMAccountName

  • Other: cn

DirectoryGroupMembersAttr

Defines the LDAP attributes of groups that stores its members

  • AD: member

  • Other: uniqueMember

DirectoryGroupMembersIDAttr

Defines the users that are assigned within the members attribute of groups

  • AD: distinguishedName

  • Other: dn

DirectoryGroupsObjectClassAttr

Defines the object class attribute that defines the LDAP entry for groups

  • AD: group

  • Other: groupOfUniqueNames

Configuring SSO Authentication through a Proxy Server (Deprecated)

This procedure describes how to set up SSO authentication for Control-M Web through an Apache proxy server and an integration with Okta that uses the Shibboleth module and the SAML protocol.

This procedure involves the following major tasks:

  1. Configuring Authentication with LDAP
  2. Configuring the Shibboleth Module for SSO
  3. Configuring SSO in Control-M

For additional troubleshooting information and configuration examples, see Knowledge Base article 000171811.

Configuring the Apache Proxy Server for SSO

This procedure describes how to configure an Apache proxy server for SSO authentication in Control-M Web.

All paths in this procedure are based on /etc/httpd as the location of the home directory of the Apache HTTP Web server. If you installed the Apache server in a different location, adjust all paths accordingly.

Before you begin

  • Install an Apache HTTP Web server, preferably on a dedicated VM (for optimal performance).

  • Install the following modules to support integration with Okta and Shibboleth:

    • mod_ssl.so

    • mod_proxy.so

    • mod_shib_24.so

    • mod_php.so

      To avoid compatibility issues, ensure that the Shibboleth library that you install is mod_shib_24.so. In BMC testing, the shibboleth-3.0.3-1.1.x86_64 installation package was used and was found to contain the appropriate Shibboleth module.

Begin

  1. Use the vi command to edit the httpd.conf file, located in /etc/httpd/conf/. Apply the following edits and save the file:

    • Update the ServerName variable with host and port, as in the following example:

      ServerName host-apache.myorg.com:80

    • Specify the Listen IP of the Apache server host:

      Listen xxx.xxx.xxx.xxx:80

    • Update the DocumentRoot variable, as in the following example:

      DocumentRoot "/var/www/html"

  2. Use the following command to receive a list of the available configuration files:

    ls -tl /etc/httpd/conf.d/*.conf

  3. Ensure that the following configuration files are listed in the output from the previous step:

    • shib.conf — Context root settings. For the configuration required in this file, see step 4.

    • httpd-ssl.conf — SSL settings. For the configuration required in this file, see step 5.

    • httpd-default.conf — Default configuration

    • php.conf — PHP module configuration. Ensure that the PHP package is installed on this server.

      File names might vary, depending on the module version installed. For example, php.conf might appear as rh-php_72.conf.

  4. In shib.conf, perform the following edits:

    1. Verify that LoadModule mod_shib points to the correct path of the shared library:

      LoadModule mod_shib /usr/lib64/shibboleth/mod_shib_24.so

    2. Verify that the Location section does not include a relative path and that the following elements are included:

      Copy 
      <Location />
      	AuthType shibboleth
      	ShibRequestSetting requireSession 1
      	ShibUseHeaders On
      	require shibboleth
      </Location>

  5. Configure SSL settings by performing the following steps:

    1. Generate a Certificate Signing Request (CSR) and key file and provide the CSR file to the Certificate Authority (CA) to be signed.

      The CA entity provides you with a root CA certificate and intermediate CA certificate, to be specified in the next step. Ensure that these files are in PEM format. Self-signed certificates are not supported in this configuration.

      The CN that you provide to the CA entity is also used as the ServerName in the next step.

    2. In the httpd-ssl.conf file, provide updated values for the SSL settings that are highlighted in bold below:

      SSLSessionCache shmcb:/etc/httpd/run/ssl_scache (512000)
      SSLSessionCacheTimeout 300
      SSLPassPhraseDialog exec:conf/ssl.crt/passwd.sh
      Listen *:443
      <VirtualHost *:443>
      DocumentRoot "/var/www/http"
      ServerAlias host-apache.myorg.com:443
      ServerName host-apache.myorg.com:443
      ServerAdmin ai@myorg.com
      LimitRequestFieldsize 65535
      SSLEngine on
      SSLCipherSuite ALL:!ADH:!EXPORT56:+HIGH:+MEDIUM:-LOW:-SSLv2:-RC4:-EX
      SSLProtocol +SSLv3 +TLSv1.2
      SSLCertificateFile /etc/httpd/conf/ssl/host-apache.crt
      SSLCertificateKeyFile /etc/httpd/conf/ssl/host-apache.key
      SSLCACertificateFile /etc/httpd/conf/ssl/host-apache-intermediate.crt
      SSLOptions +StdEnvVars +ExportCertData
      </VirtualHost>
    SSLProxyEngine on

  6. In the httpd-proxy.conf file, replace the parameters highlighted in bold below with the location of the Control-M Web server (the Tomcat server), and verify that all other parameter values appear as in the following example:

    SSLProxyVerify none
    SSLProxyCheckPeerCN off
    SSLProxyCheckPeerName off
    SSLProxyCheckPeerExpire off
    ProxyRequests off
    ProxyPreserveHost On
    ProxyPass /Shibboleth.sso/ !
    ProxyPass /uname !
    ProxyPass /ControlM https://control-m.myorg.com:8443/ControlM
    ProxyPass /Reports https://control-m.myorg.com:8443/Reports
    ProxyPass /RF-Server https://control-m.myorg.com:8443/RF-Server
    ProxyPass /automation-api https://control-m.myorg.com:8443/automation-api
    ProxyPass /sls-apps https://control-m.myorg.com:8443/sls-apps
    ProxyPassReverse /ControlM https://control-m.myorg.com:8443/ControlM
    ProxyPassReverse /Reports https://control-m.myorg.com:8443/Reports
    ProxyPassReverse /RF-Server https://control-m.myorg.com:8443/RF-Server
    ProxyPassReverse /automation-api https://control-m.myorg.com:8443/automation-api
    ProxyPassReverse /sls-apps https://control-m.myorg.com:8443/sls-apps

  7. Recycle the Apache HTTP Web server.

    On a Linux host, you can run the following commands from /etc/httpd/sbin:

    ./apachectl stop
    ./apachectl start

    Alternatively, if an Apache service is configured, you can use the following commands:

    systemctl stop apache
    systemctl start apache

Configuring the Shibboleth Module for SSO

This procedure describes how to configure the Shibboleth module for SSO authentication in Control-M Web.

Begin

  1. Use the following command to receive a list of available Shibboleth configuration files:

    ls -tl /etc/shibboleth/*.xml

  2. Ensure that the following configuration files are listed in the output from the previous step.

    • example-metadata.xml — Okta entity ID configuration. For the configuration required in this file, see step 3.

    • shibboleth2.xml — Okta application configuration. For the configuration required in this file, see step 4.

    • attribute-map.xml — Okta header configuration. For the configuration required in this file, see step 5.

  3. Rename the example-metadata.xml file to a more meaningful name (such as ApacheHost-metadata.xml), and update the parameters in this file with local values from your Okta administrator:

    • “entityID="http://www.okta.com/MY-OKTA-ID"”
    • HTTP-POST:
      Location="https://myorg.okta.com/app/bindingaddress/MY-OKTA-ID/sso/saml"/>
    • HTTP:Redirect:
      Location="https://myorg.okta.com/app/bindingaddress/MY-OKTA-ID/sso/saml"/>

  4. In the shibboleth2.xml file, provide appropriate values for the parameters highlighted in bold below:

    <ApplicationDefaults entityID=”https://host-apche.MYORG.com/shibboleth”>
    ...
    <SSO entityID=”http://www.okta.com/MY-OKTA-ID”>
    ...
    <MetadataProvider type="XML" validate="true" path="ApacheHost-metadata.xml"/>
    ...
    </ApplicationDefaults>

  5. In the attribute-map.xml file, ensure that SSO user ID values are specified as in the following sample:

    Copy 
    <Attribute
    name="SSOUSERID" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" id="SSOUSERID"> <AttributeDecoder xsi:type=" StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>

  6. Recycle the Shibboleth service by running the following commands:

    service shibd stop
    service shibd start

Configuring SSO in Control-M

This procedure describes how to complete the configuration of SSO authentication through a proxy server in Control-M.

Begin

  1. In Control-M Configuration Manager, right-click the Control-M EM component and select System Parameters.

  2. Configure the following system parameters:

    1. In the Advanced category, set the value of SSO to ON.

    2. In the Advanced category, modify SSOUserIdParamName to SSOUSERID, the name used in the Okta setup.

    3. In the LDAP category, add a domain for SSO authentication and define its LDAP system parameters, and an LDAP group for SSO authentication, as described in Configuring Authentication with LDAP.