POST | Create LDAP group sync

Description

Create an LDAP group synchronization in the Segura™ platform. A single request binds an Active Directory group, identified by a distinguished name and an LDAP filter, to a user group, assigns the ACL roles its members receive, and optionally configures the Domum block.

The synchronization is created in the active state. Creating it does not import any user: run POST | Run LDAP group sync to start the first import.

Prerequisites

An application with the Users authorization granted by the administrator in A2A, and its resource permission set to Read and write. For more information, access How to manage authorizations in A2A.
A valid OAuth 2.0 access token. For more information, access How to authenticate an application in A2A.
The LDAP server, the user group, and any roles referenced in the request must already exist and be active.
The cote license module must be active to send the domum block.

Info

An access token carries only the authorizations that existed when it was generated. After the administrator enables the Users authorization, generate a new token for the application, an existing token will not gain the new authorization.

Request

POST /api/v2/iam/ldap-group-syncs

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`.

Attention

This endpoint does not support the Idempotency-Key header. Retrying a request creates a second synchronization. Check whether the resource already exists with GET | List all LDAP group syncs before you retry.

Request body

The body carries two objects. group_sync holds the synchronization itself, and domum holds the optional Domum integration.

`group_sync`

Field	Type	Required	Description
`name`	string	Yes	Name of the synchronization. Maximum 100 characters.
`server_id`	int	Yes	Identification code of the LDAP server. The server must exist and be active.
`user_group_id`	int	Yes	Identification code of the user group that receives the synchronized users. The group must exist and be active.
`synchronization_enabled`	boolean	Yes	Indicates whether the synchronization runs.
`overwrite_user_accesses`	boolean	Yes	Indicates whether the synchronization overwrites the accesses already assigned to a user. Requires `synchronization_enabled` to be `true`.
`force_roles`	boolean	No	Indicates whether the synchronization removes from the user any role that the Active Directory group no longer grants. Default: `true`.
`automatic_sync`	boolean	No	Indicates whether the platform runs the synchronization on its own schedule. Default: `false`.
`dn`	string	Yes	Base distinguished name searched in the directory. Maximum 255 characters.
`ad_username_attribute`	string	Yes	Active Directory attribute read as the username. Maximum 255 characters.
`ad_name_attribute`	string	No	Active Directory attribute read as the full name. Allowed values: `name`, `displayname`, `samaccountname`, `null`. Values are lowercase.
`department_id`	int	No	Identification code of the department assigned to the synchronized users. Accepts `null`.
`ad_query`	string	Yes	LDAP filter that selects the groups to synchronize. Maximum 2048 characters.
`role_ids`	array of int	No	Identification codes of the ACL roles assigned to the synchronized users.

`domum`

Send this object only when the cote license module is active. Without the license the request returns 422 api.feature.unavailable.

Field	Type	Required	Description
`enabled`	boolean	Yes	Indicates whether the synchronized users receive Domum access.
`type`	string	Yes	Access profile granted in Domum. Allowed values: `full_users`, `limited_users`.
`vendor_id`	int	Conditional	Identification code of the vendor or internal group. Required when `enabled` is `true`.

Example request `POST` `{{url}}/api/v2/iam/ldap-group-syncs`

Body

{
    "group_sync": {
        "name": "Infrastructure operators",
        "server_id": 10,
        "user_group_id": 7,
        "synchronization_enabled": true,
        "overwrite_user_accesses": false,
        "force_roles": true,
        "automatic_sync": false,
        "dn": "OU=Operators,DC=example,DC=com",
        "ad_username_attribute": "sAMAccountName",
        "ad_name_attribute": "displayname",
        "ad_query": "(&(objectClass=group)(cn=ops-*))",
        "role_ids": [1, 3]
    },
    "domum": {
        "enabled": true,
        "type": "limited_users",
        "vendor_id": 22
    }
}

Response

HTTP/1.1 201 Created
Location: /api/v2/iam/ldap-group-syncs/501
ETag: "174f80fa9c3b4d2e"

The Location header holds the path of the created synchronization and the ETag header holds its current version. Keep the ETag value, PUT | Update LDAP group sync by [id], PATCH | Partially update LDAP group sync by [id], and DELETE | Delete LDAP group sync by [id] use it in the If-Match header to detect concurrent changes.

Example response body

{
    "data": {
        "id": "501",
        "group_sync": {
            "name": "Infrastructure operators",
            "active": true,
            "server": { "id": "10" },
            "user_group": { "id": "7" },
            "synchronization_enabled": true,
            "overwrite_user_accesses": false,
            "force_roles": true,
            "automatic_sync": false,
            "dn": "OU=Operators,DC=example,DC=com",
            "ad_username_attribute": "sAMAccountName",
            "ad_name_attribute": "displayname",
            "department": null,
            "ad_query": "(&(objectClass=group)(cn=ops-*))",
            "roles": [{ "id": 1 }, { "id": 3 }]
        },
        "domum": {
            "enabled": true,
            "type": "limited_users",
            "vendor": { "id": 22 }
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-group-syncs/501" },
        "actions": {
            "sync": "/api/v2/iam/ldap-group-syncs/501/sync",
            "deactivate": "/api/v2/iam/ldap-group-syncs/501/deactivate"
        }
    }
}

Response body fields

Field	Type	Description
`data`	object	The created synchronization.
`meta`	object	Links and the actions available for the resource in its current state.

`data`

Field	Type	Description
→`id`	string	Unique identification code of the synchronization, assigned by Segura™.
→`group_sync`	object	The synchronization settings.
→`domum`	object	The Domum settings. Returned only when the `cote` license module is active.

`data.group_sync`

Field	Type	Description
→→`name`	string	Name of the synchronization.
→→`active`	boolean	Indicates whether the synchronization is active. A new synchronization is always created as `true`.
→→`server`	object	The LDAP server, as `{ "id": <string> }`. The request sends `server_id`.
→→`user_group`	object	The user group, as `{ "id": <string> }`. The request sends `user_group_id`.
→→`synchronization_enabled`	boolean	Indicates whether the synchronization runs.
→→`overwrite_user_accesses`	boolean	Indicates whether the synchronization overwrites accesses already assigned to a user.
→→`force_roles`	boolean	Indicates whether the synchronization removes roles the Active Directory group no longer grants.
→→`automatic_sync`	boolean	Indicates whether the platform runs the synchronization on its own schedule.
→→`dn`	string	Base distinguished name searched in the directory.
→→`ad_username_attribute`	string	Active Directory attribute read as the username.
→→`ad_name_attribute`	string	Active Directory attribute read as the full name. Returns `null` when the attribute sent is not supported.
→→`department`	object	The department assigned to the synchronized users. Returns `null` when not set.
→→`ad_query`	string	LDAP filter that selects the groups to synchronize.
→→`roles`	array of objects	The ACL roles assigned, each as `{ "id": <int> }`. The request sends `role_ids`.

`data.domum`

Field	Type	Description
→→`enabled`	boolean	Indicates whether the synchronized users receive Domum access.
→→`type`	string	Access profile granted in Domum. Returns `full_users` or `limited_users`.
→→`vendor`	object	The vendor or internal group, as `{ "id": <int> }`. The request sends `vendor_id`.

Attention

Sending ad_name_attribute with a value the platform recognizes but does not support returns 201 Created and stores null. Check the ad_name_attribute value in the response to confirm the attribute was accepted.

Errors

HTTP code	Message	Possible cause	Solution
`400`	`api.request.malformed`	The body is not valid JSON.	Check the JSON syntax and resend the request.
`403`	`api.permission.denied`	The application lacks permission for this resource.	Ask the administrator to check the application's Users authorization in A2A.
`422`	`api.validation.required_field`	A required field is missing or `null`.	Send every required field listed in the request body tables.
`422`	`api.validation.invalid_type`	A field has the wrong primitive type.	Check the `Type` column in the request body tables.
`422`	`api.validation.length_exceeded`	A string is longer than the column allows.	Shorten the value to the maximum documented for the field.
`422`	`api.validation.invalid_reference`	`server_id`, `user_group_id`, `department_id`, an entry in `role_ids`, or `domum.vendor_id` does not exist.	Confirm the referenced resources exist before you resend the request.
`422`	`api.validation.server.inactive`	`server_id` points to an inactive LDAP server.	Activate the server, or reference an active one.
`422`	`api.validation.user_group.inactive`	`user_group_id` points to an inactive user group.	Activate the group, or reference an active one.
`422`	`api.validation.overwrite.requires_sync_enabled`	`overwrite_user_accesses` is `true` while `synchronization_enabled` is `false`.	Set `synchronization_enabled` to `true`, or set `overwrite_user_accesses` to `false`.
`422`	`api.validation.unknown_field`	The body carries a key that is not part of the resource schema.	Remove the key. Check that the body uses the `group_sync` and `domum` objects.
`422`	`api.enum.invalid_value`	`ad_name_attribute` or `domum.type` is outside its allowed values.	Send one of the allowed values listed in the request body tables.
`422`	`api.feature.unavailable`	The `domum` block was sent without the `cote` license module.	Remove the `domum` block, or ask the administrator to license the module.
`422`	`ldap_group_sync.domum.vendor_required`	`domum.enabled` is `true` without `domum.vendor_id`.	Send `domum.vendor_id`.
`429`	`rate_limit_exceeded`	The application exceeded its request quota.	Wait for the period in the `Retry-After` header and resend the request.

Authentication errors

Message	Possible cause	Solution
`Client authentication failed.`	Application authentication failure with the Segura server.	Check the authentication parameters (`Access Token URL`, `Client ID`, and `Client secret`) and request a new access token.
`Invalid signature`	Failure in recognizing the client application URL.	Check the URL of the client application and resend the request.
`No route matched with those values.`	Missing authorization header in the API request.	Request a new access token.
`Request timed out.`	The request exceeded the timeout limit.	Check the connectivity between the source of the request and the Segura server.