Configuring saslauthd

reference

The Couchbase REST API supports enablement of saslauthd and the establishment of saslauthd administrators for the cluster.

HTTP Methods and URIs

POST /settings/saslauthdAuth

GET /settings/saslauthdAuth

Description

The POST method enables saslauthd for the cluster, and establishes administrators and/or read-only administrators for saslauthd.

The GET method returns the current saslauthd settings for the cluster.

Note that appropriate installation and configuration must already have occurred, for the POST and GET methods to succeed (see Configure saslauthd).

The Full Admin, Cluster Admin, or External Security Admin role is required for each method.

Curl Syntax

 curl -X POST -u <administrator>:<password>
    http://<ip-address-or-hostname>:8091/settings/saslauthdAuth
    -d enabled=< true | false >
    -d admins=[<admin-name>]
    -d roAdmins=[<admin-name>]

curl -X GET -u <administrator>:<password>
   http://<ip-address-or-hostname>:8091/settings/saslauthdAuth

The enabled parameter is a required parameter, whose value determines whether saslauthd is enabled or disabled on the cluster: if the value is true, saslauthd is enabled. By default, saslauthd is disabled.

The values of the optional admins and roAdmins parameters can in each case be a comma-separated list of saslauthd users (each user having already been established by means of the operating system), who are to be given privileges corresponding to the parameter, across the entire cluster. If an empty list is specified, no saslauthd users will have the privileges corresponding to the parameter.

Note that use of the POST method is not incremental: each specified list explicitly defines the new list of users and privileges that will exist from the point of execution — users who have previously had privileges, but are omitted from the list, lose their privileges.

Responses

Successful use of POST returns 200 OK, and a JSON object containing three key-value pairs, which respectively indicate the current enablement-status, the current list of administrators, and the current list of read-only administrators.

Successful use of GET returns 200 OK, and a JSON object identical to that returned by the most recent POST.

A malformed URI returns 404 Object Not Found.

Failure to authenticate returns 401 Unauthorized. Successful authentication with an inappropriate role returns 403 Forbidden, and an object such as the following: {"message":"Forbidden. User needs the following permissions","permissions":["cluster.admin.security.external!write"]}.

Examples

The following examples show how saslauthd can be configured with the REST API.

Enable saslauthd and Establish Administrators

The following example assigns saslauthd roles to three users, who have already been established as members of the sasl group:

curl -X POST http://localhost:8091/settings/saslauthdAuth -u Administrator:password -d admins=[couchbase] -d roAdmins=[abc,def] -d enabled=true

If the call is successful, an object such as the following is returned.

{"enabled":true,"admins":["[couchbase]"],"roAdmins":["[abc,def]"]}

Retrieve Current saslauthd Settings

The following example retrieves the current saslauthd settings for the cluster:

curl -X GET http://localhost:8091/settings/saslauthdAuth -u Administrator:password

If the call is successful, an object such as the following is returned:

{"enabled":true,"admins":["[tjh]"],"roAdmins":["[abc,def]"]}

Delete Administrators and Disable saslauthd

The following example deletes all previously created administrators and disables saslauthd.

curl -X POST http://localhost:8091/settings/saslauthdAuth -u Administrator:password -d admins=[] -d roAdmins=[] -d enabled=false