Authenticate client connections

This tutorial introduces you to member security by setting up authentication for client connections.

Overview

In this tutorial, you'll do the following:

1. Enable and configure authentication credentials for a Hazelcast Enterprise Edition member.
2. Configure and connect a client with the correct credentials.
3. Test connecting an unauthorized client to the member.

note

By default, members allow connections from any Hazelcast client. This means any client with access to a member can connect to the cluster and use its resources. To allow only authorized clients to connect to a member, you can configure authentication credentials on the members and clients.

The tutorial should take approximately 10 minutes to complete.

Prerequisites

Before you begin, ensure you have completed the following:

• Get started with Hazelcast Enterprise Edition

Step 1: Enable security on the member

Before a member can authenticate a client, you need to enable security on the member and define credentials.

tip

If you are comfortable using kubectl, you can create a Kubernetes secret to hold your license key rather than amending the provided code examples in this and other tutorials. For more information, see Deploy a Cluster with the Hazelcast Platform Operator for Kubernetes.

1. Create a hazelcast.yaml (or xml) configuration file using the following example as a template, replacing the <YOUR_LICENSE_KEY> placeholder with your Hazelcast Enterprise Edition license key, and save it in the ~/config directory on your local machine.

tip

You can save the file in any directory as long as you update the command in step 2 to reference the correct location.

YAML

yaml

hazelcast:
  cluster-name: hello-world
  license-key: <YOUR_LICENSE_KEY> (1)
  security:
    enabled: true
    realms:
      - name: passwordRealm (2)
        identity:
          username-password: (3)
            username: member1
            password: s3crEtPassword*
    member-authentication:
      realm: passwordRealm (4)

XML

xml

<hazelcast>
    <cluster-name>hello-world</cluster-name>
    <license-key><YOUR_LICENSE_KEY></license-key> (1)
    <security enabled="true">
        <realms>
            <realm name="passwordRealm"> (2)
                <identity>
                    <username-password username="member1" password="s3crEtPassword*" /> (3)
                </identity>
            </realm>
        </realms>
        <member-authentication realm="passwordRealm" /> (4)
    </security>
</hazelcast>

1 Replace the <YOUR_LICENSE_KEY> placeholder with your Hazelcast Enterprise Edition license key.

2 Define a security realm and set 'member-authentication' to use it.

3 Define a username and password combination here.

4 Ensure the security realm matches the realm defined with the username and password above.

With this configuration the member only accepts connections from clients with a username of member1 and a password of s3crEtPassword*.

Step 2: Start the member

Run the following command.

shell

docker run \
    -p 5701:5701 \
    -e JAVA_OPTS="-Dhazelcast.config=/opt/hazelcast/config_ext/hazelcast.yaml" -v ~/config:/opt/hazelcast/config_ext hazelcast/hazelcast-enterprise:6.0.0-SNAPSHOT

This command starts the member and configures it using the hazelcast.yaml file defined above.

note

This code example uses ~/config as the path to the directory containing the configuration file created in step 1. If you saved the configuration file somewhere else, you need to update this path.

When the member is running, you should see confirmation similar to the following:

shell

Members {size:1, ver:1} [
	Member [172.18.0.2]:5701 - cfc75512-a9c5-4798-bcca-450b7bf3c105 this
]

Step 3: Connect an authenticated client to the member

You can now use your preferred language client to create an authentication connection to the member:

Python

1. Create a new project in your preferred Python IDE

2. Run pip install hazelcast-python-client in the IDE's terminal

3. Create a Python file, e.g., myPyClient.py containing the following code.

   python

   import hazelcast
   import logging
   
   logging.basicConfig(level=logging.INFO)
   
   client = hazelcast.HazelcastClient(
       cluster_members=["127.0.0.1:5701"],
       cluster_name="hello-world",
       creds_username="member1",
       creds_password="s3crEtPassword*"
   )
   
   client.shutdown()

4. Run python myPyClient.py in the IDE or a new terminal window.

Go

1. In a terminal, create a new directory and go into it.

2. Run go mod init <name_of_the_directory>.

3. Run go get github.com/hazelcast/hazelcast-go-client.

4. While in this directory, create a go file (e.g. main.go) containing the following code:

   go

   package main
   
   import (
   	"context"
   
   	"github.com/hazelcast/hazelcast-go-client"
   )
   
   func main() {
   	ctx := context.TODO()
   	config := hazelcast.Config{}
   	cc := &config.Cluster
   	cc.Network.SetAddresses("127.0.0.1:5701")
   	cc.Name = "hello-world"
   	creds := &cc.Security.Credentials
   	creds.Username = "member1"
   	creds.Password = "s3crEtPassword*"
   	client, err := hazelcast.StartNewClientWithConfig(ctx, config)
   	if err != nil {
   		panic(err)
   	}
   	client.Shutdown(ctx)
   }

