Create or update an LDAP server connection

Purpose

Creates or updates an external LDAP server connection.

URI

Use the Eclipse Amlen REST API POST method with the following Eclipse Amlen configuration URI:

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

Object configuration data

Provide LDAP object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json:


{    
  "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 creating 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 create 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.
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 external 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.; The default value is false which means that an existing certificate is not overwritten.

Usage Notes®

You must copy the LDAP certificate to Eclipse Amlen before you can apply it to Eclipse Amlen. Copy a file from the local machine to Eclipse Amlen to copy the certificate.
You can copy and apply only one LDAP certificate. If you want to upload and apply another certificate, you must overwrite the existing certificate.
The certificate must be a pem format certificate.
After the certificate is applied, it is automatically renamed to ldap.pem
If you update the LDAP certificate, the old LDAP certificate is used until the next time a client or connection is authenticated or authorized.
If you are updating an LDAP certificate in a High Availability (HA) environment, you must upload the new certificate on the primary server and then replicate this certificate on the standby server. For more information about how to update certificates in an HA environment, see Updating a certificate for an LDAP connection in a High Availability environment by using REST Administration APIs.
If you use ldaps://, you might need to add a DNS entry to resolve the host name of the LDAP server.
The new LDAP settings will be used the next time a client or connection is authenticated or authorized.
Ensure that capitalization and double quotation marks are used as shown.

Related REST Administration APIs

Example

Creates 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."
}