Configuring an LDAP connection by using REST Administration APIs

System administrators can configure an LDAP connection by using REST Administration APIs.

If you want to use a secure LDAP connection, you must upload a certificate to use with the connection. For more information about importing a certificate for an LDAP connection, see Importing and applying a certificate for an LDAP connection by using REST Administration APIs.
You can configure an LDAP connection by using REST Administration APIs, or by using the Amlen WebUI. For more information about using the Amlen WebUI to configure an LDAP connection, see Configuring an LDAP server by using the Amlen WebUI.

For more information about the parameters that you must specify to configure an LDAP connection, see Configuring LDAP for user authentication.

If you want to secure an LDAP connection, you must import an LDAP certificate. For more information about importing an LDAP certificate, see Importing and applying a certificate for an LDAP connection by using REST Administration APIs.

  1. To configure an LDAP connection, use the Eclipse Amlen REST API POST method.
    1. Use the following Eclipse Amlen configuration URI:

      http://<admin-endpoint-IP:Port>/ima/v1/configuration/

    2. Provide LDAP object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown. 
      
{    
  "LDAP": {
    "URL": "string",
    "Certificate": "string",
    "IgnoreCase": true|false,
    "BaseDN": "string",
    "BindDN": "string",
    "BindPassword":  "string",
    "UserSuffix": "string",
    "GroupSuffix": "string",
    "GroupCacheTimeout": integer,
    "UserIdMap": "string",
    "GroupIdMap": "string",
    "GroupMemberIdMap": "string",
    "Timeout": integer,
    "EnableCache": true|false,
    "CacheTimeout": integer,
    "MaxConnections": integer,
    "NestedGroupSearch": true|false,
    "Enabled": true|false,
    "Verify": true|false,
    "Overwrite": true|false 
   }
}
      Where:
      URL
      Required if you are configuring an LDAP connection.
      Specifies the URL of the LDAP server.
      The URL must be of the form: ldap://ipAddress:portNumber or ldaps://ipAddress:portNumber
      If you use ldaps://, you must upload an LDAP certificate before you configure the LDAP connection.
      Certificate
      Specifies the certificate to use if the LDAP URL uses SSL or TLS. This is the name of a certificate in the truststore.
      CheckServerCert
      Available in version 5.0.0.2 and later releases. Possible options are as follows:
      TrustStore
      When connecting to the LDAP server, the certificate that is presented by the server is checked using the certificate that is uploaded to the product trust store.
      PublicTrust
      The certificate that is presented by the LDAP server is checked against the public certificates that are installed as part of the operating system.
      DisableVerify
      No certificate verification is performed when connecting to the LDAP server. This is an insecure option that is designed for testing purposes only.
      IgnoreCase: true|false
      Specifies whether case is ignored (true) or not ignored (false).
      The default value is true.
      BaseDN
      Required if you are creating an LDAP connection.
      Specifies the base distinguished name of the directory service.
      BindDN
      Specifies the distinguished name to use when you bind to LDAP.
      BindPassword
      Specifies the password to use when you bind to LDAP.
      The value of this parameter is not returned on the REST API GET method.
      UserSuffix
      Specifies the distinguished name that is the suffix of the user distinguished name.
      GroupSuffix
      Specifies distinguished name that is the suffix of the group distinguished name.
      GroupCacheTimeout
      Specifies the group cache time to live, in seconds.
      This value must be in the range 1-86400.
      The default value is 300.
      UserIdMap
      Specifies the LDAP filter that maps the short name of a user to an LDAP entry.
      GroupIdMap
      Specifies the LDAP filter that maps the short name of a group to an LDAP entry.
      GroupMemberIdMap
      Specifies LDAP filter that identifies user-to-group relationships.
      Timeout
      Specifies the timeout for LDAP calls, in seconds.
      This value must be in the range 1-60.
      The default value is 10.
      EnableCache: true|false
      Specifies whether the authentication result is cached (true) or not cached (false).
      The default value is true.
      CacheTimeout
      Specifies the cache time to live, in seconds.
      This value must be in the range 1-60.
      The default value is 10.
      MaxConnections
      Specifies the maximum number of concurrent connections that can be made to the LDAP server.
      This value must be in the range 1-100.
      The default value is 10.
      NestedGroupSearch
      Specifies whether to use nested group searching (true) to find the group membership of a user.
      The default value is false which means that nested group searching is not used.
      Enabled: true|false
      Specifies whether the LDAP connection is enabled (true) or disabled (false).
      The default value is true.
      Verify: true|false
      Specifies whether the LDAP connection is tested with the configuration change without committing the configuration change.
      The default value is false which means that the configuration change is committed without first testing the LDAP connection.
      Overwrite: true|false
      Specifies whether an existing certificate is overwritten if the certificates have the same name.
      The default value is false which means that an existing certificate is not overwritten if the certificates have the same name.
  2. Test the LDAP connection by using the same REST API POST method that you used to configure your LDAP connection, but ensure that Verify is set to true.
    • You can test the LDAP connection before you save your LDAP configuration. You must provide information that is required to establish a connection. If you are using TLS, you must ensure that the certificate is uploaded before you include the certificate name in the test connection request.
    • You can test the LDAP connection to ensure that a configured LDAP object is configured correctly. You must ensure that Verify is set to true.
    • You can test changes that you made to a configured LDAP object before you commit the changes. You only need to include the properties that you want to update. The server uses all of the previously set values except those values that are included in the REST request. To change a value, you must set Verify to false.
The following example shows the configuration of an LDAP server connection by using cURL:

curl -X POST \
   -H 'Content-Type: application/json'  \
   -d  '{ 
         "LDAP": {
           "URL": "ldap://192.0.2.0:1000",
           "BaseDN": "ou=DEPT,o=COMPANY,c=COUNTRY",
           "BindDN": "cn=root",
           "BindPassword": "password",
           "UserSuffix": "ou=users,ou=DEPT,o=COMPANY,c=COUNTRY",
           "GroupSuffix": "ou=groups,ou=DEPT,o=COMPANY,c=COUNTRY",         
           "UserIdMap": "*:UID",
           "GroupIdMap": "*:cn",
           "GroupMemberIdMap": "member",
           "Enabled": true
       }
    }
 '  \
http://127.0.0.1:9089/ima/v1/configuration/
An example response to the POST method:

{        
  "Version": "v1",
  "Code": "CWLNA6011",
  "Message": "The requested configuration change has completed successfully."
}
The following example shows how to test that an LDAP URL port can be successfully changed from ldap://192.0.2.0:1000 to ldap://192.0.2.0:1089 by using cURL but without committing the change:

curl -X POST \
    -H 'Content-Type: application/json'  \
    -d  '{
           "LDAP": {
             "URL": "ldap://192.0.2.0:1089",
             "Verify":true
          }
       }
      '  \
http://127.0.0.1:9089/ima/v1/configuration/