| .. Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| .. use this file except in compliance with the License. You may obtain a copy of |
| .. the License at |
| .. |
| .. http://www.apache.org/licenses/LICENSE-2.0 |
| .. |
| .. Unless required by applicable law or agreed to in writing, software |
| .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| .. License for the specific language governing permissions and limitations under |
| .. the License. |
| |
| .. _api/db/security: |
| |
| ================= |
| ``/db/_security`` |
| ================= |
| |
| .. http:get:: /{db}/_security |
| :synopsis: Returns the special security object for the database |
| |
| Returns the current security object from the specified database. |
| |
| The security object consists of two compulsory elements, ``admins`` |
| and ``members``, which are used to specify the list of users and/or roles |
| that have admin and members rights to the database respectively: |
| |
| - ``members``: they can read all types of documents from the DB, and they |
| can write (and edit) documents to the DB except for design documents. |
| |
| - ``admins``: they have all the privileges of ``members`` plus the |
| privileges: write (and edit) design documents, add/remove database admins |
| and members and set the :ref:`database revisions limit |
| <api/db/revs_limit>`. They can not create a database nor delete a |
| database. |
| |
| Both ``members`` and ``admins`` objects contain two array-typed fields: |
| |
| - ``names``: List of CouchDB user names |
| - ``roles``: List of users roles |
| |
| Any additional fields in the security object are optional. |
| The entire security object is made available to validation and other |
| internal functions so that the database can control and limit |
| functionality. |
| |
| If both the names and roles fields of either the admins or members |
| properties are empty arrays, or are not existent, it means the database |
| has no admins or members. |
| |
| Having no admins, only server admins (with the reserved ``_admin`` role) |
| are able to update design documents and make other admin level changes. |
| |
| Having no members or roles, any user can write regular documents (any |
| non-design document) and read documents from the database. |
| |
| Since CouchDB 3.x newly created databases have by default the _admin role |
| to prevent unintentional access. |
| |
| If there are any member names or roles defined for a database, then only |
| authenticated users having a matching name or role are allowed to read |
| documents from the database (or do a :get:`/{db}` call). |
| |
| .. note:: |
| If the security object for a database has never been set, then the |
| value returned will be empty. |
| |
| Also note, that security objects are not regular versioned documents |
| (that is, they are not under MVCC rules). This is a design choice to |
| speed up authorization checks (avoids traversing a database's documents |
| B-Tree). |
| |
| :param db: Database name |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>json object admins: Object with two fields as ``names`` and ``roles``. |
| See description above for more info. |
| :>json object members: Object with two fields as ``names`` and ``roles``. |
| See description above for more info. |
| :code 200: Request completed successfully |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /db/_security HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Cache-Control: must-revalidate |
| Content-Length: 109 |
| Content-Type: application/json |
| Date: Mon, 12 Aug 2013 19:05:29 GMT |
| Server: CouchDB (Erlang/OTP) |
| |
| { |
| "admins": { |
| "names": [ |
| "superuser" |
| ], |
| "roles": [ |
| "admins" |
| ] |
| }, |
| "members": { |
| "names": [ |
| "user1", |
| "user2" |
| ], |
| "roles": [ |
| "developers" |
| ] |
| } |
| } |
| |
| .. http:put:: /{db}/_security |
| :synopsis: Sets the special security object for the database |
| |
| Sets the security object for the given database. |
| |
| :param db: Database name |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :<header Content-Type: :mimetype:`application/json` |
| :<json object admins: Object with two fields as ``names`` and ``roles``. |
| :ref:`See description above for more info <api/db/security>`. |
| :<json object members: Object with two fields as ``names`` and ``roles``. |
| :ref:`See description above for more info <api/db/security>`. |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>json boolean ok: Operation status |
| :code 200: Request completed successfully |
| :code 401: CouchDB Server Administrator privileges required |
| |
| **Request**: |
| |
| .. code-block:: bash |
| |
| shell> curl http://localhost:5984/pineapple/_security -X PUT -H 'content-type: application/json' -H 'accept: application/json' -d '{"admins":{"names":["superuser"],"roles":["admins"]},"members":{"names": ["user1","user2"],"roles": ["developers"]}}' |
| |
| .. code-block:: http |
| |
| PUT /db/_security HTTP/1.1 |
| Accept: application/json |
| Content-Length: 121 |
| Content-Type: application/json |
| Host: localhost:5984 |
| |
| { |
| "admins": { |
| "names": [ |
| "superuser" |
| ], |
| "roles": [ |
| "admins" |
| ] |
| }, |
| "members": { |
| "names": [ |
| "user1", |
| "user2" |
| ], |
| "roles": [ |
| "developers" |
| ] |
| } |
| } |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Cache-Control: must-revalidate |
| Content-Length: 12 |
| Content-Type: application/json |
| Date: Tue, 13 Aug 2013 11:26:28 GMT |
| Server: CouchDB (Erlang/OTP) |
| |
| { |
| "ok": true |
| } |