kerberos

README

xk6-kerberos

xk6-kerberos is an extension for k6. It adds support for the Kerberos authentication protocol to k6, enabling you to perform tests on environments secured with Kerberos.

import http from 'k6/http';
import kerberos from 'k6/x/kerberos';

// Open and read the Kerberos configuration file
const config = open("krb5.conf");

export default function () {
  // A UserClient can be used to authenticate a single user in a kerberos-secured environment.
  const client = new kerberos.UserClient(config, 'myusername', 'mypassword');

  // The authenticate method obtains a kerberos service ticket.
  const token = client.authenticate('http.example.com');

  // Perform an authenticated request to a kerberos-secured HTTP service.
  // Use the returned token to generate a SPNEGO compliant HTTP header to pass to HTTP services.
  http.get('https://test-api.k6.io', { Authorization: token.negotiateHeader(); });
}

Check the example section below for a extensive and complete implemention.

Getting started

Using the xk6-kerberos extension involves building a k6 binary incorporating it. A detailed guide on how to do this using a Docker or Go environment is available in the extension's documentation.

We list below the suggested steps:

Prepare the local environment

1. Make sure git and go are available commands.
2. Install xk6 as suggested in the local installation documentation's section.

Build the binary

1. Build a k6 binary incorporating the xk6-kerberos extension

xk6 build --with github.com/grafana/xk6-kerberos

1. Run a test script with the newly built binary

./k6 run script.js

Run a local version

Instead, use the following command after you've cloned the xk6-kerberos repository and moved inside the project's folder, if you want to use a local version of the extension:

xk6 build --with github.com/grafana/xk6-kerberos=.

Usage

Once built into a k6 executable using xk6, the extension can be imported by load test scripts as the k6/x/kerberos JavaScript module.

import kerberos from 'k6/x/kerberos';

UserClient

The module exports a UserClient type which can be used to authenticate a single user in a Kerberos-secured environment. Construct a UserClient instance by passing the Kerberos configuration and user credentials.

const client = new UserClient(config, username, password, realm)

The table below details the expected arguments:

Argument	Type	Required	Description
Configuration	ArrayBuffer	Yes	It contains the Kerberos configuration. Typically available in defined krb5.conf file.
Username	string	Yes	The user's username.
Password	string	Yes	The user's password.
Realm	string	No	Optional. If not defined, it uses the default realm from config.

An initialized client can then be used to get Kerberos service tickets.

const token = client.authenticate(service);

The returned token can be used to generate the expected SPNEGO HTTP header to pass to HTTP services.

const header = token.negotiateHeader();

It can be then used along the k6/http module to submit authenticated requests to an HTTP service.

import http from 'k6/http';

let headers = {Authorization: negotiateHeader};
http.get('http://test.k6.io', headers);

Example

In examples/krb5 a fully working testing environment and a simple example are available to demonstrate how to use the k6/x/kerberos module to authenticate against a Kerberos server and perform a request to a service protected by Kerberos authentication.

How to run

Docker Engine, or a compatible alternative, is required. Please make sure to have it installed before starting.

Run locally the Kerberos' testing environment.

$ docker compose -f ./examples/krb5/docker-compose.yml up -d

Build a new k6 binary incorporating the Kerberos extension.

$ docker run --rm -v $(pwd):/xk6 \
    grafana/xk6 build master \
    --with github.com/grafana/xk6-kerberos=.

Run the k6 test using the built binary.

docker run --rm -i \
  --network krb5_default \
  -v $(pwd)/k6:/usr/bin/k6 \
  -v $(pwd)/examples/krb5/krb5.conf:/home/k6/krb5.conf \
  -e KRB5_CONFIG=/home/k6/krb5.conf \
  grafana/k6:master run -<./examples/script.js

Support

To get help, report bugs and suggest features refer to k6 SUPPORT.md.

Contribute

If you want to contribute or help with the development of xk6-kerberos, start by reading k6 CONTRIBUTING.md. Before you start coding, it might be a good idea to discuss your plans and implementation details with the k6 maintainers—especially regarding big changes and features. You can do this in the GitHub issue for the problem you're solving (create one if it doesn't exist).

[!NOTE] To disclose security issues, refer to k6 SECURITY.md.

Development

The module is based on top of the gokrb5 library and its forked version grafana/gokrb5.

Documentation

Overview

Package kerberos provides a JavaScript module for Kerberos authentication.

Index

• type Client
  • func (c *Client) Authenticate(spn string) (Token, error)
• type ModuleInstance
  • func (mi *ModuleInstance) Exports() modules.Exports
• type RootModule
  • func New() *RootModule
  • func (*RootModule) NewModuleInstance(vu modules.VU) modules.Instance
• type Token
  • func (t Token) NegotiateHeader() string

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the main object exposed on the JavaScript API. It's a wrapper that holds a Kerberos configuration and a Kerberos client. It exposes the main [Authenticate] method for Kerberos authentication.

func (*Client) Authenticate

func (c *Client) Authenticate(spn string) (Token, error)

Authenticate uses Client credentials to acquire a ticket-granting ticket, if needed, and then uses that one to acquire a service ticket for the given Service Principal Name (SPN).

type ModuleInstance

type ModuleInstance struct {
	// contains filtered or unexported fields
}

ModuleInstance represents an instance of the JS module.

func (*ModuleInstance) Exports

func (mi *ModuleInstance) Exports() modules.Exports

Exports implements the modules.Instance interface and returns the exports of the JS module.

type RootModule

type RootModule struct{}

RootModule is the global module instance that will create module instances for each VU.

func New

func New() *RootModule

New returns a pointer to a new RootModule instance.

func (*RootModule) NewModuleInstance

func (*RootModule) NewModuleInstance(vu modules.VU) modules.Instance

NewModuleInstance implements the modules.Module interface returning a new instance for each VU.

type Token

type Token string

Token is a base64-encoded token that holds a Kerberos service ticket.

func (Token) NegotiateHeader

func (t Token) NegotiateHeader() string

NegotiateHeader returns the token in a format that can be used in the Authentication header of an HTTP request against a service using Kerberos authentication.