# 10.2.15. Authentication

Interfaces for obtaining session and authorization data.

Note

We also strongly recommend you set up SSL to improve all authentication methods’ security.

## 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:

    GET / HTTP/1.1
    Accept: application/json
    Authorization: Basic cm9vdDpyZWxheA==
    Host: localhost:5984

Response:

    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"
        }
    }

## 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 `adjustable`. Also it’s possible to make cookies `persistent`.

To obtain the first token and thus authenticate a user for the first time, the username and password must be sent to the _session API.

### `/_session`

`POST` `/_session`

  Initiates new session for specified user credentials by providing Cookie value.

  Request Headers:
  | Content-Type – application/x-www-form-urlencoded application/json
  Query Parameters:
  | next (string) – Enforces redirect after successful login to the specified location. This location is relative from server root. Optional.
  Form Parameters:
  | name – User name password – Password
  Response Headers:
  | Set-Cookie – Authorization token
  Response JSON Object:
  | ok (boolean) – Operation status name (string) – Username roles (array) – List of user roles
  Status Codes: | 200 OK – Successfully authenticated 302 Found – Redirect after successful authentication 401 Unauthorized – Username or password wasn’t recognized

  Request:

      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:

      POST /_session HTTP/1.1
      Accept: application/json
      Content-Length: 37
      Content-Type: application/json
      Host: localhost:5984

      {
          "name": "root",
          "password": "relax"
      }

  Response:

      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:

      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:

      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"]}

`GET` `/_session`

  Returns complete information about authenticated user. This information contains User Context Object, authentication method and available ones and authentication database.

  Query Parameters:
  | basic (boolean) – Accept Basic Auth by requesting this resource. Optional.
  Status Codes: | 200 OK – Successfully authenticated. 401 Unauthorized – Username or password wasn’t recognized.

  Request:

      GET /_session HTTP/1.1
      Host: localhost:5984
      Accept: application/json
      Cookie: AuthSession=cm9vdDo1MEJDMDQxRDpqb-Ta9QfP9hpdPjHLxNTKg_Hf9w

  Response:

      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"
              ]
          }
      }

`DELETE` `/_session`

  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.

  Status Codes: | 200 OK – Successfully close session.

  Request:

      DELETE /_session HTTP/1.1
      Accept: application/json
      Cookie: AuthSession=cm9vdDo1MjA1NEVGMDo1QXNQkqC_0Qmgrk8Fw61_AzDeXw
      Host: localhost:5984

  Response:

      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
      }

## 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 `httpd/authentication_handlers`:

    [httpd]
    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 User Context Object for remotely authenticated user. By default, the client just needs to pass specific headers to CouchDB with related requests:

- `X-Auth-CouchDB-UserName`: username;
- `X-Auth-CouchDB-Roles`: comma-separated (`,`) list of user roles;
- `X-Auth-CouchDB-Token`: authentication token. When `proxy_use_secret` is set (which is strongly recommended!), this header provides the secret token to prevent requests from untrusted sources.

Request:

    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:

    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 session to be authenticated by this method if all required HTTP headers are provided.