System Settings reference
This page provides information for creating or reviewing payload JSON files that are involved in the configuration of system settings.
The following code sample shows the system settings that you can include within such a file. The rest of this page provides details about each of these system settings.
"saml2IdentityProvider": {
"metadataUrl": "https://dba-life:8443",
"enabled": false,
"serviceProviderInformation": {
"entityID": "Control-M_appId",
"ssoUrls": [
"https://dba-life:8443"
]
},
"forceAuthentication": true
},
"ldapSettings": {
"ldapEnabled": true,
"defaultDomain": "prod",
"domains": [
{
"domainName": "prod",
"directorySearchUser": "emuser@prod.bmc.com",
"directorySearchPassword": "*****",
"communicationProtocol": "TCP",
"directoryServerType": "Active Directory",
"serverHostNameAndPort": [
{
"physicalHostname": "prod.bmc.com",
"port": "1234"
}
],
"directorySearchBase": ["prod.bmc.com"]
}
]
}
}
SAML2 Identity Provider settings
The first element in the JSON list of system settings, Saml2IdentityProvider, focuses on settings for integration of a SAML2 identity provider (IdP) with Control-M. The following properties are included:
Property | Description |
|---|---|
metadataUrl | Points to the location of SAML2 metadata that you obtained from your identity provider. You can choose from the following options:
|
enabled | Whether the SAML2 IdP is enabled in your environment, either true or false Note: After you enable the SAML2 IdP, certain user authorization management actions are no longer relevant and cannot be performed. These include adding, updating, or deleting a user, as well as getting user details. |
serviceProviderInformation | Attributes generated by Control-M for enabling integration with a SAML2 IdP. |
entityID | An ID that dictates the entity or audience for SAML2 assertions for the internal IdP in Control-M You obtain this property value by running the config systemsettings::get API command. |
ssoUrls | A list of URLs for single sign-on, where SAML2 assertions are sent by the internal IdP in Control-M This property is read-only. You obtain the value of this property by running the config systemsettings::get API command, but you cannot modify its value using the config systemsettings::set API command. |
forceAuthentication | Whether to force re-authentication of users even if the user has a SSO session at the IdP, either true or false The default is true. |
Steps for enabling a SAML2 IdP
A typical end-to-end process for enabling a SAML2 IdP consists of the following steps:
- Obtain values for the two properties that pertain to the internal IdP in Control-M — ssoUrls and entityID — by running the config systemsettings::get API command.
- Obtain SAML2 metadata from your SAML2 IdP, either as a URL or as an XML file.
- Use the output from step 1 as a template for creation of a System Settings .json file.
In the same file, set the metadataUrl property to the relevant value (from step 2) and the enabled property to true. - Run the config systemsettings::set API command and provide the System Settings .json file (that you prepared in step 3) as a payload file for this API command.
If you set the metadataUrl property in the .json file to metadata, you must also provide a SAML2 Metadata file in XML format.
After completing this setup, if at any point you want to review the SAML2 metadata from your SAML2 IdP, you can run the config systemsettings:identityprovidermetadata::get API command.
LDAP system settings
Through the JSON file, you can define the LDAP settings used for authentication of users. The following table summarizes and describes the available properties.
Property | Description |
|---|---|
ldapEnabled | Whether LDAP authentication is enabled, either true or false. The default is false. Note: If a SAML2 identity provider is enabled, it takes precedence over LDAP user authentication. In such a case, ldapEnabled=true is ignored. |
defaultDomain | Name of the default domain |
domains | Details of all the domains that host LDAP servers that authenticate users |
domainName | Name of the domain |
directorySearchUser | Name of the user that runs the search action for users that log on. For example, admin@company.us.com or cn=admin,dc=company,dc=us,dc=com. If this property is not defined, then you must specify a value for the directorySearchBase property. |
directorySearchPassword | Password of the user that runs the search action (previous property). If this user does not have a defined password, set this property to an empty value. |
communicationProtocol | The transmission protocol that LDAP uses to connect to Control-M, either TCP or SSL. The default is TCP. |
directoryServerType | Type of configuration used for authentication by the LDAP server. Type of LDAP configuration used for authentication. Valid values for this property are as specified in the DirectoryServiceType.cfg configuration file located in the ctm_em/etc directory. For more information, see DirectoryServiceType.cfg parameters in the Control-M Online Help. |
serverHostNameAndPort | A list of LDAP server hosts. Each LDAP server host is defined by the following properties:
|
directorySearchBase | The starting domain name for the user search in the directory tree structure. For example, sales.company.us.com or dc=sales,dc=company,dc=us,dc=com. This property must have a specified value if the directorySearchUser property is not defined. Otherwise, the default value is the domain where the search user is located. |