LDAP synchronisation
In an existing enterprise environment it would be cumbersome if every user would have to register individually. The periodically run LDAP synchronisation process can automatically synchronise users and groups with an existing LDAP directory such as a Microsoft Active Directory.
Manage LDAP synchronisation settings
Set LDAP synchronisation settings
POST /v<api_version>/admin/ldapsettings/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_settings permission.
- Admins can set the LDAP settings of their own organisation only.
- Superadmins can set the LDAP settings of any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | Yes | All admins | The ID of the organisation to set the LDAP settings for. |
POST data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | Description |
|---|---|---|---|
uri |
String | Yes | The URI of the LDAP server in the format “ldap[s]:// |
synchronisation_interval |
Number | Yes | The interval in minutes between each synchronisation run. Must be a multiple of 5. A value of 0 means the synchronisation does not run automatically. |
connect_attempts |
Number | Yes | The maximum number of attempts to try to connect to the LDAP server during each synchronisation run. |
connect_delay |
Number | Yes | The delay in seconds between each connection attempt to the LDAP server. |
binddn |
String | Yes | The distinguished name (DN) of the LDAP account used to authenticate to the LDAP server, e.g. “uid=twldap,dc=myenterprise,dc=com”. Required for the LDAP synchronisation to work properly. |
bindpw |
String | Yes | The password used to authenticate to the LDAP server. Required for the LDAP synchronisation to work properly. |
schema |
String | Yes | The schema used by the LDAP server, i.e. how the LDAP server stores user and group information. Currently either “inetorgperson” (OpenLDAP, Novell eDirectory) or “ad” (Microsoft Active Directory). |
groups_basedn |
String | Yes | The distinguished name (DN) of the LDAP directory subtree that contains group information. Required for the LDAP synchronisation to work properly. |
group_objects_filter |
String | Yes | A custom LDAP filter expression used to identify group objects. With the default “” (empty string) default filter will be used that depends on the selected schema. |
groups_includelist |
String | Yes | If specified only these LDAP groups and their users will be synchronised. Groups must be separated by comma. |
groups_excludelist |
String | Yes | If specified these LDAP groups and their users will never be synchronised. Groups must be separated by comma. Overrides groups_includelist. |
group_name_attr |
String | Yes | The attribute name expected on an LDAP group object to determine the Teamwire group’s name. With the default “” (empty string) “cn” will be used. |
group_is_public_attr |
String | Yes | The attribute name expected on an LDAP group object to determine whether the Teamwire group will be set to public or not. If empty this field will not be synchronised and groups will be non-public. |
users_basedn |
String | Yes | The distinguished name (DN) of the LDAP directory subtree that contains user information. This is only required if both Active Directory and nested groups are used. |
user_objects_filter |
String | Yes | A custom LDAP filter expression used to identify user objects. With the default “” (empty string) a default filter will be used that depends on the selected schema. |
email_address_attr |
String | Yes | The attribute name expected on an LDAP user object to determine the user’s email address. With the default “” (empty string) “mail” will be used. |
login_password_attr |
String | Yes | The attribute name expected on an LDAP user object to set the Teamwire user’s login password. With the default “” (empty string) the login password will not be synchronised. |
user_profile_department_attr |
String | Yes | The attribute name expected on an LDAP user object to contain a value for a user profile’s “department” field. If empty this field will not be synchronised. |
user_profile_role_attr |
String | Yes | The attribute name expected on an LDAP user object to contain a value for a user profile’s “role” field. If empty this field will not be synchronised. |
user_profile_status_attr |
String | Yes | The attribute name expected on an LDAP user object to contain a value for a user profile’s “status” field. If empty this field will not be synchronised. |
user_profile_phone_attr |
String | Yes | The attribute name expected on an LDAP user object to contain a value for a user profile’s “phone” field. If empty this field will not be synchronised. |
user_profile_email_attr |
String | Yes | The attribute name expected on an LDAP user object to contain a value for a user profile’s “email” field. If empty this field will not be synchronised. |
user_profile_website_attr |
String | Yes | The attribute name expected on an LDAP user object to contain a value for a user profile’s “website” field. If empty this field will not be synchronised. |
user_profile_notes_attr |
String | Yes | The attribute name expected on an LDAP user object to contain a value for a user profile’s “notes” field. If empty this field will not be synchronised. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The LDAP settings have been updated. |
| 400 (Bad request) | The request failed because an invalid parameter was supplied. Inspect the returned error message for details. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) an organisation ID was specified and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because the organisation could not be found. |
| 409 (Conflict) | The request failed because the organisation has been disabled. |
Return LDAP synchronisation settings
GET /v<api_version>/admin/ldapsettings/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_view_settings permission.
- Admins can request the LDAP settings of their own organisation only.
- Superadmins can request the LDAP settings of any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | Yes | All admins | The ID of the organisation to retrieve the LDAP settings for. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information about LDAP synchronisation settings is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) an organisation ID was specified and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because the organisation could not be found. |
| 409 (Conflict) | The request failed because the organisation has been disabled. |
If the request was successful, a single JSON object with the following elements is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
uri |
String | All admins | The URI of the LDAP server in the format “ldap[s]:// |
synchronisation_interval |
Number | All admins | The interval in minutes between each synchronisation run. A value of 0 means the synchronisation does not run automatically. |
connect_attempts |
Number | All admins | The maximum number of attempts to try to connect to the LDAP server during each synchronisation run. |
connect_delay |
Number | All admins | The delay in seconds between each connection attempt to the LDAP server. |
binddn |
String | All admins | The distinguished name (DN) of the LDAP account used to authenticate to the LDAP server, e.g. “uid=twldap,dc=myenterprise,dc=com”. |
bindpw |
String | All admins | The password used to authenticate to the LDAP server. |
schema |
String | All admins | The schema used by the LDAP server, i.e. how the LDAP server stores user and group information. Currently either “inetorgperson” (OpenLDAP, Novell eDirectory) or “ad” (Microsoft Active Directory). |
groups_basedn |
String | All admins | The distinguished name (DN) of the LDAP directory subtree that contains group information. |
group_objects_filter |
String | All admins | A custom LDAP filter expression used to identify group objects. With the default “” (empty string) default filter will be used that depends on the selected schema. |
groups_includelist |
String | All admins | If specified only these LDAP groups and their users will be synchronised. Groups must be separated by comma. |
groups_whitelist |
String | All admins | Deprecated, will be removed – do not use anymore. |
groups_excludelist |
String | All admins | If specified these LDAP groups and their users will never be synchronised. Groups must be separated by comma. Overrides groups_includelist. |
groups_blacklist |
String | All admins | Deprecated, will be removed – do not use anymore. |
group_name_attr |
String | All admins | The attribute name expected on an LDAP group object to determine the Teamwire group’s name. With the default “” (empty string) “cn” will be used. |
group_is_public_attr |
String | All admins | The attribute name expected on an LDAP group object to determine whether the Teamwire group will be set to public or not. If empty this field will not be synchronised and groups will be non-public. |
users_basedn |
String | All admins | The distinguished name (DN) of the LDAP directory subtree that contains user information. This is only required if both Active Directory and nested groups are used. |
user_objects_filter |
String | All admins | A custom LDAP filter expression used to identify user objects. With the default “” (empty string) a default filter will be used that depends on the selected schema. |
email_address_attr |
String | All admins | The attribute name expected on an LDAP user object to determine the user’s email address. With the default “” (empty string) “mail” will be used. |
login_password_attr |
String | All admins | The attribute name expected on an LDAP user object to set the Teamwire user’s login password. With the default “” (empty string) the login password will not be synchronised. |
user_profile_department_attr |
String | All admins | The attribute name expected on an LDAP user object to contain a value for a user profile’s “department” field. If empty this field will not be synchronised. |
user_profile_role_attr |
String | All admins | The attribute name expected on an LDAP user object to contain a value for a user profile’s “role” field. If empty this field will not be synchronised. |
user_profile_status_attr |
String | All admins | The attribute name expected on an LDAP user object to contain a value for a user profile’s “status” field. If empty this field will not be synchronised. |
user_profile_phone_attr |
String | All admins | The attribute name expected on an LDAP user object to contain a value for a user profile’s “phone” field. If empty this field will not be synchronised. |
user_profile_email_attr |
String | All admins | The attribute name expected on an LDAP user object to contain a value for a user profile’s “email” field. If empty this field will not be synchronised. |
user_profile_website_attr |
String | All admins | The attribute name expected on an LDAP user object to contain a value for a user profile’s “website” field. If empty this field will not be synchronised. |
user_profile_notes_attr |
String | All admins | The attribute name expected on an LDAP user object to contain a value for a user profile’s “notes” field. If empty this field will not be synchronised. |
Manage LDAP synchronisation runs
Get the current LDAP synchronisation status
GET /v<api_version>/admin/ldapsync/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_manage_ldap_sync permission.
- Admins can request the synchronisation status of their own organisation only.
- Superadmins can request the synchronisation status of any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | Yes | All admins | The ID of the organisation to retrieve the LDAP synchronisation status for. |
GET parameters
The following parameters are specified as part of the query string
in the URL, i.e. ?param1=value2¶m2=value2:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
sync_log_skip_entries |
Number | No | All admins | Specifies the number of entries to skip when returning the LDAP sync log. Defaults to 0. This can be used to reduce the amount of data returned when an ongoing synchronisation run is being monitored. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information about the current LDAP synchronisation status is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) an organisation ID was specified and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because the organisation could not be found. |
| 409 (Conflict) | The request failed because the organisation has been disabled. |
If the request was successful, a single JSON object with the following elements is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
last_update |
String | All admins | A timestamp in seconds and microseconds since 1970-01-01 00:00:00 UTC indicating when the status has been updated the last time. |
last_run_state |
String | All admins | The last known run state. Either “Unknown” (e.g. sync didn’t run yet), “Running” (right now), “Success” or “Failure”. |
last_run_timestamp |
String | All admins | A timestamp in seconds and microseconds since 1970-01-01 00:00:00 UTC indicating when the last sync run began/finished/was aborted. |
status_msg |
String | All admins | A single-line status message describing the overall status on the last sync run. |
progress |
Number | All admins | A floating point number between 0.0 and 100.0 indicating the total progress of the current LDAP synchronisation run. |
sync_log |
Array | All admins | An array of JSON objects as described below representing the LDAP sync log. |
task_id |
Number | All admins | The internal ID of the currently running sync run task. |
The LDAP sync long is returned as an array of JSON objects with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
date |
String | All admins | A timestamp in seconds and microseconds since 1970-01-01 00:00:00 UTC indicating the time the message was logged. |
severity |
String | All admins | The severity of the log message. Either “INFO”, “WARNING” or “CRITICAL”. |
msg |
String | All admins | The log message. |
Start a LDAP synchronisation run manually
PUT /v<api_version>/admin/ldapsync/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_manage_ldap_sync permission.
- Admins can start a synchronisation run for their own organisation only.
- Superadmins can start a synchronisation run for any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | Yes | All admins | The ID of the organisation to start the LDAP synchronisation for. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. A LDAP synchronisation run has been started. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) an organisation ID was specified and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because the organisation could not be found. |
| 409 (Conflict) | The request failed because the organisation has been disabled. |
Abort an ongoing LDAP synchronisation run
DELETE /v<api_version>/admin/ldapsync/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_manage_ldap_sync permission.
- Admins can abort a synchronisation run for their own organisation only.
- Superadmins can abort a synchronisation run for any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | Yes | All admins | The ID of the organisation for which the current LDAP run should be aborted. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The LDAP synchronisation run has been aborted. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) an organisation ID was specified and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because the organisation could not be found. |
| 409 (Conflict) | The request failed because either a.) the organisation has been disabled or b.) there is currently no sync run active. |