Dear Wiki user, You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.
The "Session_API" page has been changed by JoanTouzet: https://wiki.apache.org/couchdb/Session_API?action=diff&rev1=13&rev2=14 <<Include(EditTheWiki)>> - The Session API manages sessions for CouchDB access. + See our [[http://docs.couchdb.org/en/stable/api/server/authn.html|official documentation]] on the session API. - 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: - * 200 OK (with Cookie) - * 302 Redirection (with Cookie) -- if "next" parameter was provided - * 401 Unauthorized - - === 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: - * 200 OK (cookie removed) - * 302 Redirection (cookie removed) -- if "next" parameter was provided - - === 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: - * 200 OK - * 401 Unauthorized -- if invalid basic auth credentials are provided, or the "basic" parameter was provided with a true value and a non logged in user. - - 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 [[http://tools.ietf.org/html/rfc2617|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). -
