Skip to content
immudb docker run -d --net host -it --name immudb codenotary/immudb:latest

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 in the config folder.

Go

 1package main
 2
 3import (
 4	"context"
 5	"log"
 6
 7	immudb "github.com/codenotary/immudb/pkg/client"
 8)
 9
10func main() {
11	opts := immudb.DefaultOptions().
12		WithAddress("localhost").
13		WithPort(3322)
14
15	client := immudb.NewClient().WithOptions(opts)
16	err := client.OpenSession(
17		context.TODO(),
18		[]byte(`immudb`),
19		[]byte(`immudb`),
20		"defaultdb",
21	)
22	if err != nil {
23		log.Fatal(err)
24	}
25
26	defer client.CloseSession(context.TODO())
27
28	// do amazing stuff
29}

Python

 1from grpc import RpcError
 2from immudb import ImmudbClient
 3
 4URL = "localhost:3322"  # immudb running on your machine
 5LOGIN = "immudb"        # Default username
 6PASSWORD = "immudb"     # Default password
 7DB = b"defaultdb"       # Default database name (must be in bytes)
 8
 9def main():
10    client = ImmudbClient(URL)
11    # database parameter is optional
12    client.login(LOGIN, PASSWORD, database=DB)
13    client.logout()
14
15    # Bad login
16    try:
17        client.login("verybadlogin", "verybadpassword")
18    except RpcError as exception:
19        print(exception.debug_error_string())
20        print(exception.details())
21
22if __name__ == "__main__":
23    main()

Java

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).

 1// Setting the "store" where the internal states are being persisted.
 2FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
 3            .withStatesFolder("immu_states")
 4            .build();
 5
 6// Creating an new ImmuClient instance.
 7ImmuClient immuClient = ImmuClient.newBuilder()
 8            .withStateHolder(stateHolder)
 9            .withServerUrl("localhost")
10            .withServerPort(3322)
11            .build();
12
13// Login with default credentials.
14immuClient.login("immudb", "immudb");

.NET

The following code snippets show how to create a client.

Using default configuration:

1    ImmuClient immuClient = ImmuClient.NewBuilder().Build();
2
3    // or
4
5    Immuclient immuClient = new ImmuClient();
6    Immuclient immuClient = new ImmuClient("localhost", 3322);

Setting immudb url and port:

1    ImmuClient immuClient = ImmuClient.NewBuilder()
2                                .WithServerUrl("localhost")
3                                .WithServerPort(3322)
4                                .Build();
5
6    ImmuClient immuClient = ImmuClient.NewBuilder()
7                                .WithServerUrl("localhost")
8                                .WithServerPort(3322)
9                                .Build();

Customizing the State Holder:

1    FileImmuStateHolder stateHolder = FileImmuStateHolder.NewBuilder()
2                                        .WithStatesFolder("./my_immuapp_states")
3                                        .Build();
4
5    ImmuClient immuClient = ImmuClient.NewBuilder()
6                                      .WithStateHolder(stateHolder)
7                                      .Build();

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

 1    await immuClient.Open("usr1", "pwd1", "defaultdb");
 2
 3    // Interact with immudb using logged-in user.
 4    //...
 5
 6    await immuClient.Close();
 7
 8    // or one liner open the session right 
 9    client = await ImmuClient.NewBuilder().Open();
10
11    //then close it
12    await immuClient.Close();

Node.js

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

Others

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 tool from immudb repository. It generates a list of folders containing certificates and private keys to set up a mTLS connection.

1./generate.sh localhost mysecretpassword

Go

 1package main
 2
 3import (
 4	"context"
 5	"log"
 6
 7	immudb "github.com/codenotary/immudb/pkg/client"
 8)
 9
10func main() {
11	// Folder containing MTLS certificates
12	pathToMTLSFolder := "./mtls"
13
14	opts := immudb.DefaultOptions().
15		WithAddress("localhost").
16		WithPort(3322).
17		WithMTLs(true).
18		WithMTLsOptions(
19			immudb.MTLsOptions{}.
20				WithCertificate(pathToMTLSFolder + "/4_client/certs/localhost.cert.pem").
21				WithPkey(pathToMTLSFolder + "/4_client/private/localhost.key.pem").
22				WithClientCAs(pathToMTLSFolder + "/2_intermediate/certs/ca-chain.cert.pem").
23				WithServername("localhost"),
24		)
25
26	client := immudb.NewClient().WithOptions(opts)
27	err := client.OpenSession(
28		context.TODO(),
29		[]byte(`immudb`),
30		[]byte(`immudb`),
31		"defaultdb",
32	)
33	if err != nil {
34		log.Fatal(err)
35	}
36
37	defer client.CloseSession(context.TODO())
38
39	// do amazing stuff
40}

Python

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

Java

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

.NET

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

Node.js

 1import ImmudbClient from 'immudb-node'
 2import Parameters from 'immudb-node/types/parameters'
 3
 4const IMMUDB_HOST = '127.0.0.1'
 5const IMMUDB_PORT = '3322'
 6const IMMUDB_USER = 'immudb'
 7const IMMUDB_PWD = 'immudb'
 8
 9const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
10
11(async () => {
12 const loginReq: Parameters.Login = { user: IMMUDB_USER, password: IMMUDB_PWD }
13 const loginRes = await cl.login(loginReq)
14 console.log('success: login:', loginRes)
15})()

Others

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.

1$ ./immudb --auth=false

Go

 1package main
 2
 3import (
 4	"context"
 5	"log"
 6
 7	immudb "github.com/codenotary/immudb/pkg/client"
 8)
 9
10func main() {
11	client, err := immudb.NewImmuClient(
12		immudb.DefaultOptions().
13			WithAddress("localhost").
14			WithPort(3322).
15			WithAuth(false),
16	)
17	if err != nil {
18		log.Fatal(err)
19	}
20
21	_, err = client.VerifiedSet(context.TODO(), []byte(`immudb`), []byte(`hello world`))
22	if err != nil {
23		log.Fatal(err)
24	}
25}

Python

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

Java

 1FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
 2            .withStatesFolder("immu_states")
 3            .build();
 4
 5ImmuClient immuClient = ImmuClient.newBuilder()
 6            .withStateHolder(stateHolder)
 7            .withServerUrl("localhost")
 8            .withServerPort(3322)
 9            .withAuth(false) // No authentication is needed.
10            .build();
11try {
12    immuClient.set(key, val);
13} catch (CorruptedDataException e) {
14    // ...
15}

Node.js

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

Others

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

Edit this page on GitHub Last updated