This tutorial introduces you to member security by setting up authentication for client connections.
Overview
In this tutorial, you’ll do the following:
-
Enable and configure authentication credentials for a Hazelcast Enterprise Edition member.
-
Configure and connect a client with the correct credentials.
-
Test connecting an unauthorized client to the member.
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.
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.
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. |
-
Create a
hazelcast.yaml
(orxml
) 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.
You can save the file in any directory as long as you update the command in step 2 to reference the correct location. |
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)
<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.
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:5.5.7
This command starts the member and configures it using the hazelcast.yaml
file defined above.
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:
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:
-
Create a new project in your preferred Python IDE
-
Run
pip install hazelcast-python-client
in the IDE’s terminal -
Create a Python file, e.g.,
myPyClient.py
containing the following code.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()
-
Run
python myPyClient.py
in the IDE or a new terminal window.
-
In a terminal, create a new directory and go into it.
-
Run
go mod init <name_of_the_directory>
. -
Run
go get github.com/hazelcast/hazelcast-go-client
. -
While in this directory, create a
go
file (e.g.main.go
) containing the following code: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) }
-
Run
go run main.go
in the terminal.
-
Install the Java client library.
-
In your preferred Java IDE, create a new project to include a class containing the following code:
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); } }
-
Run the
SecuredClient
class in the IDE.
-
Install the latest C Sharp client library
-
In your preferred C# IDE, create a new project to include a class containing the following code:
var username = "member1"; var password = "s3crEtPassword*"; var options = new HazelcastOptionsBuilder(); .With(o => { o.Authentication.ConfigureUsernamePasswordCredentials(username, password); }) .Build(); var client = await HazelcastClientFactory.StartNewClientAsync(options);
-
Run this class in the IDE.
-
Install the latest C++ client library
-
In your preferred C++ IDE, create a new project to include a class containing the following code.
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();
-
Run this class in the IDE.
-
Install the Node.js client library:
npm install hazelcast-client
-
In your preferred Node.js IDE, create a new project to include the following script.
const config = { security: { usernamePassword: { username: 'member1', password: 's3crEtPassword*' } } }; const client = await Client.newHazelcastClient(cfg);
-
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:
INFO:hazelcast.lifecycle:HazelcastClient 5.5.7 is STARTING
INFO:hazelcast.lifecycle:HazelcastClient 5.5.7 is STARTED
INFO:hazelcast.connection:Trying to connect to Address(host=127.0.0.1, port=5701)
INFO:hazelcast.lifecycle:HazelcastClient 5.5.7 is CONNECTED
INFO:hazelcast.connection:Authenticated with server Address(host=172.18.0.2, port=5701):63b2a2ce-85f6-413f-8ce9-6058a748e4b9, server version: 5.5.7, 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:
INFO:hazelcast.lifecycle:HazelcastClient 5.5.7 is STARTING
INFO:hazelcast.lifecycle:HazelcastClient 5.5.7 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:
-
Enable and configure authentication credentials for a Hazelcast Enterprise Edition member.
-
Configure and connect a client with the correct credentials.
-
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: