gssapi.js

GSSAPI Bindings for Node.js

gssapi.js is a Node.js binding for the GSSAPI API implemented by the [MIT Kerberos] library.

Installation

To build this module, you need the MIT Kerberos library installed.

If Kerberos is installed in a directory not automatically detected by the build system set KRB5_DIR in your environment to the directory path where MIT Kerberos is installed.

API

const gssapi = require('gssapi');

gssapi.createServerContext();
gssapi.createClientContext(options);
gssapi.initSecContext(client_context);
gssapi.initSecContext(client_context, token);
gssapi.acceptSecContext(server_context, token);
gssapi.setKeyTabPath(path);
gssapi.kinit(ccname, username, password);
gssapi.kdestroy(ccname);
gssapi.verifyCredentials(username, password, options)

##gssapi.createServerContext Creates a new server-side security context suitable for calling acceptSecContext

Returns a GssSecContext object with the properties:

• clientName() returns the name of the authenticating client
• isComplete() returns a boolean indicating whether the authentication process has completed

##gssapi.createClientContext Creates a new client-side security context suitable for calling initSecContext

• options - (Object) parameters to use in authentication
  • krbCcache - (string, optional): name of the Kerberos Credentials Cache to take credentials from
  • server - (string): the server principal name to authenticate against
  • mech - (string, optional): the mechanism to use. If specified, must be "spnego" or "krb5"

Returns a GssSecContext object with the property:

• isComplete() returns a boolean indicating whether the authentication process has completed

async gssapi.initSecContext

Initiates a GSS-API security context with a peer application.

• client_context: A GssSecContext generated by a call to createClientContext()
• token (Buffer, optional): a token generated by a prior call to acceptSecContext. Should be omitted in the first call to initSecContext

Returns a promise which resolves to a Buffer containing a token to be sent to the server, which should pass it into a call to acceptSecContext.

async gssapi.acceptSecContext

Accepts a security context initiated by a peer application

• server_context: A GssSecContext generated by a call to createServerContext()
• token (Buffer): a token generated by a prior call to initSecContext.

Returns a promise which resolves to a Buffer containing a token to be sent to the client, which should pass it into a call to initSecContext.

gssapi.setKeytabPath

Sets the default path to a Kerberos Keytab file for use in subsequent acceptSecContext calls

• path: Path to the Keytab file to use

async gssapi.kinit

Obtain a Kerberos ticket-granting ticket (TGT) and store it in a specified credentials cache. If a valid credentials cache already exists, this function is not necessary for GSSAPI authentication. It is provided for convenience if a credentials cache needs to be created.

• ccname (string): The credentials cache to use, in the format TYPE:NAME. See here for a description of available cache types
• principal (string): The user principal to obtain a ticket for
• password (string): The user's password

Returns a promise which resolves to the canonical principal name on success, or is rejected with an Error on failure.

async gssapi.kdestroy

Destroy a Kerberos credentials cache This function is not necessary for GSSAPI authentication. It is provided for convenience if a custom credentials cache is created and needs to be subsequently deleted

• ccname (string): The credentials cache to use, in the format TYPE:NAME. See here for a description of available cache types

Returns a promise which resolves to undefined on success, or is rejected with an Error on failure.

async gssapi.verifyCredentials

Authenticate a user's credentials using Kerberos. This function is not necessary for GSSAPI authentication, and is simply provided for convenience.

• principal (string): The user principal to verify
• password (string): The user's password
• options (object, optional): Additional optional parameters. Valid properties:
  • keytab: Keytab file to check the specified user against
  • serverPrincipal: the server principal name to find in the keytab. By default, any "host" principal is used.

Returns a promise which resolves to the canonical principal name if the user is successfully authenticated, or is rejected with an Error otherwise.

Usage

To authenticate, the client application should first create a security context, and then use it in a call to initSecContext:

const gssapi = require('gssapi');

gssapi.createClientContext({
    server: '[email protected]',
    krbCcache: 'FILE:myccache.krb5'
});
const token_to_server = await gssapi.initSecContext(client_context);

The generated token should be transferred to the server application, which likewise, creates its own security context for the authentication, and uses that to call acceptSecContext:

const gssapi = require('gssapi');

gssapi.createServerContext();
const token_to_client = await gssapi.acceptSecContext(server_context, token_from_client);

The generated token should be transferred back to the client application, which passes it into a second call to initSecContext:

const token_to_server = gssapi.initSecContext(client_context, token_from_server);

At each step, if a non-empty token is produced by initSecContext/acceptSecContext, it should be passed to the other application. If context.isComplete() is true, the authentication was successful and the application will not receive any more tokens and can discard the context object. The server application may call context.clientName() to get the name of the client that was authenticated.

If a Kerberos credentials cache does not already exist, kinit may be used to create it before the initial initSecContext call.