Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Mozilla BrowserID support plugin for CouchDB
branch: master

This branch is 37 commits behind iriscouch:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
etc/couchdb/default.d
priv
src
ui
.gitignore
LICENSE
README.md
rebar

README.md

BrowserID for CouchDB

This is a plugin for CouchDB to support Mozilla's BrowserID standard.

So Simple

Put this in your Couch app.

<!DOCTYPE html>
<html>
  <head>
    <script src="/_browserid/include.js" type="text/javascript"></script>

    <!-- Optional styles -->
    <link rel="stylesheet" type="text/css" href="/_browserid/style.css">
  </head>

  <body>
    <div id="browserid">
      <div class="login">
        <img src="/_browserid/sign_in_blue.png">
      </div>
      <div class="picture"></div>
    </div>

    Hello, BrowserID world!
  </body>

  <!-- Recommended convenience API -->
  <script src="/_utils/script/jquery.js" type="text/javascript"></script>
  <script src="/_browserid/main.js" type="text/javascript"></script>
</html>

You're done!

That is a complete, working CouchDB login page. All you need is a #browserid div a .login div inside.

CouchDB supports automatic new account creation and a traditional session cookie. User accounts haven't changed. They are still documents in the _users database. You can set roles and replicate them as before. The only changes are

  • Users log in through BrowserID instead of passwords
  • The first time a user logs in, CouchDB will create an account for them.

Logging in and out programatically

If you use the convenience API, /_browserid/main.js, you can start the login or logout process from Javascript:

// Start the login process, which pops up the BrowserID window.
$.couch.browserid.login();

// Start the logout process, which ends the user's session.
$.couch.browserid.logout();

Upon login, the .login div will contain a welcome message for the user. Use jQuery and CSS to modify or style it as needed. It will look like this:

<div class="login">
  <span class="greeting">Hi </span>
  <span class="username">me@example.com</span>
  <span class="farewell">.</span>
  <a class="logout" href="/">(logout)</a>
</div>

Additionally, the .picture div will contain a Gravatar image for the user's email address.

Login and logout events

To be notified when the login or logout phase completes, use the same functions with a callback.

// This will run when login is done.
$.couch.browserid.login(function(event, error, user) {
  if(error)
    return console.log("Something went wrong with login: " + error);

  console.log("Congratulations " + user.email + ", you now have an account on my couch");
});

// This will run when logout is done.
$.couch.browserid.logout(function(event, error) {
  if(error)
    return console.log("Something went wrong with logout: " + error);

  console.log("Sorry to see you go!");
})

Advanced usage

If you are a BrowserID whiz and prefer to do your own thing, then include only the /_browserid/include.js file and no others. To verify your membership assertion, POST an application/json body to /_browserid, such as this:

{ "assertion": "<the assertion string goes here>"
, "audience" : "example.com:80"
}

The response will be the same as https://browserid.org/verify. That URL is currently used for verification. You can use a different one by changing /_config/httpd/browserid_verify_url.

Building

Use Build CouchDB: https://github.com/iriscouch/build-couchdb

rake plugin="git://github.com/iriscouch/browserid_couchdb origin/master"

Installation

Build CouchDB already took care of this step!

Development

This is what I do. It's not perfect but barely harder than building a fork of CouchDB, and it allows 1.0.x, 1.1.x, as well as trunk support.

This example assumes three Git checkouts, side-by-side:

  • couchdb - Perhaps a trunk checkout, but could be any tag or branch
  • build-couchdb - For the boring Couch dependencies
  • browserid_couchdb - This code

Build dependencies plus couch

Feel free to skip this if you are Randall Leeds. (Hi, Randall!)

cd couchdb
rake -f ../build-couchdb/Rakefile couchdb:configure
# Go get coffee. This builds the deps, then runs the boostrap and configure scripts
make dev

Next, teach rebar where to find CouchDB, and teach Erlang and Couch where to find this plugin.

cd ../browserid_couchdb
export ERL_COMPILER_OPTIONS='[{i, "../couchdb/src/couchdb"}]'
export ERL_ZFLAGS="-pz $PWD/ebin"
ln -s "../../../../browserid_couchdb/etc/couchdb/default.d/browserid.ini" ../couchdb/etc/couchdb/default.d

You're ready. Run this every time you change the code:

./rebar compile && ../couchdb/utils/run -i
Something went wrong with that request. Please try again.