Parse, build and deal with HTTP authorization headers.
npm install http-auth-utils[//]: # ( )
[//]: # (This file is automatically generated by a metapak)
[//]: # (module. Do not change it except between the)
[//]: # (content:start/end flags, your changes would)
[//]: # (be overridden.)
[//]: # ( )
[//]: # (::contents:start)
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.
[//]: # (::contents:end)
* http-auth-utils
* _static_
* [.parseWWWAuthenticateHeader(header, [authMechanisms], [options])](#module_http-auth-utils.parseWWWAuthenticateHeader) ⇒ Object
* [.parseAuthorizationHeader(header, [authMechanisms], [options])](#module_http-auth-utils.parseAuthorizationHeader) ⇒ Object
* .buildWWWAuthenticateHeader(authMechanism, The) ⇒ string
* .buildAuthorizationHeader(authMechanism, The) ⇒ string
* _inner_
* ~mechanisms : Array
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
``js`
assert.deepEqual(
parseWWWAuthenticateHeader('Basic realm="test"'), {
type: 'Basic',
data: {
realm: 'test'
}
}
);
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
`js`
assert.deepEqual(
parseAuthorizationHeader('Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='), {
type: 'Basic',
data: {
hash: 'QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
}
}
);
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
`js`
assert.deepEqual(
buildWWWAuthenticateHeader(BASIC, {
realm: 'test'
}),
'Basic realm="test"'
);
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
`js`
assert.deepEqual(
buildAuthorizationHeader(BASIC, {
realm: 'test'
}),
'Basic realm="test"'
);
Kind: inner constant of http-auth-utils
* 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
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
#### 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
`js`
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
`js`
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
`js`
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
`js`
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
`js`
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
`js`
assert.deepEqual(
BASIC.decodeHash('QWxpIEJhYmE6b3BlbiBzZXNhbWU='), {
username: 'Ali Baba',
password: 'open sesame'
}
);
* http-auth-utils/mechanisms/bearer
* ~BEARER : Object
* .type : String
* .parseWWWAuthenticateRest(rest) ⇒ Object
* .buildWWWAuthenticateRest(data) ⇒ String
* .parseAuthorizationRest(rest) ⇒ Object
* .buildAuthorizationRest(content) ⇒ String
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
#### BEARER.type : String
The Bearer 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
`js`
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
`js`
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
`js`
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
`js`
assert.equal(
BEARER.buildAuthorizationRest({
hash: 'mF_9.B5f-4.1JqM'
}),
'mF_9.B5f-4.1JqM=='
);
* http-auth-utils/mechanisms/digest
* ~DIGEST : Object
* .type : String
* .parseWWWAuthenticateRest(rest) ⇒ Object
* .buildWWWAuthenticateRest(data) ⇒ String
* .parseAuthorizationRest(rest) ⇒ Object
* .buildAuthorizationRest(data) ⇒ String
* .computeHash(data) ⇒ String
Kind: inner constant of http-auth-utils/mechanisms/digest
See
- http://tools.ietf.org/html/rfc2617#section-3
- http://tools.ietf.org/html/rfc2069#section-2
* ~DIGEST : Object
* .type : String
* .parseWWWAuthenticateRest(rest) ⇒ Object
* .buildWWWAuthenticateRest(data) ⇒ String
* .parseAuthorizationRest(rest) ⇒ Object
* .buildAuthorizationRest(data) ⇒ String
* .computeHash(data) ⇒ String
#### 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
`js`
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 which to build the rest. |
Example
`js`
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
`js`
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 which to build the rest. |
Example
`js`
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
`js``
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'
);