Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    www-authenticatepublic

    www-authenticate Build Status

    Documentation

    Provides the functionality needed for a client to use HTTP Basic or Digest authentication. Also provides primitives for parsing WWW-Authenticate and Authentication_Info headers.

    Parses the content of a WWW-Authenticate header sent by a server. Interpret the authentication challenge posed. Then generate the credentials for Authorization headers for subsequent requests from the server.

    • Supports Basic and Digest authentication schemes.
    • Supports 'auth' quality of protection (qop) and challenges that do not include qop.
    • Supports MD5 and MD5-sess algorithms.
    • Assumes Node.js, but otherwise makes no assumtion about framework.

    Limitations

    • Included tests only test Digest scheme against the rfc2617 example.
    • Most of the permutations of qop and algorithm have not been tested.
    • Little real-world testing. That's where you can help! Report any failures or submit a patch that resolves an authentication failure.
    • Will not parse WWW-Authenticate headers that contain more than one challenge. Please send an example of one if you find one in the field or modify the parser to parse it.
    • Does not support auth-int qop, but will use auth qop if server allows either. Support could surely be added in the future.
    • Response to challenges without qop have not been tested.

    Getting Started

    Install the module with: npm install www-authenticate See examples below.

    Examples

    Use the high level interface:

    var www_authenticate = require('www-authenticate');
    var authenticator= www_authenticate.authenticator(username,password);
     
    // Whenever you receive a response, send it to the authenticator. 
    // The authenticator will parse and record any challenge it contains. 
    authenticator.get_challenge(response);
     
    //... now, whenever you make a request the authenticator will add an 
    // authorization header if a challenge has been received... 
     var options= {
       method: "GET",
       path: "/dir/index.html"
     }
     authenticator.authenticate_request_options(options);
     if (authenticator.err) throw err;  // or do something similarly drastic 
     http.request(options);

    Use the low level interface:

    var www_authenticate = require('www-authenticate');
    var on_www_authenticate= www_authenticate(username,password);
     
    // now wait for HTTP/1.1 401 Unauthorized and then parse the WWW_Authenticate header 
    var authenticator= on_www_authenticate(response.headers['www-authenticate']);
    if (authenticator.err) throw err; // or do something similarly drastic 
     
    //... now, whenever you make a request, add an Authorization header: 
    response.setHeader('authorization', authenticator.authorize('GET',url));

    Parse www-authenticate or authentication-info headers:

    var parsers = require('www-authenticate').parsers;
    var parsed= new parsers.WWW_Authenticate(request.headers['www-authenticate']);
    console.log(parsed.scheme);
    console.log(parsed.parms.nonce);
     
    var parsed= new parsers.Authentication_Info(request.headers['authentication-info']);
    console.log(parsed.parms.nonce);

    User credentials:

    This module exports a user_credentials function. When called, it returns a user_credentials object that uses the username and password to generate components of an Authentication header without exposing the password. A user_credentials object may be used in place of the username and password arguments.

    Without user credentials:

    var www_authenticate = require('www-authenticate');
    var authenticator= www_authenticate.authenticator(username,password);

    With user credentials:

    var www_authenticate = require('www-authenticate');
    var my_credentials= www_authenticate.user_credentials("Me","My Password");
    var authenticator= www_authenticate.authenticator(my_credentials);

    In the above example, my_credentials might actually be generated in a separate module and passed around instead of the plain text username and password, making accidental pasword disclosure less likely.

    Options:

    In the above examples, an option object may be passed in addition to the username and password (or user credentials). The following options are supported:

    • cnonce: provides a string to be used as the cnonce in digest authentication Authorization headers. If this option is not provided, a random cnonce will be generated.
    • sendImmediately: (high level interface only). If this option tests true, an Authorization header will always be produced, even if a WWW-Authenticate header has not been received. Until a WWW-Authenticate header is received, a Basic Authorization header will be generated. Once a WWW-Authenticate header is received, it's challenge will define the content of the Authorization header.

    WWW-Authenticate header parser:

    This module exports the parser that is used internally to parse a WWW-Authenticate header. Please see the tests for usage examples.

    Contributing

    In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

    Release History

    • v0.6.0: Add sendImmediately option. Inspired by request module.
    • v0.5.0: The higher-level interface is now exported directly by the module
    • v0.4.0: Provides a higher-level interface
    • v0.3.0: If password is null, it, and preceding ':' will not be included in hash

    License

    Copyright (c) 2013 Randy McLaughlin Licensed under the MIT license.

    Keywords

    none

    install

    npm i www-authenticate

    Downloadslast 7 days

    1,839

    version

    0.6.2

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar