The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

The Session API manages sessions for CouchDB access.

Session information is stored on the client using a Cookie (named AuthSession).

Log in

To acquire a session cookie, do a

  POST /_session

with "name" and "password" fields. These can be sent either as JSON or the standard form data encoding; just be sure to set the Content-Type appropriately. (The latter format allows you to log in directly from a simple HTML form.)

You can see your logged-in user name and roles with

  GET /_session

}

if you pass either your session cookie or authenticate with basic auth;

   Authorization: Basic <base64-encoded-username:password>

The username is the "name" field of a user's record in CouchDB's _users database.

There is an optional "next" parameter that can be used to force a redirection after CouchDB processed a successful login.

In case of success, the POST /_session command will return a JSON value:

  {
    "ok": true,
    "userCtx": {
      "name": "username",
      "roles": ["role1","role2"]
    },
    "info": {
      "authentication_db":"_users",
      "authentication_handlers":["oauth","cookie","default"],
      "authenticated":"default"
    }
  }

Note how the userCtx field is similar to the user context (userCtx) parameter of some of the Javascript functions.

In case of error, the POST /_session command will return a JSON value:

  {
    "error":"Name or password is incorrect."
  }

Possible return values:

Log out

To delete the session, do a

  DELETE /_session

which will remove the session cookie.

An optional parameter "next" can be provided to redirect the browser.

Possible return values:

Session information

To retrieve the current session's information, do a

  GET /_session

which will retrieve the session data (based on the session cookie).

If the session is valid the GET method will return the same structure as provided by the successful POST that started the session.

If the session is not valid (not logged in, etc.) a default response will be returned with a null name and an empty roles list (when in Admin Party mode, the "_admin" roll will be returned):

  {
    "ok": true,
    "userCtx": {
      "name": null,
      "roles": []
    },
    "info": {
      "authentication_db":"_users",
      "authentication_handlers":["oauth","cookie","default"]
    }
  }

Possible return values:

Note: it seems Futon does not use POST but simply submits a GET /_session with the proper Authorization header.

Forcing Basic Authorization

Rather than return a default value, Basic Authorization may be forced by supplying the basic query parameter:

  GET /_session?basic=true

This will ensure that requests to _session return either a valid user context or a 401 Unauthorized error.

CouchApps and /_session with Basic Authorization

When using Basic Authorization to access a protected CouchApp, requests to /_session will not be included in the Basic Authorization protection space by default, and because /_session returns 200 ok by default rather than a 401 Unauthorized, no Basic realm will be defined for the request as the WWW-Authenticate header is not provided.

To fix this issue, pass the basic=true query parameter to /_session as mentioned above. This will ensure that either a valid user context is returned, or a 401 Unauthorized request is returned, which will supply the WWW-Authenticate header and define the appropriate Basic realm. This allows the browser to automatically provide the current Basic Authorization value in the Authorization header on the request to /_session, which then returns the user session info as expected.

For further information on Basic Authorization realms and protection spaces, see RFC 2617.

Session Timeout

The session timeout is specified by the "timeout" parameter in the "couch_httpd_auth" section of the configuration. If not specified it defaults to 600 seconds (10 minutes).

Session_API (last edited 2013-01-08 02:24:15 by RobertNewson)