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 RussellBranca: http://wiki.apache.org/couchdb/Session_API?action=diff&rev1=9&rev2=10 Comment: Updated _session info to document the hidden basic=true param and describe how to utilize it in Basic Auth protected CouchApps 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.) an exception will be thrown with an "unauthorized" error. + 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 ===
