<access-service>/api/v1/ldapconnections

URL structure

https://access-service.xy-company.com/api/v1/ldapconnections

Supported methods and overview

• POST - adds a new LDAP connection.
• GET - retrieves a list of field information for all LDAP connections configured on the Cocoon Data Platform.

Note: The GET method takes no parameters.

Detailed description

This API endpoint serves a number of purposes:

• Adds a new connection to an LDAP server/user directory on the Cocoon Data Platform.
  Notes:
  • Before calling this API endpoint:
    • Be aware that adding at least one LDAP connection (through this API endpoint) permanently disables the ability to add more organisations to the Cocoon Data Platform - i.e. doing so permamently disables successful calls to the POST method on the <access-service>/api/v1/organisations endpoint.
    • Ensure that at least one plan has been configured in the one organisation configured on the Cocoon Data Platform instance. For more information see <access-service>/api/v1/organisations/{orgGroupId}/plans.
  • To test that the Cocoon Data Platform can successfully connect to the LDAP server/user directory first before adding the LDAP connection itself, call the <access-service>/api/v1/ldapconnections/availability API endpoint (before calling the POST method on this API endpoint).
  • All accounts in the LDAP user directory will appear as new user accounts in the one configured organisation when the Cocoon Data Platform next synchronizes with the LDAP server.
  • All new LDAP user accounts added to the Cocoon Data Platform from an LDAP server/user directory automatically have the Originator role and are assigned the default plan.
  • If the email address of an existing user account on the Cocoon Data Platform matches that of the emailField of a user in the LDAP user directory, then a new account will not be added to the Cocoon Data Platform for that account in LDAP (during synchronization).
• Retrieves a list of field information for all LDAP connections configured on the Cocoon Data Platform.

Supported roles and conditions

This API endpoint supports the following Cocoon Data user roles (as described in the SafeShare Administrator's Guide):

• SafeShare administrator - using the:
  • POST method, when only one organisation has been configured on the Cocoon Data Platform. To retrieve information about all configured organisations on the Cocoon Data Platform, see <access-service>/api/v1/organisations.
  • GET method, without any futher conditions.

The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria above is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

The following header is required if the body of the request has a JSON object:

• Content-Type: application/json

Required parameters

The following required parameters must be sent in the body of the POST request, each as individual members of a JSON object:

• serverUrl - .
• serverTimeout - .
• managerDN - .
• managerPassword - .
• baseDN - .
• syncFilter - .
• authFilter - .
• domain - .
• accountNameField - .
• emailField - .
• userPrincipalNameField - .
• fullnameField - .
• statusField - .
• statusDisabledValue - .
  Example (request):

  {
    "serverUrl":"ldap://ldap.xy-company.com",
    "serverTimeout":45000,
    "managerDN":"cn=server sync,cn=users,dc=xy-company,dc=com",
    "managerPassword":"password",
    "baseDN":"ou=users,dc=xy-company,dc=com",
    "syncFilter":"(&(memberOf=ou=users,dc=xy-company,dc=com)(userPrincipalName=*@xy-company.com))",
    "authFilter":"userPrincipalName={0}",
    "domain":"XY-COMPANY",
    "accountNameField":"sAMAccountName",
    "emailField":"mail",
    "userPrincipalNameField":"userPrincipalName",
    "fullnameField":"name",
    "statusField":"userAccountControl",
    "statusDisabledValue":"2"
  }

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful requests only, a JSON-formatted response containing the following members is also returned:

• items ( from GET requests only ) - .
  • id - .
  • serverUrl - .
  • serverTimeout - .
  • baseDN - .
  • authFilter - .
  • managerDN - .
  • managerPassword - .
  • syncFilter - .
  • domain - .
  • enabled - .
  • emailField - .
  • userPrincipalNameField - .
  • statusField - .
  • statusDisabledValue - .
  • accountNameField - .
  • fullnameField - .
  • modifiedAt - .
  • createdAt - .
• count ( from GET requests only ) - .
• offset ( from GET requests only ) - .
  Example (response from a GET request):

  {
      "items":[
          {
              "id":"1000000",
              "serverUrl":"ldap://ldap.xy-company.com",
              "serverTimeout":45000,
              "baseDN":"ou=users,dc=xy-company,dc=com",
              "authFilter":"userPrincipalName={0}",
              "managerDN":"cn=server sync,cn=users,dc=xy-company,dc=com",
              "managerPassword":"password",
              "syncFilter":"(&(memberOf=ou=users,dc=xy-company,dc=com)(userPrincipalName=*@xy-company.com))",
              "domain":"XY-COMPANY",
              "enabled":true,
              "emailField":"mail",
              "userPrincipalNameField":"userPrincipalName",
              "statusField":"userAccountControl",
              "statusDisabledValue":"2",
              "accountNameField":"sAMAccountName",
              "fullnameField":"name",
              "modifiedAt":"2016-10-27T00:39:55.604Z",
              "createdAt":"2016-10-27T00:39:55.604Z"
          }
      ],
      "count":"1",
      "offset":"0"
  }