Authentication

Control-M supports the following methods to authenticate Control-M users:

  • Control-M: Authenticates individual users that are created manually within Control-M, as described in Creating an Internal User.

  • Identity Provider (IdP): Authenticates multiple external users with one configuration, instead of creating multiple individual internal users in Control-M, as described in Configuring Authentication with an IdP. In addition IdP supports Single Sign-on (SSO) and Multi-factor Authentication (MFA). You must configure MFA on your identity provider. You can configure authentication to one IdP.

  • LDAP: Authenticates multiple external users with one configuration, instead of creating multiple individual internal users in Control-M, as described in .Configuring Authentication with LDAP. You can configure authentication to multiple LDAP domains.

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 multiple individual internal users in Control-M.

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

  • If SSO was previously enabled, verify that it's disabled before you configure IdP.

  • If both IdP and LDAP are enabled, CLI utilities are authenticated with LDAP. If IdP is disabled and LDAP is enabled, Control-M Web, Control-M Desktop, CCM, CLI utilities and Mobile are authenticated with LDAP.

  • If IdP is down, you can log in with a local Control-M/EM user, to bypass IdP settings and connect to Control-M directly, with the following URL:

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

Before You Begin

  • (Control-M Desktop and CCM only) Verify that all IdP users have installed Microsoft WebView2.

    If IdP users have installed the fixed binaries version, they must define the path to the WebView2 installation in the EMCLIENT_WEBVIEW2_HOME environment variable.

Begin

  1. From the icon, select Configuration.

    The Configuration domain appears.

  2. From the drop-down list, select System Settings.

    The System Settings pane appears.

  3. From the Identity Provider (IdP) drop-down, select the SAML 2.0 checkbox.

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

  5. Copy the following field values by clicking , and paste each value in your IdP application configuration.

    • Single Sign-On URL: Defines the IdP URLs or SAML Endpoint, where Control-M redirects users to sign in.

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

      emutil --setIdpValveExternalBaseURL <base url>

      where:

      • <base url> is one of the following:

        • https://<hostname>:<port>

        • https://<hostname>

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

      • <hostname> is the FQDN name.

        In some cases, you might need to define a logical name as the value, such as when you use a reverse proxy or a load balancer.

      • 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.

    • Signing Certificate: Defines the certificate that ensures that messages are coming from the expected IdP and Service Providers. The SAML certificate is used to sign SAML requests, responses, and assertions from the service to the connected applications. The signing certificate is available in the idp-valve-sp-metadata.xml file in the following location:

      <EM_HOME>/ini/saml

  6. From your IdP, you need to define the groups and username attribute.

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

  7. From your IdP, generate the XML metadata file and do one of the following:

    • Click Select File and browse for the XML metadata file on your machine.

    • In the XML Metadata for SAML Service Provider field, type the XML metadata file endpoint URL.

    If you disable SAML 2.0, you cannot remove the XML metadata file.

  8. After you have completed this procedure, you must map the groups from the IdP to rolesClosed An 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 Control-M Web, 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.

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

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

  10. 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 users. This enables you to authenticate multiple external users with one configuration, instead of creating multiple individual internal users in Control-M.

If the LDAP domain is down, you can still log in to Control-M with an internal user by selecting Local EM from the Domain drop-down list.

  1. From the icon, select Configuration.

    The Configuration domain appears.

  2. From the drop-down list, select System Settings.

    The System Settings pane appears.

  3. From the Active Directory (LDAP) drop-down, select the Enable LDAP checkbox.

  4. From the Domain area, click , and in the Domain Name field of the Add Domain dialog type the domain name of the Active Directory that you want to use to authenticate Control-M users.

  5. In the LDAP Directory Search User field, enter 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

  6. 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.

  7. 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 the Control-M Web Server.

  8. 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.

  9. 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.

  10. 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. Perform the following steps to configure SSL settings:

    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, specified in the next step. Ensure that these files are in PEM format. This configuration does not support self-signed certificates.

      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.