1 | # passport-ldapauth
|
2 |
|
3 | [Passport](http://passportjs.org/) authentication strategy against LDAP server. This module is a Passport strategy wrapper for [ldapauth-fork](https://github.com/vesse/node-ldapauth-fork)
|
4 |
|
5 | ## Install
|
6 |
|
7 | ```
|
8 | npm install passport-ldapauth
|
9 | ```
|
10 |
|
11 | ## Status
|
12 |
|
13 | [![Build Status](https://travis-ci.org/vesse/passport-ldapauth.png)](https://travis-ci.org/vesse/passport-ldapauth)
|
14 | [![Dependency Status](https://gemnasium.com/vesse/passport-ldapauth.png)](https://gemnasium.com/vesse/passport-ldapauth)
|
15 |
|
16 | ## Usage
|
17 |
|
18 | ### Configure strategy
|
19 |
|
20 | ```javascript
|
21 | var LdapStrategy = require('passport-ldapauth');
|
22 |
|
23 | passport.use(new LdapStrategy({
|
24 | server: {
|
25 | url: 'ldap://localhost:389',
|
26 | ...
|
27 | }
|
28 | }));
|
29 | ```
|
30 |
|
31 | * `server`: LDAP settings. These are passed directly to [ldapauth-fork](https://github.com/vesse/node-ldapauth-fork). See its documentation for all available options.
|
32 | * `url`: e.g. `ldap://localhost:389`
|
33 | * `bindDn`: e.g. `cn='root'`
|
34 | * `bindCredentials`: Password for bindDn
|
35 | * `searchBase`: e.g. `o=users,o=example.com`
|
36 | * `searchFilter`: LDAP search filter, e.g. `(uid={{username}})`. Use literal `{{username}}` to have the given username used in the search.
|
37 | * `searchAttributes`: Optional array of attributes to fetch from LDAP server, e.g. `['displayName', 'mail']`. Defaults to `undefined`, i.e. fetch all attributes
|
38 | * `tlsOptions`: Optional object with options accepted by Node.js [tls](http://nodejs.org/api/tls.html#tls_tls_connect_options_callback) module.
|
39 | * `usernameField`: Field name where the username is found, defaults to _username_
|
40 | * `passwordField`: Field name where the password is found, defaults to _password_
|
41 | * `passReqToCallback`: When `true`, `req` is the first argument to the verify callback (default: `false`):
|
42 |
|
43 | passport.use(new LdapStrategy(..., function(req, user, done) {
|
44 | ...
|
45 | done(null, user);
|
46 | }
|
47 | ));
|
48 |
|
49 | Note: you can pass a function instead of an object as `options`, see the [example below](#options-as-function)
|
50 |
|
51 | ### Authenticate requests
|
52 |
|
53 | Use `passport.authenticate()`, specifying the `'ldapauth'` strategy, to authenticate requests.
|
54 |
|
55 | #### `authenticate()` options
|
56 |
|
57 | In addition to [default authentication options](http://passportjs.org/guide/authenticate/) the following options are available for `passport.authenticate()`:
|
58 |
|
59 | * `badRequestMessage` flash message for missing username/password (default: 'Missing credentials')
|
60 | * `invalidCredentials` flash message for `InvalidCredentialsError`, `NoSuchObjectError`, and `/no such user/i` LDAP errors (default: 'Invalid username/password')
|
61 | * `userNotFound` flash message when LDAP returns no error but also no user (default: 'Invalid username/password')
|
62 | * `constraintViolation` flash message when user account is locked (default: 'Exceeded password retry limit, account locked')
|
63 |
|
64 | ## Express example
|
65 |
|
66 | ```javascript
|
67 | var express = require('express'),
|
68 | passport = require('passport'),
|
69 | bodyParser = require('body-parser'),
|
70 | LdapStrategy = require('passport-ldapauth');
|
71 |
|
72 | var OPTS = {
|
73 | server: {
|
74 | url: 'ldap://localhost:389',
|
75 | bindDn: 'cn=root',
|
76 | bindCredentials: 'secret',
|
77 | searchBase: 'ou=passport-ldapauth',
|
78 | searchFilter: '(uid={{username}})'
|
79 | }
|
80 | };
|
81 |
|
82 | var app = express();
|
83 |
|
84 | passport.use(new LdapStrategy(OPTS));
|
85 |
|
86 | app.use(bodyParser.json());
|
87 | app.use(bodyParser.urlencoded({extended: false}));
|
88 | app.use(passport.initialize());
|
89 |
|
90 | app.post('/login', passport.authenticate('ldapauth', {session: false}), function(req, res) {
|
91 | res.send({status: 'ok'});
|
92 | });
|
93 |
|
94 | app.listen(8080);
|
95 | ```
|
96 |
|
97 | ### Active Directory over SSL example
|
98 |
|
99 | Simple example config for connecting over `ldaps://` to a server requiring some internal CA certificate (often the case in corporations using Windows AD).
|
100 |
|
101 | ```javascript
|
102 | var fs = require('fs');
|
103 |
|
104 | var opts = {
|
105 | server: {
|
106 | url: 'ldaps://ad.corporate.com:636',
|
107 | bindDn: 'cn=non-person,ou=system,dc=corp,dc=corporate,dc=com',
|
108 | bindCredentials: 'secret',
|
109 | searchBase: 'dc=corp,dc=corporate,dc=com',
|
110 | searchFilter: '(&(objectcategory=person)(objectclass=user)(|(samaccountname={{username}})(mail={{username}})))',
|
111 | searchAttributes: ['displayName', 'mail'],
|
112 | tlsOptions: {
|
113 | ca: [
|
114 | fs.readFileSync('/path/to/root_ca_cert.crt')
|
115 | ]
|
116 | }
|
117 | }
|
118 | };
|
119 | ...
|
120 | ```
|
121 |
|
122 | <a name="options-as-function"></a>
|
123 | ## Asynchronous configuration retrieval
|
124 |
|
125 | Instead of providing a static configuration object, you can pass a function as `options` that will take care of fetching the configuration. It will be called with the and a callback function having the standard `(err, result)` signature. Notice that the provided function will be called on every authenticate request.
|
126 |
|
127 | ```javascript
|
128 | var getLDAPConfiguration = function(req, callback) {
|
129 | // Fetching things from database or whatever
|
130 | process.nextTick(function() {
|
131 | var opts = {
|
132 | server: {
|
133 | url: 'ldap://localhost:389',
|
134 | bindDn: 'cn=root',
|
135 | bindCredentials: 'secret',
|
136 | searchBase: 'ou=passport-ldapauth',
|
137 | searchFilter: '(uid={{username}})'
|
138 | }
|
139 | };
|
140 |
|
141 | callback(null, opts);
|
142 | });
|
143 | };
|
144 |
|
145 | var LdapStrategy = require('passport-ldapauth');
|
146 |
|
147 | passport.use(new LdapStrategy(getLDAPConfiguration,
|
148 | function(user, done) {
|
149 | ...
|
150 | return done(null, user);
|
151 | }
|
152 | ));
|
153 | ```
|
154 |
|
155 | ## License
|
156 |
|
157 | MIT
|