Kerberos for Node.js
krb5 is a Node.js native binding for Kerberos. It is a Node.js implementation of Kerberos client tools:
- kinit (keytab, or password): retrieve initial credentials;
- kdestroy: destroy a credential cache;
- spnego: generate a SPNEGO token.
It uses the MIT Kerberos native library.
SPNEGO is a GSS mechanism to authenticate through HTTP requests.
Installation
To build this module, you need MIT Kerberos library. Refer to the section corresponding to your operating system:
- Archlinux
pacman -S krb5 npm install krb5
- RHEL/Centos
yum install -y krb5-devel npm install krb5
- Ubuntu
apt-get install -y libkrb5-dev npm install krb5
- MacOS
brew install krb5 npm install krb5
- Windows
choco install mitkerberos --install-arguments="ADDLOCAL=all" npm install krb5
Python >=3.6 must be available in your path. You can check it by running python --version
. It should display something like "Python 3.6.15". If not, you must ensure that python 3 is used, for by placing back the original path: PATH="/usr/bin:$PATH" npm install
.
Windows
To compile this library on windows, you need a complete visual studio compile chain, please refer to the node-gyp instructions. If you have a 32 bit OS, please delete binding.gyp
and rename _binding32.gyp
before install.
To install the kerberos headers needed for the build, you need to tick the "SDK" options. It is disabled by default.
z/OS
Install curl for z/OS and gzip for z/OS, then follow the instruction here.
Manual compilation of MIT Kerberos
Follow these instructions if you wish to manually install MIT Kerberos (in case your distribution packet manager does not have a corresponding package for example).
wget https://kerberos.org/dist/krb5/1.16/krb5-1.16.1.tar.gz
tar -xzf krb5-1.16.1.tar.gz
cd krb5-1.16.1/src
./configure
make
sudo make install
The latest version downloaded with wget
can be found here.
Compiling from the source of MIT Kerberos requires python3
, make
, gcc
(g++
), bison
.
If you want to install MIT Kerberos in another directory (default is "/usr/local"), specify a --prefix
option to ./configure
.
If kerberos is installed in a directory not included in include and/or library path (if you have manually compiled kerberos in a specific directory for example), please modify the binding.gyp present in the package root folder with the following properties:
{
'targets': [{
'target_name': 'krb5',
'include_dirs': [
'/path/to/kerberos/include/dir/',
'/path/to/kerberos_gssapi/include/dir/'],
'libraries': [
'/path/to/libkrb5',
'/path/to/libgssapi_krb5']
}]
}
or you can specify the following environment variables to npm install
command:
export CPLUS_INCLUDE_PATH="/path/to/kerberos/include"
export LIBRARY_PATH="/path/to/kerberos/lib"
Install node-krb5 on z/OS
- run the following command to install krb5 libraries for z/OS (it requires curl for z/OS and gzip for z/OS)
_ENCODE_FILE_NEW=BINARY curl https://codeload.github.com/ibmruntimes/libkrb5-zos/tar.gz/v1.16.3-zos --output v1.16.3-zos.tar.gz
gzip -d v1.16.3-zos.tar.gz
tar -xfUXo v1.16.3-zos.tar
chtag -tc 819 -R ./libkrb5-zos-1.16.3-zos
chtag -b -R ./libkrb5-zos-1.16.3-zos/lib
- set the following environment variable
export KRB5_HOME=/path/to/libkrb5-zos-1.16.3-zos
npm install node-krb5
Remember to specify your krb5.conf
:
export KRB5_CONFIG=/path/to/krb5.conf
Usage
Quick example
- Retrieve a SPNEGO token for a service
In this example we want to retrieve a token to access a REST API of the service HBase, located on the host m01.krb.local
.
// Get the initial credentials using a keytab
krb5.kinit({
principal: 'hbase/m01.krb.local',
keytab: '/tmp/hbase.service.keytab',
realm: 'KRB.LOCAL',
}, function (err, ccname) {
if (err) {
console.log(err)
} else {
console.log('Credentials saved in', ccname)
// Get the SPNEGO token
krb5.spnego({
service_fqdn: 'm01.krb.local'
}, function (err, token) {
if (err) {
console.log(err)
} else {
console.log('SPNEGO token :', token)
}
})
}
});
You can also use promises.
krb5.kinit({
principal: 'hbase/m01.krb.local',
keytab: '/tmp/hbase.service.keytab',
realm: 'KRB.LOCAL',
}).then(function (ccname) {
console.log('Credentials saved in', ccname)
return krb5.spnego({
hostbased_service: 'HTTP@m01.krb.local'
})
}).then(function (token) {
console.log('SPNEGO token :', token)
}).catch(function (err) {
console.log(err)
})
For more examples, see the samples and test directories.
Functions
kinit(options, callback)
Retrieve initial credentials (Ticket Granting Ticket)
Options:
-
principal
Kerberos principal username@REALM or username. If realm is given, overrides the realm option. -
password
/keytab
One of both should be given for authentication. -
realm
(optionnal)
Kerberos realm (usually capitalized domain name). If this is not specified, use the default realm from/etc/krb5.conf
. -
ccname
(optionnal)
Credential cache location. If this is not specified, default path is taken from environment variableKRB5CCNAME
, then from/etc/krb5.conf
.
Callback parameters:
-
err
Should beundefined
. Otherwise it contains an error message. -
ccname
Credential path location used to store initial credentials.
spnego(options, callback)
Retrieve a SPNEGO token.
In order to retrieve a SPNEGO token to access a service, you first need an initial ticket (TGT) which you can get with kinit
.
Options:
-
hostbased_service
orservice_fqdn
Hostbased service should be of the formservice@fqdn
. If you only pass the fully qualified domain namefqdn
, it will default toHTTP@fqdn
.
It will be resolved to the corresponding principalservice/fqdn@REALM
by the GSS-API. To use the principal directly, use theservice_principal
option instead. -
service_principal
Principal of the service. -
ccname
(optionnal)
Location of the credential cache storing the initial ticket. If not specified, default path is taken.
Callback parameters:
-
err
Should beundefined
. Otherwise contains GSS API major error code. -
token
The SPNEGO token to access the service. It can then be added to the header of the HTTP requestAuthorization: Negociate {token}
.
kdestroy (options, callback)
: destroys credential cache
Options:
-
ccname
(optionnal)
Credential cache location. If this is not specified, default path is taken from environment variableKRB5CCNAME
, then from/etc/krb5.conf
.
Callback parameters:
-
err
Should beundefined
. Otherwise it contains an error message.
Run the tests
To run the tests in a container:
cd docker && ./run_tests $os
Available $os
: archlinux / ubuntu / centos7
To test this module locally, run the KDC and REST dockers, and use the corresponding krb5.conf (bcakup your own if you need it later):
cd docker
docker-compose up -d kerberos
docker-compose up -d rest
sudo mv /etc/krb5.conf /etc/krb5.conf.backup
sudo cp /tmp/krb5_test/krb5.conf /etc/krb5.conf
sudo npm test