Parse, build and deal with HTTP auth headers.
MIT License
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.
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'
}
}
);
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=='
}
}
);
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"'
);
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"'
);
Natively supported authentication mechanisms.
Kind: inner constant of http-auth-utils
Basic authentication mechanism.
Kind: inner constant of http-auth-utils/mechanisms/basic See: http://tools.ietf.org/html/rfc2617#section-2
The Basic auth mechanism prefix.
Kind: static property of BASIC
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'
}
);
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"'
);
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'
}
);
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='
);
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='
);
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'
}
);
Bearer authentication mechanism.
Kind: inner constant of http-auth-utils/mechanisms/bearer See: https://tools.ietf.org/html/rfc6750#section-3
The Bearer auth mechanism prefix.
Kind: static property of BEARER
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="[email protected]", ' +
'scope="openid profile email"'
), {
realm: '[email protected]',
scope: 'openid profile email',
}
);
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: '[email protected]',
error: 'invalid_request',
error_description: 'The access token expired',
}),
'realm="[email protected]", ' +
'error="invalid_request", ' +
'error_description="The access token expired"'
);
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',
}
);
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=='
);
Digest authentication mechanism.
Kind: inner constant of http-auth-utils/mechanisms/digest See
The Digest auth mechanism prefix.
Kind: static property of DIGEST
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="[email protected]", ' +
'qop="auth, auth-int", ' +
'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
), {
realm: '[email protected]',
qop: 'auth, auth-int',
nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
opaque: '5ccc069c403ebaf9f0171e9517f40e41'
}
);
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: '[email protected]',
qop: 'auth, auth-int',
nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
opaque: '5ccc069c403ebaf9f0171e9517f40e41'
}),
'realm="[email protected]", ' +
'qop="auth, auth-int", ' +
'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
);
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="[email protected]",' +
'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",' +
'uri="/dir/index.html",' +
'qop="auth",' +
'nc="00000001",' +
'cnonce="0a4f113b",' +
'response="6629fae49393a05397450978507c4ef1",' +
'opaque="5ccc069c403ebaf9f0171e9517f40e41"'
), {
username: "Mufasa",
realm: '[email protected]',
nonce: "dcd98b7102dd2f0e8b11d0f600bfb0c093",
uri: "/dir/index.html",
qop: 'auth',
nc: '00000001',
cnonce: "0a4f113b",
response: "6629fae49393a05397450978507c4ef1",
opaque: "5ccc069c403ebaf9f0171e9517f40e41"
}
);
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: '[email protected]',
nonce: "dcd98b7102dd2f0e8b11d0f600bfb0c093",
uri: "/dir/index.html",
qop: 'auth',
nc: '00000001',
cnonce: "0a4f113b",
response: "6629fae49393a05397450978507c4ef1",
opaque: "5ccc069c403ebaf9f0171e9517f40e41"
}),
'username="Mufasa", ' +
'realm="[email protected]", ' +
'nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", ' +
'uri="/dir/index.html", ' +
'response="6629fae49393a05397450978507c4ef1", ' +
'cnonce="0a4f113b", ' +
'opaque="5ccc069c403ebaf9f0171e9517f40e41", ' +
'qop="auth", ' +
'nc="00000001"'
);
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: '[email protected]',
password: 'Circle Of Life',
method: 'GET',
uri: '/dir/index.html',
nonce: 'dcd98b7102dd2f0e8b11d0f600bfb0c093',
nc: '00000001',
cnonce: '0a4f113b',
qop: 'auth',
algorithm: 'md5'
}),
'6629fae49393a05397450978507c4ef1'
);