.. 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/auth: ============== Authentication ============== Interfaces for obtaining session and authorization data. .. note:: We also strongly recommend you :ref:`set up SSL ` to improve all authentication methods' security. .. _api/auth/basic: Basic Authentication ==================== `Basic authentication`_ (:rfc:`2617`) is a quick and simple way to authenticate with CouchDB. The main drawback is the need to send user credentials with each request which may be insecure and could hurt operation performance (since CouchDB must compute the password hash with every request): **Request**: .. code-block:: http GET / HTTP/1.1 Accept: application/json Authorization: Basic cm9vdDpyZWxheA== Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 177 Content-Type: application/json Date: Mon, 03 Dec 2012 00:44:47 GMT Server: CouchDB (Erlang/OTP) { "couchdb":"Welcome", "uuid":"0a959b9b8227188afc2ac26ccdf345a6", "version":"1.3.0", "vendor": { "version":"1.3.0", "name":"The Apache Software Foundation" } } .. _Basic authentication: http://en.wikipedia.org/wiki/Basic_access_authentication .. _api/auth/cookie: Cookie Authentication ===================== For cookie authentication (:rfc:`2109`) CouchDB generates a token that the client can use for the next few requests to CouchDB. Tokens are valid until a timeout. When CouchDB sees a valid token in a subsequent request, it will authenticate the user by this token without requesting the password again. By default, cookies are valid for 10 minutes, but it's :config:option:`adjustable `. Also it's possible to make cookies :config:option:`persistent `. To obtain the first token and thus authenticate a user for the first time, the `username` and `password` must be sent to the :ref:`_session API `. .. _api/auth/session: ``/_session`` ------------- .. http:post:: /_session :synopsis: Authenticates user by Cookie-based user login Initiates new session for specified user credentials by providing `Cookie` value. :
header Set-Cookie: Authorization token :>json boolean ok: Operation status :>json string name: Username :>json array roles: List of user roles :code 200: Successfully authenticated :code 302: Redirect after successful authentication :code 401: Username or password wasn't recognized **Request**: .. code-block:: http POST /_session HTTP/1.1 Accept: application/json Content-Length: 24 Content-Type: application/x-www-form-urlencoded Host: localhost:5984 name=root&password=relax It's also possible to send data as JSON: .. code-block:: http POST /_session HTTP/1.1 Accept: application/json Content-Length: 37 Content-Type: application/json Host: localhost:5984 { "name": "root", "password": "relax" } **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 43 Content-Type: application/json Date: Mon, 03 Dec 2012 01:23:14 GMT Server: CouchDB (Erlang/OTP) Set-Cookie: AuthSession=cm9vdDo1MEJCRkYwMjq0LO0ylOIwShrgt8y-UkhI-c6BGw; Version=1; Path=/; HttpOnly {"ok":true,"name":"root","roles":["_admin"]} If ``next`` query parameter was provided the response will trigger redirection to the specified location in case of successful authentication: **Request**: .. code-block:: http POST /_session?next=/blog/_design/sofa/_rewrite/recent-posts HTTP/1.1 Accept: application/json Content-Type: application/x-www-form-urlencoded Host: localhost:5984 name=root&password=relax **Response**: .. code-block:: http HTTP/1.1 302 Moved Temporarily Cache-Control: must-revalidate Content-Length: 43 Content-Type: application/json Date: Mon, 03 Dec 2012 01:32:46 GMT Location: http://localhost:5984/blog/_design/sofa/_rewrite/recent-posts Server: CouchDB (Erlang/OTP) Set-Cookie: AuthSession=cm9vdDo1MEJDMDEzRTp7Vu5GKCkTxTVxwXbpXsBARQWnhQ; Version=1; Path=/; HttpOnly {"ok":true,"name":null,"roles":["_admin"]} .. http:get:: /_session :synopsis: Returns Cookie-based login user information Returns information about the authenticated user, including a :ref:`userctx_object`, the authentication method and database that were used, and a list of configured authentication handlers on the server. :query boolean basic: Accept `Basic Auth` by requesting this resource. *Optional*. :>json boolean ok: Operation status :>json object userCtx: User context for the current user :>json object info: Server authentication configuration :code 200: Successfully authenticated. :code 401: Username or password wasn't recognized. **Request**: .. code-block:: http GET /_session HTTP/1.1 Host: localhost:5984 Accept: application/json Cookie: AuthSession=cm9vdDo1MEJDMDQxRDpqb-Ta9QfP9hpdPjHLxNTKg_Hf9w **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 175 Content-Type: application/json Date: Fri, 09 Aug 2013 20:27:45 GMT Server: CouchDB (Erlang/OTP) Set-Cookie: AuthSession=cm9vdDo1MjA1NTBDMTqmX2qKt1KDR--GUC80DQ6-Ew_XIw; Version=1; Path=/; HttpOnly { "info": { "authenticated": "cookie", "authentication_db": "_users", "authentication_handlers": [ "cookie", "default" ] }, "ok": true, "userCtx": { "name": "root", "roles": [ "_admin" ] } } .. http:delete:: /_session :synopsis: Logout Cookie-based user Closes user's session by instructing the browser to clear the cookie. This does not invalidate the session from the server's perspective, as there is no way to do this because CouchDB cookies are stateless. This means calling this endpoint is purely optional from a client perspective, and it does not protect against theft of a session cookie. :code 200: Successfully close session. **Request**: .. code-block:: http DELETE /_session HTTP/1.1 Accept: application/json Cookie: AuthSession=cm9vdDo1MjA1NEVGMDo1QXNQkqC_0Qmgrk8Fw61_AzDeXw Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 12 Content-Type: application/json Date: Fri, 09 Aug 2013 20:30:12 GMT Server: CouchDB (Erlang/OTP) Set-Cookie: AuthSession=; Version=1; Path=/; HttpOnly { "ok": true } .. _api/auth/proxy: Proxy Authentication ==================== .. note:: To use this authentication method make sure that the ``{couch_httpd_auth, proxy_authentication_handler}`` value in added to the list of the active :config:option:`chttpd/authentication_handlers`: .. code-block:: ini [chttpd] authentication_handlers = {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, proxy_authentication_handler}, {couch_httpd_auth, default_authentication_handler} `Proxy authentication` is very useful in case your application already uses some external authentication service and you don't want to duplicate users and their roles in CouchDB. This authentication method allows creation of a :ref:`userctx_object` for remotely authenticated user. By default, the client just needs to pass specific headers to CouchDB with related requests: - :config:option:`X-Auth-CouchDB-UserName `: username; - :config:option:`X-Auth-CouchDB-Roles `: comma-separated (``,``) list of user roles; - :config:option:`X-Auth-CouchDB-Token `: authentication token. When :config:option:`proxy_use_secret ` is set (which is strongly recommended!), this header provides the secret token to prevent requests from untrusted sources. **Request**: .. code-block:: http GET /_session HTTP/1.1 Host: localhost:5984 Accept: application/json Content-Type: application/json; charset=utf-8 X-Auth-CouchDB-Roles: users,blogger X-Auth-CouchDB-UserName: foo **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 190 Content-Type: application/json Date: Fri, 14 Jun 2013 10:16:03 GMT Server: CouchDB (Erlang/OTP) { "info": { "authenticated": "proxy", "authentication_db": "_users", "authentication_handlers": [ "cookie", "proxy", "default" ] }, "ok": true, "userCtx": { "name": "foo", "roles": [ "users", "blogger" ] } } Note that you don't need to request :ref:`session ` to be authenticated by this method if all required HTTP headers are provided.