5. Run go run main.go in the terminal.

Java

1. Install the Java client library.

2. In your preferred Java IDE, create a new project to include a class containing the following code:

   java

   import com.hazelcast.client.HazelcastClient;
   import com.hazelcast.client.config.ClientConfig;
   
   public class SecuredClient {
     public static void main(String[] args) {
   
   ClientConfig clientConfig = new ClientConfig();
           clientConfig.setClusterName("hello-world");
           clientConfig.getSecurityConfig().setUsernamePasswordIdentityConfig("member1","s3crEtPassword*");
           HazelcastClient.newHazelcastClient(clientConfig);
   
     }
   }

3. Run the SecuredClient class in the IDE.

C Sharp

1. Install the latest C Sharp client library

2. In your preferred C# IDE, create a new project to include a class containing the following code:

   cs

   var username = "member1";
   var password = "s3crEtPassword*";
   
   var options = new HazelcastOptionsBuilder();
       .With(o => {
           o.Authentication.ConfigureUsernamePasswordCredentials(username, password);
       })
       .Build();
   
   var client = await HazelcastClientFactory.StartNewClientAsync(options);

3. Run this class in the IDE.

C++

1. Install the latest C++ client library

2. In your preferred C++ IDE, create a new project to include a class containing the following code.

   cpp

       hazelcast::client::client_config clientConfig;
   
       clientConfig.set_credentials(
               std::make_shared<hazelcast::client::security::username_password_credentials>("member1", "s3crEtPassword*"));
   
       clientConfig.set_cluster_name("hello-world");
   
       auto hz = hazelcast::new_client(std::move(clientConfig)).get();

3. Run this class in the IDE.

Node.js

1. Install the Node.js client library: npm install hazelcast-client

2. In your preferred Node.js IDE, create a new project to include the following script.

   javascript

   const config = {
       security: {
           usernamePassword: {
               username: 'member1',
               password: 's3crEtPassword*'
           }
       }
   };
   const client = await Client.newHazelcastClient(cfg);

3. Run this script in the IDE.

In the client terminal, you should see that the member has authenticated and accepted the client connection with confirmation similar to the following:

shell

INFO:hazelcast.lifecycle:HazelcastClient 6.0.0-SNAPSHOT is STARTING
INFO:hazelcast.lifecycle:HazelcastClient 6.0.0-SNAPSHOT is STARTED
INFO:hazelcast.connection:Trying to connect to Address(host=127.0.0.1, port=5701)
INFO:hazelcast.lifecycle:HazelcastClient 6.0.0-SNAPSHOT is CONNECTED
INFO:hazelcast.connection:Authenticated with server Address(host=172.18.0.2, port=5701):63b2a2ce-85f6-413f-8ce9-6058a748e4b9, server version: 6.0.0-SNAPSHOT, local address: Address(host=127.0.0.1, port=36006)
INFO:hazelcast.cluster:

Members [1] {
	Member 172.18.0.2:5701 - 63b2a2ce-85f6-413f-8ce9-6058a748e4b9
}

INFO:hazelcast.client:Client started

Step 3: Connect an unauthenticated client to the member

If you try to connect a client without any credentials or with incorrect credentials, the connection is refused by the member and you will see confirmation similar to the following:

shell

INFO:hazelcast.lifecycle:HazelcastClient 6.0.0-SNAPSHOT is STARTING
INFO:hazelcast.lifecycle:HazelcastClient 6.0.0-SNAPSHOT is STARTED
INFO:hazelcast.connection:Trying to connect to Address(host=127.0.0.1, port=5701)
INFO:hazelcast.connection:Connection(id=0, live=False, remote_address=None) closed. Reason: Failed to authenticate connection
WARNING:hazelcast.connection:Error during initial connection to Address(host=127.0.0.1, port=5701)

To test this, take a copy of the client code you created in step 3, change the password to make it incorrect and run the client.

Step 4: Clean up

To shut down the cluster, close the terminals in which the members are running or press Ctrl+C in each terminal.

Summary

In this tutorial, you learned how to:

1. Enable and configure authentication credentials for a Hazelcast Enterprise Edition member.
2. Configure and connect a client with the correct credentials.
3. Test connecting an unauthorized client to the member.

Next steps

If you're interested in learning more about the topics introduced in this tutorial, see Security Overview

To continue learning about Enterprise Edition features, see:

• Deploy blue-green clusters
• Replicate a map across clusters in a WAN