Authentication

With credentials

The immudb server runs on port 3322 as the default. The code examples below illustrate how to connect your client to the server and authenticate using default options and the default username and password. You can modify defaults on the immudb server in immudb.toml (opens new window) in the config folder.

package main

import (
	"context"
	"log"

	immudb "github.com/codenotary/immudb/pkg/client"
)

func main() {
	opts := immudb.DefaultOptions().
		WithAddress("localhost").
		WithPort(3322)

	client := immudb.NewClient().WithOptions(opts)
	err := client.OpenSession(
		context.TODO(),
		[]byte(`immudb`),
		[]byte(`immudb`),
		"defaultdb",
	)
	if err != nil {
		log.Fatal(err)
	}

	defer client.CloseSession(context.TODO())

	// do amazing stuff
}

from grpc import RpcError
from immudb import ImmudbClient

URL = "localhost:3322"  # immudb running on your machine
LOGIN = "immudb"        # Default username
PASSWORD = "immudb"     # Default password
DB = b"defaultdb"       # Default database name (must be in bytes)


def main():
    client = ImmudbClient(URL)
    # database parameter is optional
    client.login(LOGIN, PASSWORD, database=DB)
    client.logout()

    # Bad login
    try:
        client.login("verybadlogin", "verybadpassword")
    except RpcError as exception:
        print(exception.debug_error_string())
        print(exception.details())


if __name__ == "__main__":
    main()

Under the hood, during login, a token is being retrieved from the server, stored in memory and reused for subsequent operations.

The state is internally used for doing verified operations (such as verifiedSet or verifiedGet).

// Setting the "store" where the internal states are being persisted.
FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
            .withStatesFolder("immu_states")
            .build();

// Creating an new ImmuClient instance.
ImmuClient immuClient = ImmuClient.newBuilder()
            .withStateHolder(stateHolder)
            .withServerUrl("localhost")
            .withServerPort(3322)
            .build();

// Login with default credentials.
immuClient.login("immudb", "immudb");

The following code snippets show how to create a client.

Using default configuration:

    ImmuClient immuClient = ImmuClient.NewBuilder().Build();

    // or

    Immuclient immuClient = new ImmuClient();
    Immuclient immuClient = new ImmuClient("localhost", 3322);

Setting immudb url and port:

    ImmuClient immuClient = ImmuClient.NewBuilder()
                                .WithServerUrl("localhost")
                                .WithServerPort(3322)
                                .Build();

    ImmuClient immuClient = ImmuClient.NewBuilder()
                                .WithServerUrl("localhost")
                                .WithServerPort(3322)
                                .Build();

Customizing the State Holder:

    FileImmuStateHolder stateHolder = FileImmuStateHolder.NewBuilder()
                                        .WithStatesFolder("./my_immuapp_states")
                                        .Build();

    ImmuClient immuClient = ImmuClient.NewBuilder()
                                      .WithStateHolder(stateHolder)
                                      .Build();

Use Open and Close methods to initiate and terminate user sessions:

    await immuClient.Open("usr1", "pwd1", "defaultdb");

    // Interact with immudb using logged-in user.
    //...

    await immuClient.Close();

    // or one liner open the session right 
    client = await ImmuClient.NewBuilder().Open();

    //then close it
    await immuClient.Close();

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Node.js sdk github project (opens new window)

If you're using another development language, please refer to the immugw option.

With Mutual TLS

To enable mutual authentication, a certificate chain must be provided to both the server and client. That will cause each to authenticate with the other simultaneously. In order to generate certs, use the generate.sh (opens new window) tool from immudb repository. It generates a list of folders containing certificates and private keys to set up a mTLS connection.

./generate.sh localhost mysecretpassword

package main

import (
	"context"
	"log"

	immudb "github.com/codenotary/immudb/pkg/client"
)

func main() {
	// Folder containing MTLS certificates
	pathToMTLSFolder := "./mtls"

	opts := immudb.DefaultOptions().
		WithAddress("localhost").
		WithPort(3322).
		WithMTLs(true).
		WithMTLsOptions(
			immudb.MTLsOptions{}.
				WithCertificate(pathToMTLSFolder + "/4_client/certs/localhost.cert.pem").
				WithPkey(pathToMTLSFolder + "/4_client/private/localhost.key.pem").
				WithClientCAs(pathToMTLSFolder + "/2_intermediate/certs/ca-chain.cert.pem").
				WithServername("localhost"),
		)

	client := immudb.NewClient().WithOptions(opts)
	err := client.OpenSession(
		context.TODO(),
		[]byte(`immudb`),
		[]byte(`immudb`),
		"defaultdb",
	)
	if err != nil {
		log.Fatal(err)
	}

	defer client.CloseSession(context.TODO())

	// do amazing stuff
}

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Java sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .NET SDK github project (opens new window)

import ImmudbClient from 'immudb-node'
import Parameters from 'immudb-node/types/parameters'

const IMMUDB_HOST = '127.0.0.1'
const IMMUDB_PORT = '3322'
const IMMUDB_USER = 'immudb'
const IMMUDB_PWD = 'immudb'

const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });

(async () => {
 const loginReq: Parameters.Login = { user: IMMUDB_USER, password: IMMUDB_PWD }
 const loginRes = await cl.login(loginReq)
 console.log('success: login:', loginRes)
})()

If you're using another development language, please refer to the immugw option.

No Auth

You also have the option to run immudb with authentication disabled. This method is depreciated and not recommended.

A server configured with databases and user permissions can't be instantiated without authentication enabled. If a valid token is present, authentication is enabled by default.

$ ./immudb --auth=false

package main

import (
	"context"
	"log"

	immudb "github.com/codenotary/immudb/pkg/client"
)

func main() {
	client, err := immudb.NewImmuClient(
		immudb.DefaultOptions().
			WithAddress("localhost").
			WithPort(3322).
			WithAuth(false),
	)
	if err != nil {
		log.Fatal(err)
	}

	_, err = client.VerifiedSet(context.TODO(), []byte(`immudb`), []byte(`hello world`))
	if err != nil {
		log.Fatal(err)
	}
}

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
            .withStatesFolder("immu_states")
            .build();

ImmuClient immuClient = ImmuClient.newBuilder()
            .withStateHolder(stateHolder)
            .withServerUrl("localhost")
            .withServerPort(3322)
            .withAuth(false) // No authentication is needed.
            .build();
try {
    immuClient.set(key, val);
} catch (CorruptedDataException e) {
    // ...
}

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Node.js sdk github project (opens new window)

If you're using another development language, please refer to the immugw option.