Configuring saslauthd
- reference
The Couchbase REST API supports enablement of saslauthd and the establishment of saslauthd administrators for the cluster.
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
If the call is successful, an object such as the following is returned:
{"enabled":false,"admins":[],"roAdmins":[]}
See Also
Information on configuring saslauthd is provided in see Configure saslauthd. Information on Couchbase-Server authentication domains is provided in Authentication Domains.