http-auth-utils
Parse, build and deal with HTTP authorization headers.
This library provide several utilities to parse and build WWW-Authenticate and Authorization headers as described per the HTTP RFC.
It is intended to be framework agnostic and could be used either on the server and the client side. It is also pure functions only, no side effect here. The functions are synchronous since only parsing headers of small size so no need for streams or anything asynchronous.
The module is easily extensible with new mechanisms, one very common way to
extend it is to create a FAKE_TOKEN
mechanism for development only that allows
to directly provide the userId that should be authenticated. You can find
an sample implementation
in the Whook's framework repository.
API
Modules
- http-auth-utils
- http-auth-utils/mechanisms/basic
- http-auth-utils/mechanisms/bearer
- http-auth-utils/mechanisms/digest
http-auth-utils
-
http-auth-utils
- static
-
inner
-
~mechanisms :
Array
-
~mechanisms :
Object
http-auth-utils.parseWWWAuthenticateHeader(header, [authMechanisms], [options]) ⇒ Parse HTTP WWW-Authenticate header contents.
Kind: static method of http-auth-utils
Returns: Object
- Result of the contents parse.
Api: public
Param | Type | Default | Description |
---|---|---|---|
header | string |
The WWW-Authenticate header contents | |
[authMechanisms] | Array |
[BASIC, DIGEST, BEARER] |
Allow providing custom authentication mechanisms. |
[options] | Object |
Parsing options | |
[options.strict] | boolean |
true |
Strictly detect the mechanism type (case sensitive) |
Example
assert.deepEqual(
parseWWWAuthenticateHeader('Basic realm="test"'), {
type: 'Basic',
data: {
realm: 'test'
}
}
);
Object
http-auth-utils.parseAuthorizationHeader(header, [authMechanisms], [options]) ⇒ Parse HTTP Authorization header contents.
Kind: static method of http-auth-utils
Returns: Object
- Result of the contents parse.
Api: public
Param | Type | Default | Description |
---|---|---|---|
header | string |
The Authorization header contents | |
[authMechanisms] | Array |
[BASIC, DIGEST, BEARER] |
Allow custom authentication mechanisms. |
[options] | Object |
Parsing options | |
[options.strict] | boolean |
true |
Strictly detect the mechanism type (case sensitive) |
Example
assert.deepEqual(
parseAuthorizationHeader('Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='), {
type: 'Basic',
data: {
hash: 'QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
}
}
);
string
http-auth-utils.buildWWWAuthenticateHeader(authMechanism, The) ⇒ Build HTTP WWW-Authenticate header value.
Kind: static method of http-auth-utils
Returns: string
- The header value.
Api: public
Param | Type | Description |
---|---|---|
authMechanism | Object |
The mechanism to use |
The | Object |
WWW-Authenticate header contents to base the value on. |
Example
assert.deepEqual(
buildWWWAuthenticateHeader(BASIC, {
realm: 'test'
}),
'Basic realm="test"'
);
string
http-auth-utils.buildAuthorizationHeader(authMechanism, The) ⇒ Build HTTP Authorization header value.
Kind: static method of http-auth-utils
Returns: string
- The header value.
Api: public
Param | Type | Description |
---|---|---|
authMechanism | Object |
The mechanism to use |
The | Object |
Authorization header contents to base the value on. |
Example
assert.deepEqual(
buildAuthorizationHeader(BASIC, {
realm: 'test'
}),
'Basic realm="test"'
);
Array
http-auth-utils~mechanisms : Natively supported authentication mechanisms.
Kind: inner constant of http-auth-utils
http-auth-utils/mechanisms/basic
-
http-auth-utils/mechanisms/basic
-
~BASIC :
Object
-
.type :
String
-
.parseWWWAuthenticateRest(rest) ⇒
Object
-
.buildWWWAuthenticateRest(data) ⇒
String
-
.parseAuthorizationRest(rest) ⇒
Object
-
.buildAuthorizationRest(content) ⇒
String
-
.computeHash(credentials) ⇒
String
-
.decodeHash(hash) ⇒
Object
-
.type :
-
~BASIC :
Object
http-auth-utils/mechanisms/basic~BASIC : Basic authentication mechanism.
Kind: inner constant of http-auth-utils/mechanisms/basic
See: http://tools.ietf.org/html/rfc2617#section-2
-
~BASIC :
Object
-
.type :
String
-
.parseWWWAuthenticateRest(rest) ⇒
Object
-
.buildWWWAuthenticateRest(data) ⇒
String
-
.parseAuthorizationRest(rest) ⇒
Object
-
.buildAuthorizationRest(content) ⇒
String
-
.computeHash(credentials) ⇒
String
-
.decodeHash(hash) ⇒
Object
-
.type :
String
BASIC.type : The Basic auth mechanism prefix.
Kind: static property of BASIC
Object
BASIC.parseWWWAuthenticateRest(rest) ⇒ Parse the WWW Authenticate header rest.
Kind: static method of BASIC
Returns: Object
- Object representing the result of the parse operation.
Api: public
Param | Type | Description |
---|---|---|
rest | String |
The header rest (string after the authentication mechanism prefix). |
Example
assert.deepEqual(
BASIC.parseWWWAuthenticateRest('realm="perlinpinpin"'), {
realm: 'perlinpinpin'
}
);
String
BASIC.buildWWWAuthenticateRest(data) ⇒ Build the WWW Authenticate header rest.
Kind: static method of BASIC
Returns: String
- The built rest.
Api: public
Param | Type | Description |
---|---|---|
data | Object |
The content from wich to build the rest. |
Example
assert.equal(
BASIC.buildWWWAuthenticateRest({
realm: 'perlinpinpin'
}),
'realm="perlinpinpin"'
);
Object
BASIC.parseAuthorizationRest(rest) ⇒ Parse the Authorization header rest.
Kind: static method of BASIC
Returns: Object
- Object representing the result of the parse operation {hash}.
Api: public
Param | Type | Description |
---|---|---|
rest | String |
The header rest (string after the authentication mechanism prefix).) |
Example
assert.deepEqual(
BASIC.parseAuthorizationRest('QWxpIEJhYmE6b3BlbiBzZXNhbWU='), {
hash: 'QWxpIEJhYmE6b3BlbiBzZXNhbWU=',
username: 'Ali Baba',
password: 'open sesame'
}
);
String
BASIC.buildAuthorizationRest(content) ⇒ Build the Authorization header rest.
Kind: static method of BASIC
Returns: String
- The rest built.
Api: public
Param | Type | Description |
---|---|---|
content | Object |
The content from wich to build the rest. |
Example
assert.equal(
BASIC.buildAuthorizationRest({
hash: 'QWxpIEJhYmE6b3BlbiBzZXNhbWU='
}),
'QWxpIEJhYmE6b3BlbiBzZXNhbWU='
);
String
BASIC.computeHash(credentials) ⇒ Compute the Basic authentication hash from the given credentials.
Kind: static method of BASIC
Returns: String
- The hash representing the credentials.
Api: public
Param | Type | Description |
---|---|---|
credentials | Object |
The credentials to encode {username, password}. |
Example
assert.equal(
BASIC.computeHash({
username: 'Ali Baba',
password: 'open sesame'
}),
'QWxpIEJhYmE6b3BlbiBzZXNhbWU='
);
Object
BASIC.decodeHash(hash) ⇒ Decode the Basic hash and return the corresponding credentials.
Kind: static method of BASIC
Returns: Object
- Object representing the credentials {username, password}.
Api: public
Param | Type | Description |
---|---|---|
hash | String |
The hash. |
Example
assert.deepEqual(
BASIC.decodeHash('QWxpIEJhYmE6b3BlbiBzZXNhbWU='), {
username: 'Ali Baba',
password: 'open sesame'
}
);
http-auth-utils/mechanisms/bearer
-
http-auth-utils/mechanisms/bearer
-
~BEARER :
Object
-
.type :
String
-
.parseWWWAuthenticateRest(rest) ⇒
Object
-
.buildWWWAuthenticateRest(data) ⇒
String
-
.parseAuthorizationRest(rest) ⇒
Object
-
.buildAuthorizationRest(content) ⇒
String
-
.type :
-
~BEARER :
Object
http-auth-utils/mechanisms/bearer~BEARER : Bearer authentication mechanism.
Kind: inner constant of http-auth-utils/mechanisms/bearer
See: https://tools.ietf.org/html/rfc6750#section-3
-
~BEARER :
Object
-
.type :
String
-
.parseWWWAuthenticateRest(rest) ⇒
Object
-
.buildWWWAuthenticateRest(data) ⇒
String
-
.parseAuthorizationRest(rest) ⇒
Object
-
.buildAuthorizationRest(content) ⇒
String
-
.type :
String
BEARER.type : The Bearer auth mechanism prefix.
Kind: static property of BEARER
Object
BEARER.parseWWWAuthenticateRest(rest) ⇒ Parse the WWW Authenticate header rest.
Kind: static method of BEARER
Returns: Object
- Object representing the result of the parse operation.
Api: public
Param | Type | Description |
---|---|---|
rest | String |
The header rest (string after the authentication mechanism prefix). |
Example
assert.deepEqual(
BEARER.parseWWWAuthenticateRest(
'realm="testrealm@host.com", ' +
'scope="openid profile email"'
), {
realm: 'testrealm@host.com',
scope: 'openid profile email',
}
);
String
BEARER.buildWWWAuthenticateRest(data) ⇒ Build the WWW Authenticate header rest.
Kind: static method of BEARER
Returns: String
- The built rest.
Api: public
Param | Type | Description |
---|---|---|
data | Object |
The content from wich to build the rest. |
Example
assert.equal(
BEARER.buildWWWAuthenticateRest({
realm: 'testrealm@host.com',
error: 'invalid_request',
error_description: 'The access token expired',
}),
'realm="testrealm@host.com", ' +
'error="invalid_request", ' +
'error_description="The access token expired"'
);
Object
BEARER.parseAuthorizationRest(rest) ⇒ Parse the Authorization header rest.
Kind: static method of BEARER
Returns: Object
- Object representing the result of the parse operation {hash}.
Api: public
Param | Type | Description |
---|---|---|
rest | String |
The header rest (string after the authentication mechanism prefix).) |
Example
assert.deepEqual(
BEARER.parseAuthorizationRest('mF_9.B5f-4.1JqM'), {
hash: 'mF_9.B5f-4.1JqM',
}
);
String
BEARER.buildAuthorizationRest(content) ⇒ Build the Authorization header rest.
Kind: static method of BEARER
Returns: String
- The rest built.
Api: public
Param | Type | Description |
---|---|---|
content | Object |
The content from wich to build the rest. |
Example
assert.equal(
BEARER.buildAuthorizationRest({
hash: 'mF_9.B5f-4.1JqM'
}),
'mF_9.B5f-4.1JqM=='
);
http-auth-utils/mechanisms/digest
-
http-auth-utils/mechanisms/digest
-
~DIGEST :
Object
-
.type :
String
-
.parseWWWAuthenticateRest(rest) ⇒
Object
-
.buildWWWAuthenticateRest(data) ⇒
String
-
.parseAuthorizationRest(rest) ⇒
Object
-
.buildAuthorizationRest(data) ⇒
String
-
.computeHash(data) ⇒
String
-
.type :
-
~DIGEST :
Object
http-auth-utils/mechanisms/digest~DIGEST : Digest authentication mechanism.
Kind: inner constant of http-auth-utils/mechanisms/digest
See
-
~DIGEST :
Object
-
.type :
String
-
.parseWWWAuthenticateRest(rest) ⇒
Object
-
.buildWWWAuthenticateRest(data) ⇒
String
-
.parseAuthorizationRest(rest) ⇒
Object
-
.buildAuthorizationRest(data) ⇒
String
-
.computeHash(data) ⇒
String
-
.type :
String
DIGEST.type : The Digest auth mechanism prefix.
Kind: static property of DIGEST
Object
DIGEST.parseWWWAuthenticateRest(rest) ⇒ Parse the WWW Authenticate header rest.
Kind: static method of DIGEST
Returns: Object
- Object representing the result of the parse operation.
Api: public
Param | Type | Description |
---|---|---|
rest | String |
The header rest (string after the authentication mechanism prefix). |
Example
assert.deepEqual(
DIGEST.parseWWWAuthenticateRest(
'realm="testrealm@host.com", ' +
'qop="auth, auth-int", ' +
'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
), {
realm: 'testrealm@host.com',
qop: 'auth, auth-int',
nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
opaque: '5ccc069c403ebaf9f0171e9517f40e41'
}
);
String
DIGEST.buildWWWAuthenticateRest(data) ⇒ Build the WWW Authenticate header rest.
Kind: static method of DIGEST
Returns: String
- The built rest.
Api: public
Param | Type | Description |
---|---|---|
data | Object |
The content from which to build the rest. |
Example
assert.equal(
DIGEST.buildWWWAuthenticateRest({
realm: 'testrealm@host.com',
qop: 'auth, auth-int',
nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
opaque: '5ccc069c403ebaf9f0171e9517f40e41'
}),
'realm="testrealm@host.com", ' +
'qop="auth, auth-int", ' +
'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
);
Object
DIGEST.parseAuthorizationRest(rest) ⇒ Parse the Authorization header rest.
Kind: static method of DIGEST
Returns: Object
- Object representing the result of the parse operation {hash}.
Api: public
Param | Type | Description |
---|---|---|
rest | String |
The header rest (string after the authentication mechanism prefix).) |
Example
assert.deepEqual(
DIGEST.parseAuthorizationRest(
'username="Mufasa",' +
'realm="testrealm@host.com",' +
'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",' +
'uri="/dir/index.html",' +
'qop="auth",' +
'nc="00000001",' +
'cnonce="0a4f113b",' +
'response="6629fae49393a05397450978507c4ef1",' +
'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
), {
username: "Mufasa",
realm: 'testrealm@host.com',
nonce: "dcd98b7102dd2f0e8b11d0f600bfb0c093",
uri: "/dir/index.html",
qop: 'auth',
nc: '00000001',
cnonce: "0a4f113b",
response: "6629fae49393a05397450978507c4ef1",
opaque: "5ccc069c403ebaf9f0171e9517f40e41"
}
);
String
DIGEST.buildAuthorizationRest(data) ⇒ Build the Authorization header rest.
Kind: static method of DIGEST
Returns: String
- The rest built.
Api: public
Param | Type | Description |
---|---|---|
data | Object |
The content from which to build the rest. |
Example
assert.equal(
DIGEST.buildAuthorizationRest({
username: "Mufasa",
realm: 'testrealm@host.com',
nonce: "dcd98b7102dd2f0e8b11d0f600bfb0c093",
uri: "/dir/index.html",
qop: 'auth',
nc: '00000001',
cnonce: "0a4f113b",
response: "6629fae49393a05397450978507c4ef1",
opaque: "5ccc069c403ebaf9f0171e9517f40e41"
}),
'username="Mufasa", ' +
'realm="testrealm@host.com", ' +
'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
'uri="/dir/index.html", ' +
'response="6629fae49393a05397450978507c4ef1", ' +
'cnonce="0a4f113b", ' +
'opaque="5ccc069c403ebaf9f0171e9517f40e41", ' +
'qop="auth", ' +
'nc="00000001"'
);
String
DIGEST.computeHash(data) ⇒ Compute the Digest authentication hash from the given credentials.
Kind: static method of DIGEST
Returns: String
- The hash representing the credentials.
Api: public
Param | Type | Description |
---|---|---|
data | Object |
The credentials to encode and other encoding details. |
Example
assert.equal(
DIGEST.computeHash({
username: 'Mufasa',
realm: 'testrealm@host.com',
password: 'Circle Of Life',
method: 'GET',
uri: '/dir/index.html',
nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
nc: '00000001',
cnonce: '0a4f113b',
qop: 'auth',
algorithm: 'md5'
}),
'6629fae49393a05397450978507c4ef1'
);