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:
import assert from 'assert';
import {
parseAuthorizationHeader,
mechanisms,
} from 'http-auth-utils';
const FAKE_MECHANISM = {
type: 'Fake',
parseAuthorizationRest: rest => {
let userId;
let scopes;
rest.replace(/^(\d+)-((\w+,)*(\w+){1})$/, (_, rawUserId, rawScopes) => {
userId = parseInt(rawUserId);
scopes = rawScopes.split(',');
return '';
});
if ('undefined' === typeof userId || 'undefined' === typeof scopes) {
throw new HTTPError(400, 'E_INVALID_FAKE_TOKEN');
}
return {
hash: rest,
userId,
scopes,
};
},
};
assert.deepEqual(
parseAuthorizationHeader('Fake 1664-read,write', [
...mechanisms,
FAKE_MECHANISM,
]), {
type: 'Fake',
data: {
hash: '1664-read,write',
userId: 1664,
scopes: ['read', 'write'],
}
}
);
API
Modules
- http-auth-utils
- http-auth-utils/mechanisms/basic
- http-auth-utils/mechanisms/bearer
- http-auth-utils/mechanisms/digest
http-auth-utils
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. |
Example
assert.deepEqual(
parseWWWAuthenticateHeader('Basic realm="test"'), {
type: 'Basic',
data: {
realm: 'test'
}
}
);
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. |
Example
assert.deepEqual(
parseAuthorizationHeader('Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='), {
type: 'Basic',
data: {
hash: 'QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
}
}
);
http-auth-utils~mechanisms : Array
Natively supported authentication mechanisms.
Kind: inner constant of http-auth-utils
http-auth-utils/mechanisms/basic
http-auth-utils/mechanisms/basic~BASIC : Object
Basic authentication mechanism.
Kind: inner constant of http-auth-utils/mechanisms/basic
See: http://tools.ietf.org/html/rfc2617#section-2
BASIC.type : String
The Basic auth mechanism prefix.
Kind: static property of BASIC
BASIC.parseWWWAuthenticateRest(rest) ⇒ Object
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'
}
);
BASIC.buildWWWAuthenticateRest(data) ⇒ String
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"'
);
BASIC.parseAuthorizationRest(rest) ⇒ Object
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'
}
);
BASIC.buildAuthorizationRest(content) ⇒ String
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='
);
BASIC.computeHash(credentials) ⇒ String
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='
);
BASIC.decodeHash(hash) ⇒ Object
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
Bearer authentication mechanism.
Kind: inner constant of http-auth-utils/mechanisms/bearer
See: https://tools.ietf.org/html/rfc6750#section-3
BEARER.type : String
The Digest auth mechanism prefix.
Kind: static property of BEARER
BEARER.parseWWWAuthenticateRest(rest) ⇒ Object
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',
}
);
BEARER.buildWWWAuthenticateRest(data) ⇒ String
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"'
);
BEARER.parseAuthorizationRest(rest) ⇒ Object
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',
}
);
BEARER.buildAuthorizationRest(content) ⇒ String
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
Digest authentication mechanism.
Kind: inner constant of http-auth-utils/mechanisms/digest
See
DIGEST.type : String
The Digest auth mechanism prefix.
Kind: static property of DIGEST
DIGEST.parseWWWAuthenticateRest(rest) ⇒ Object
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'
}
);
DIGEST.buildWWWAuthenticateRest(data) ⇒ String
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 wich 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"'
);
DIGEST.parseAuthorizationRest(rest) ⇒ Object
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"
}
);
DIGEST.buildAuthorizationRest(data) ⇒ String
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 wich 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"'
);
DIGEST.computeHash(data) ⇒ String
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'
);
Authors
License
MIT