Nascent Political Miscreant


    1.1.0 • Public • Published


    Build Status

    A simple Angular.js CouchDB auth interface. Works great directly with a CouchDB instance, works even better with a CouchDB proxy/wrapper API.


    Install with npm:

    npm install --save angular-eha.couchdb-auth

    Or alternatively bower:

    bower install --save angular-eha.couchdb-auth


    If you're using wiredep, then all you need to do is add eha.couchdb-auth as an angular module dependency somewhere sensible in your app. In the absense of wiredep, you'll need to manually bundle dist/couchdb-auth.js.


    The module can be configured through the ehaCouchDbAuthServiceProvider via a config block:

    app.config(function(ehaCouchDbAuthServiceProvider) {
        url: '',            // CouchDB/Proxy URL exposing _session endpoints
        localStorageNamespace: 'mnutrition',    // Namespace for localstorage (default: lf)
        adminRoles: ['admin'],                  // 'Admin' CouchDB role. (default: `['_admin']`)
        userRoles: ['data_provider', 'analyst'],// Roles other than admin roles
        sessionEndpoint: '_session',            // Configurable session endpoint (default: `'_session'`)
        interceptor: {                          // Enable HTTP Interceptor (default: false)
          hosts: [                              // Configure hostnames that should be intercepted
        defaultHttpFields: {                    // Passed through to Angular's $http config (default: unset)
          withCredentials: true                 // See:$http#usage

    Note: userRoles can be camelcase, or hyphenized strings (with '_' or '-' but not with both).

    Configuring an interceptor will internally add an $http interceptor, which will automatically add the bearer token to outcoming requests, and handle authentication errors (code 401) in the responses. You can react to intercepted errors using the .on method, see below. The interceptor will act on communications with locations matching one of the values in hosts.



    Promise/A+ Attempt to create a new CouchDB session with given credentials.

    • username - CouchDB user name
    • password - CouchDB user password


    Promise/A+ Attempt to destroy a CouchDB sessions and reset local authenitcation status.


    Promise/A+ Password reset features. Typical pattern; request reset token by email, follow link, change password.

    n.b. CouchDB does not provide this functionality. To leverage this functionality you require a compatible 'backend'

    • email - Email address of account for which you wish to reset the password
    • callbackUrl - The URL that the resetToken should be appended to in order to complete the flow
    • token - A valid resetToken
    • password - The new password
    Reset token flow

    Calling resetPassword() with email and callbackUrl parameters will initiate the password reset token request flow.

    Change password flow

    Calling resetPassword() with a valid token and a new password will initiate the change password flow.


    Promise/A+ Makes a GET request to the _session/ endpoint of the CouchDB url provided during configuration. Returns a promise.


    Promise/A+ Checks the local environment for a user, failing that checks local storage and finally attempts to GET the _session/ endpoint of the CouchDB url.

    Returns a promise

    on(EVENT, handler)

    Event subscription handler

    • EVENT string the name of the event you wish to handle
    • handler function the event handler
    Supported events:
    • unauthenticated - fired whenever an unauthenticated user / session attempts to access a resource that requires authentication.
    • unauthorized - fired whenever the current user / session is unauthorised to access a resource


    The provider exposes some functions suitable to be used as values for the resolve option of the when method of the $routeProvider, or as values for analogous options passed to the Angular UI router. Check Angular's documentation for more information. Note that requireAdminUser, requireAuthenticatedUser and requireUserWithRoles are designed to work this way, and need to have their arguments injected by $routeProvider, so use them for example like this:

    var auth = ehaCouchDbAuthServiceProvider.requireAuthenticatedUser;
      .when('/page', {
        templateUrl: 'views/page.html',
        controller: 'PageCtrl',
        resolve: auth


    Promise/A+ Check if the user is an admin (has one of the adminRoles provided in the config).


    E.g. the function for the data_provider role will be requireDataProviderUser.

    Promise/A+ Check if the user has a particular role.

    Note: These functions are created dynamically during the configuration of the module. These can cause problems when using the function within angular-ui-router if the routes are loaded before configuring the module. This can be avoided by providing the configuration for the roles when initializing the routes:

      .config(function($stateProvider, ehaCouchDbAuthServiceProvider) {
          userRoles: [
        .state('upload', {
          url: '/upload',
          resolve: {
            isDataProvider: ehaCouchDbAuthServiceProvider.requireDataProviderUser
          views: {


    Promise/A+ Check if the user is has a role in the given set.

    Similar to requireUser but supports checking against multiple roles, for example:

    // Within a $stateProvider.state declaration
    resolve: {
      authorization: ehaCouchDbAuthServiceProvider.requireUserWithRoles([


    Promise/A+ Check if the user is authenticated.

    eha-show-authenticated directive

    A simple directive to hide dom elements and show only for authenticated sessions.


      <div eha-show-authenticated>Only show me for authenticated sessions</div>

    eha-show-for-role directive

    A simple directive to hide/show dom elements for users depending on their access control (role) level. Accepts either a single string or an array of strings.


      <!-- single string. must be an expression. n.b. `'`s are required -->
      <div eha-show-for-role="'admin'"></div>
      <!-- an array of strings -->
      <div eha-show-for-role="['role1', 'role2']"></div>


    Copyright 2015 Matt Richards

    Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


    npm i angular-eha.couchdb-auth

    DownloadsWeekly Downloads






    Last publish