User Group Services

Manage User/Group Services through the REST API.

This resource lets administrators list, retrieve, create, update, and delete user/group service configurations (e.g. the default XML file‑based service, or an LDAP service).

Note

You must be authenticated as a user with administrative privileges. Content negotiation is supported via the Accept and Content-Type headers (application/xml and application/json).

Collection

Endpoint

/rest/security/usergroupservices

Methods

  • GET — List configured services.

  • POST — Create a new service.

Item

Endpoint

/rest/security/usergroupservices/{name}

Methods

  • GET — Retrieve a service configuration.

  • PUT — Create or replace {name} with the provided configuration.

  • DELETE — Remove the service {name}.

Warning

The default user/group service (or any service marked as required by the installation) cannot be deleted.

Representations

XML (XMLUserGroupService)

Minimal XML configuration for the built‑in file‑based service:

<org.geoserver.security.xml.XMLUserGroupServiceConfig>
  <name>users1</name>
  <className>org.geoserver.security.xml.XMLUserGroupService</className>
  <fileName>users1.xml</fileName>
  <passwordEncoderName>plainTextPasswordEncoder</passwordEncoderName>
  <passwordPolicyName>default</passwordPolicyName>
</org.geoserver.security.xml.XMLUserGroupServiceConfig>

Important

fileName is required for XMLUserGroupService.

JSON (XMLUserGroupService)

The equivalent JSON payload:

{
  "org.geoserver.security.xml.XMLUserGroupServiceConfig": {
    "name": "users1",
    "className": "org.geoserver.security.xml.XMLUserGroupService",
    "fileName": "users1.xml",
    "passwordEncoderName": "plainTextPasswordEncoder",
    "passwordPolicyName": "default"
  }
}

XML (LDAPUserGroupService)

Example configuration for an LDAP‑backed service:

<org.geoserver.security.ldap.LDAPUserGroupServiceConfig>
  <name>ldapUsers</name>
  <className>org.geoserver.security.ldap.LDAPUserGroupService</className>
  <serverURL>ldap://localhost:10389/dc=acme,dc=org</serverURL>
  <groupSearchBase>ou=groups</groupSearchBase>
  <allGroupsSearchFilter>cn=*</allGroupsSearchFilter>
  <groupSearchFilter>member=uid={0},ou=people,dc=acme,dc=org</groupSearchFilter>
  <userSearchBase>ou=people</userSearchBase>
  <allUsersSearchFilter>uid=*</allUsersSearchFilter>
  <useTLS>true</useTLS>
  <useNestedParentGroups>true</useNestedParentGroups>
  <maxGroupSearchLevel>10</maxGroupSearchLevel>
  <nestedGroupSearchFilter>(member={0})</nestedGroupSearchFilter>
  <bindBeforeGroupSearch>true</bindBeforeGroupSearch>
  <rolePrefix>ROLE_</rolePrefix>
  <convertToUpperCase>true</convertToUpperCase>
  <user>admin</user>
  <password>geoserver</password>
  <passwordEncoderName>digestPasswordEncoder</passwordEncoderName>
  <passwordPolicyName>default</passwordPolicyName>
</org.geoserver.security.ldap.LDAPUserGroupServiceConfig>

JSON (LDAPUserGroupService)

The equivalent JSON payload:

{
  "org.geoserver.security.ldap.LDAPUserGroupServiceConfig": {
    "name": "ldapUsers",
    "className": "org.geoserver.security.ldap.LDAPUserGroupService",
    "serverURL": "ldap://localhost:10389/dc=acme,dc=org",
    "groupSearchBase": "ou=groups",
    "allGroupsSearchFilter": "cn=*",
    "groupSearchFilter": "member=uid={0},ou=people,dc=acme,dc=org",
    "userSearchBase": "ou=people",
    "allUsersSearchFilter": "uid=*",
    "useTLS": true,
    "useNestedParentGroups": true,
    "maxGroupSearchLevel": 10,
    "nestedGroupSearchFilter": "(member={0})",
    "bindBeforeGroupSearch": true,
    "rolePrefix": "ROLE_",
    "convertToUpperCase": true,
    "user": "admin",
    "password": "geoserver",
    "passwordEncoderName": "digestPasswordEncoder",
    "passwordPolicyName": "default"
  }
}

Operations

List

GET /rest/security/usergroupservices

Response

  • 200 OK with a document containing the configured services.

cURL:

curl -u admin:geoserver -H "Accept: application/xml" \
  "http://localhost:8080/geoserver/rest/security/usergroupservices"

Retrieve

GET /rest/security/usergroupservices/{name}

Response

  • 200 OK with the service configuration.

  • 404 Not Found if the service does not exist.

cURL:

curl -u admin:geoserver -H "Accept: application/json" \
  "http://localhost:8080/geoserver/rest/security/usergroupservices/users1"

Create

POST /rest/security/usergroupservices

  • Request body: one of the configuration payloads shown above.

  • Content-Type: application/xml or application/json

Response

  • 201 Created (some versions may return 200 OK) and a Location header.

  • 400 Bad Request on validation errors (e.g. missing fileName for XML service).

  • 400 Bad Request if a service with the same name already exists.

cURL:

curl -u admin:geoserver -H "Content-Type: application/xml" -H "Accept: application/xml" \
  -d @xml-usergroup-service.xml \
  "http://localhost:8080/geoserver/rest/security/usergroupservices"

Update / Replace

PUT /rest/security/usergroupservices/{name}

  • Replaces (or creates) the service named {name} with the provided configuration.

  • The name inside the payload must match the path parameter.

Response

  • 200 OK on successful update, or 201 Created if newly created.

  • 400 Bad Request if the payload name does not match the path parameter.

  • 400 Bad Request on validation errors.

cURL:

curl -u admin:geoserver -X PUT -H "Content-Type: application/json" -H "Accept: application/json" \
  -d @xml-usergroup-service.json \
  "http://localhost:8080/geoserver/rest/security/usergroupservices/users1"

Delete

DELETE /rest/security/usergroupservices/{name}

Response

  • 200 OK on successful deletion.

  • 404 Not Found if the service does not exist (some deployments may return 410 Gone).

  • 400 Bad Request if attempting to delete a required service (e.g., the default one).

cURL:

curl -u admin:geoserver -X DELETE \
  "http://localhost:8080/geoserver/rest/security/usergroupservices/users1"

Content Negotiation

All operations accept/produce both XML and JSON. Either:

  • Set headers: Accept: application/xml and/or Content-Type: application/xml (or JSON), or

  • Use .xml / .json suffixes (if enabled in your deployment).

Notes & Tips

  • When creating an XMLUserGroupService, the file referenced by fileName will be created under GeoServer’s security directory if it does not already exist.

  • For LDAP services, make sure the serverURL and search parameters match your directory layout. The groupSearchFilter and nestedGroupSearchFilter usually need adjustment.

  • Passwords supplied in configuration payloads may be stored according to the chosen passwordEncoderName and policy.

Previous: Auth Providers (Endpoint Reference)
Next: Security