GridGain Developers Hub
GitHub logo GridGain iso GridGain.com
GridGain Software Documentation

Authentication

GridGain Community Edition authentication mechanism is based on the Apache Ignite authentication feature, which is limited to simple password-based authentication and only works with thin client/JDBC/ODBC connections.

GridGain Enterprise and Ultimate editions provide a more advanced Authentication and Authorization feature, which can be configured for cluster nodes as well as thin clients/JDBC/ODBC/Web Console connections. For example, you can use different accounts for server nodes and client nodes and configure different sets of permissions for different clients.

Ignite Authentication

Ignite Authentication can be enabled by setting the authenticationEnabled property to true in the node’s configuration. This type of authentication requires persistent storage be enabled for at least one data region.

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <property name="dataStorageConfiguration">
        <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
            <property name="defaultDataRegionConfiguration">
                <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
                    <property name="persistenceEnabled" value="true"/>
                </bean>
            </property>
        </bean>
    </property>

   <property name="authenticationEnabled" value="true"/>

</bean>
IgniteConfiguration cfg = new IgniteConfiguration();

// Ignite persistence configuration.
DataStorageConfiguration storageCfg = new DataStorageConfiguration();

// Enabling the persistence.
storageCfg.getDefaultDataRegionConfiguration().setPersistenceEnabled(true);

// Applying settings.
cfg.setDataStorageConfiguration(storageCfg);

// Enable authentication
cfg.setAuthenticationEnabled(true);

Ignite ignite = Ignition.start(cfg);
This API is not presently available for C++. You can use XML configuration.

The first node that you start must have authentication enabled. Upon start-up, GridGain will create a user account with the name "ignite" and password "ignite". This account is meant to be used to create other user accounts for your needs. Then simply delete the "ignite" account.

Users can be managed using the following SQL commands:

GridGain Authentication

GridGain Authentication allows you to control access to the cluster for every entity, including server and client nodes, thin clients, JDBC/ODBC and REST API clients. The feature also enables you to manage what operations the entities are allowed to perform (authorization).

How to enable authentication:

  1. The first step is to configure an authenticator that will verify the credentials of any entity trying to connect to the cluster (such as server or client nodes, thin clients, Web Console, etc.).

    GridGain supports several ways to configure an authenticator:

  2. Specify the username and password (of one of the existing users) in every node that will connect to the cluster. This is done by using a security credentials provider.

  3. All applications that use thin clients, JDBC/ODBC, or REST API must provide user credentials as well.

Note that all server nodes must have the same authenticator configuration. GridGain will verify that all nodes use the same authenticator on the node start-up.

The following two sections explain how to configure the authenticator.

Passcode Authentication

The simplest way to configure authentication is to define the list of users in the node configuration. This approach consists in creating an access-control list with a set of credentials and the permissions attached to them.

In the following example, we define two users: 'server' and 'client'. The 'server' user is allowed to execute any operation. The 'client' user can only execute cache read operations. All server nodes will use the 'server' user credentials, and all client nodes will use the credentials of the 'client' user. Refer to the Authorization and Permissions for the full list of supported permissions.

<bean class="org.apache.ignite.plugin.security.SecurityCredentials" id="server.cred">
    <constructor-arg value="server"/>
    <constructor-arg value="password"/>
</bean>

<bean class="org.apache.ignite.plugin.security.SecurityCredentials" id="client.cred">
    <constructor-arg value="client"/>
    <constructor-arg value="password"/>
</bean>
<bean class="org.apache.ignite.configuration.IgniteConfiguration" >
    <property name="pluginConfigurations">
        <bean class="org.gridgain.grid.configuration.GridGainConfiguration">
            <property name="authenticator">
                <bean class="org.gridgain.grid.security.passcode.PasscodeAuthenticator">
                    <property name="aclProvider">
                        <bean class="org.gridgain.grid.security.passcode.AuthenticationAclBasicProvider">
                            <constructor-arg>
                                <map>
                                    <!-- server.cred credentials and associated permissions (everything is allowed) -->
                                    <entry key-ref="server.cred" value="{defaultAllow:true}"/>
                                    <!-- client.cred credentials and associated permissions (only cache reads are allowed) -->
                                    <entry key-ref="client.cred" value="{defaultAllow:false, {cache:'*',permissions:['CACHE_READ']}}"/>
                                </map>
                            </constructor-arg>
                        </bean>
                    </property>
                </bean>
            </property>

            <!-- Credentials for the current node. -->
            <property name="securityCredentialsProvider">
                <bean class="org.apache.ignite.plugin.security.SecurityCredentialsBasicProvider">
                    <constructor-arg ref="server.cred"/>
                </bean>
            </property>
        </bean>
    </property>
</bean>
// Create security credentials objects.
SecurityCredentials serverCreds = new SecurityCredentials("server", "password");
SecurityCredentials clientCreds = new SecurityCredentials("client", "password");

// GridGain plugin configuration.
GridGainConfiguration ggCfg = new GridGainConfiguration();

// we will use simple passcode authentication
PasscodeAuthenticator authenticator = new PasscodeAuthenticator();

// Create a map for the list of credentials and permissions.
Map<SecurityCredentials, String> authMap = new HashMap<>();

// Allow all operations on server nodes.
authMap.put(serverCreds, "{defaultAllow:true}");

// Allow only cache reads on client nodes.
authMap.put(clientCreds, "{defaultAllow:false, {cache:'*', permissions:['CACHE_READ']}}");

authenticator.setAclProvider(new AuthenticationAclBasicProvider(authMap));

ggCfg.setAuthenticator(authenticator);
ggCfg.setSecurityCredentialsProvider(new SecurityCredentialsBasicProvider(serverCreds));

IgniteConfiguration igniteCfg = new IgniteConfiguration();

igniteCfg.setPluginConfigurations(ggCfg);

Ignite ignite = Ignition.start(igniteCfg);
// Provide security credentials.
SecurityCredentials serverCreds = new SecurityCredentials()
{
    Login = "server",
    Password = "password"
};

SecurityCredentials clientCreds = new SecurityCredentials()
{
    Login = "client",
    Password = "password"
};

// Create dictionary for node and client with their security credentials and permissions.
IDictionary<SecurityCredentials, ISecurityPermissionSet> authDict = new Dictionary<SecurityCredentials, ISecurityPermissionSet>();

// Allow all operations on server nodes.
authDict.Add(serverCreds, new SecurityPermissionSet()
{
    DefaultAllowAll = true
});

// Allow only cache reads on client nodes.
IDictionary<string, ICollection<SecurityPermission>> clientPermissions = new Dictionary<string, ICollection<SecurityPermission>>();
clientPermissions.Add("*", new[]
{
    SecurityPermission.CacheRead
});

authDict.Add(clientCreds, new SecurityPermissionSet()
{
    DefaultAllowAll = false,
    CachePermissions = clientPermissions
});

// GridGain plugin configuration.
var cfg = new IgniteConfiguration
{
    PluginConfigurations = new[]
    {
        new GridGainPluginConfiguration()
        {
            Authenticator = new PasscodeAuthenticator()
            {
                AclProvider = new AuthenticationAclBasicProvider()
                {
                    Acl = authDict
                }
            }
        }
    }
};
This API is not presently available for C++. You can use XML configuration.

Here is the configuration of a client node:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <property name="clientMode" value="true"/>
    <property name="pluginConfigurations">
        <bean class="org.gridgain.grid.configuration.GridGainConfiguration">
            <property name="securityCredentialsProvider">
                <bean class="org.apache.ignite.plugin.security.SecurityCredentialsBasicProvider">
                    <!-- Specify credentials for the current node -->
                    <constructor-arg>
                        <bean class="org.apache.ignite.plugin.security.SecurityCredentials" id="client.cred">
                            <constructor-arg value="client"/>
                            <constructor-arg value="password"/>
                        </bean>
                    </constructor-arg>
                </bean>
            </property>
        </bean>
    </property>
</bean>
SecurityCredentials clientCreds = new SecurityCredentials("client", "password");

GridGainConfiguration ggCfg = new GridGainConfiguration();

ggCfg.setSecurityCredentialsProvider(new SecurityCredentialsBasicProvider(clientCreds));

IgniteConfiguration igniteCfg = new IgniteConfiguration().setPluginConfigurations(ggCfg);

Ignite ignite = Ignition.start(igniteCfg);
This API is not presently available for C++. You can use XML configuration.

Client Certificate Authentication

If SSL is enabled, you can grant permissions based on fields of the certificate provided by the clients. When a client connects to the cluster, its certificate is validated against a predefined list of predicates. Each predicate is associated with a list of permissions. If a predicate matches the client certificate, the client is granted the associated permissions. Predicates are defined in the form of regular expressions. If the client’s certificate does not match any predicate, the client is rejected.

For example, you can define a list of permissions that will be granted only if the client’s certificate subject contains "O=CustomerOrganization".

Certificate-based authentication is provided by the CertificateAuthenticator class.

In the following example, we configure SSL in the cluster and enable certificate-based client authentication. Please refer to the Authorization and Permissions for the full list of supported permissions.

<!-- This predicate will check X.509 certificate Subject DN against regular expression: -->
<bean class="org.gridgain.grid.security.certificate.SubjectRegexPredicate" id="user.predicate">
    <constructor-arg value=".*\bCN=[a-zA-Z0-9]*\b.*"/>
</bean>

<!-- This predicate will check X.509 certificate Issuer DN against different regular expression: -->
<bean class="org.gridgain.grid.security.certificate.IssuerRegexPredicate" id="devOps.predicate">
    <constructor-arg value="^OU=devOps\b"/>
</bean>
<bean class="org.apache.ignite.configuration.IgniteConfiguration" >
    <property name="pluginConfigurations">
        <bean class="org.gridgain.grid.configuration.GridGainConfiguration">
            <property name="authenticator">
                <bean class="org.gridgain.grid.security.certificate.CertificateAuthenticator">
                    <property name="permissionsJson">
                        <map>
                             <entry key-ref="user.predicate" value="{defaultAllow:false, {cache:'*',permissions:['CACHE_READ']}}"/>
                             <entry key-ref="devOps.predicate" value="{defaultAllow:true}"/>
                        </map>
                    </property>
                </bean>
            </property>
        </bean>
    </property>

    <!-- General SSL cetificate for inter-node authentication. -->
    <property name="sslContextFactory">
        <bean class="org.apache.ignite.ssl.SslContextFactory">
            <property name="keyStoreFilePath" value="keystore/node.jks"/>
            <property name="keyStorePassword" value="123456"/>
            <property name="trustStoreFilePath" value="keystore/trust.jks"/>
            <property name="trustStorePassword" value="123456"/>
         </bean>
    </property>

    <!-- Secure and enable client certificate checking for JDBC/ODBC clients. -->
    <property name="clientConnectorConfiguration">
        <bean class="org.apache.ignite.configuration.ClientConnectorConfiguration">
            <property name="sslEnabled" value="true"/>
            <property name="sslClientAuth" value="true"/>
        </bean>
    </property>

    <!-- Secure and enable client certificate validation for control.(sh,bat). -->
    <property name="connectorConfiguration">
        <bean class="org.apache.ignite.configuration.ConnectorConfiguration">
            <property name="sslEnabled" value="true"/>
            <property name="sslClientAuth" value="true"/>

            <!-- Secure and enable client certificate validation for HTTPS REST. -->
            <property name="jettyPath" value="jetty-ssl-client-auth.xml"/>
        </bean>
    </property>
</bean>

// We will use certificate authentication.
CertificateAuthenticator authenticator = new CertificateAuthenticator();

// Create a map for the list of credentials and permissions.
Map<IgnitePredicate<Certificate[]>, SecurityPermissionSet> authMap = new HashMap<>();

SecurityBasicPermissionSet permissions = new SecurityBasicPermissionSet();
permissions.setDefaultAllowAll(false);
permissions.setCachePermissions(new HashMap<String, Collection<SecurityPermission>>() {
    {
        put("*", Arrays.asList(SecurityPermission.CACHE_READ));
    }
});

// This predicate will check X.509 certificate Subject DN against a regular expression:
authMap.put(new SubjectRegexPredicate(".*\\bCN=[a-zA-Z0-9]*\\b.*"), permissions);

// This predicate will check X.509 certificate Issuer DN against a different regular expression:
authMap.put(new IssuerRegexPredicate("^OU=devOps\\b"), new AllowAllPermissionSet());

authenticator.setPermissions(authMap);

// GridGain plugin configuration.
GridGainConfiguration ggCfg = new GridGainConfiguration();
ggCfg.setAuthenticator(authenticator);

IgniteConfiguration igniteCfg = new IgniteConfiguration();

igniteCfg.setPluginConfigurations(ggCfg);

// General SSL certificate for inter-node authentication.
SslContextFactory factory = new SslContextFactory();
factory.setKeyStoreFilePath("keystore/node.jks");
factory.setKeyStorePassword("123456".toCharArray());
factory.setTrustStoreFilePath("keystore/trust.jks");
factory.setTrustStorePassword("123456".toCharArray());
igniteCfg.setSslContextFactory(factory);

// Secure and enable client certificate validation for JDBC/ODBC and thin clients.
ClientConnectorConfiguration clientConnectorCfg = new ClientConnectorConfiguration();
clientConnectorCfg.setSslEnabled(true);
clientConnectorCfg.setSslClientAuth(true);
igniteCfg.setClientConnectorConfiguration(clientConnectorCfg);

// Secure control.(sh,bat) connection and enable client certificate validation.
ConnectorConfiguration connectorCfg = new ConnectorConfiguration();
connectorCfg.setSslEnabled(true);
connectorCfg.setSslClientAuth(true);

// Secure REST and enable client certificate validation.
//connectorCfg.setJettyPath("jetty-ssl-client-auth.xml");

igniteCfg.setConnectorConfiguration(connectorCfg);

Ignite ignite = Ignition.start(igniteCfg);
This API is not presently available for .NET/C#. You can use XML configuration.
This API is not presently available for C++. You can use XML configuration.
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
    <New id="httpsCfg" class="org.eclipse.jetty.server.HttpConfiguration">
        <Set name="secureScheme">https</Set>
        <Set name="securePort"><SystemProperty name="IGNITE_JETTY_PORT" default="8443"/></Set>
        <Call name="addCustomizer">
            <Arg><New class="org.eclipse.jetty.server.SecureRequestCustomizer"/></Arg>
        </Call>
    </New>

    <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory$Server">
        <Set name="keyStorePath"><SystemProperty
                name="IGNITE_HOME" default="${IGNITE_HOME}"/>keystore/node.jks</Set>
        <Set name="keyStorePassword">123456</Set>
        <Set name="keyManagerPassword">123456</Set>
        <Set name="trustStorePath"><SystemProperty
                name="IGNITE_HOME" default="${IGNITE_HOME}"/>keystore/trust-both.jks</Set>
        <Set name="trustStorePassword">123456</Set>
        <!-- This setting is necessary for client certificate authentication: -->
        <Set name="needClientAuth">true</Set>
    </New>

    <Call name="addConnector">
        <Arg>
            <New class="org.eclipse.jetty.server.ServerConnector">
                <Arg name="server">
                    <Ref refid="Server"/>
                </Arg>
                <Arg name="factories">
                    <Array type="org.eclipse.jetty.server.ConnectionFactory">
                        <Item>
                            <New class="org.eclipse.jetty.server.SslConnectionFactory">
                                <Arg><Ref refid="sslContextFactory"/></Arg>
                                <Arg>http/1.1</Arg>
                            </New>
                        </Item>
                        <!-- This section is necessary for client certificate authentication: -->
                        <Item>
                            <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                                <Arg><Ref refid="httpsCfg"/></Arg>
                            </New>
                        </Item>
                    </Array>
                </Arg>
                <Set name="host"><SystemProperty name="IGNITE_JETTY_HOST" default="localhost"/></Set>
                <Set name="port"><SystemProperty name="IGNITE_JETTY_PORT" default="8443"/></Set>
            </New>
        </Arg>
    </Call>

    <Set name="handler">
        <New id="Handlers" class="org.eclipse.jetty.server.handler.HandlerCollection">
            <Set name="handlers">
                <Array type="org.eclipse.jetty.server.Handler">
                    <Item>
                        <New id="Contexts" class="org.eclipse.jetty.server.handler.ContextHandlerCollection"/>
                    </Item>
                </Array>
            </Set>
        </New>
    </Set>
</Configure>

Client configuration only requires enabling SSL with an appropriate certificate:

JAAS Authentication

The JAAS authenticator uses Java Authentication and Authorization Service login modules for user authentication. The configuration of the login module is specified via the -Djava.security.auth.login.config=/my/path/jaas.config system property. Refer to the JAAS Reference Guide for details.

To enable JAAS authentication, use the following configuration example:

<bean class="org.apache.ignite.plugin.security.SecurityCredentials" id="server.cred">
    <constructor-arg value="server"/>
    <constructor-arg value="password"/>
</bean>
<bean class="org.apache.ignite.configuration.IgniteConfiguration" >
    <property name="pluginConfigurations">
        <bean class="org.gridgain.grid.configuration.GridGainConfiguration">
            <property name="authenticator">
                <bean class="org.gridgain.grid.security.jaas.JaasAuthenticator"/>
            </property>

            <!-- Credentials for the current node. -->
            <property name="securityCredentialsProvider">
                <bean class="org.apache.ignite.plugin.security.SecurityCredentialsBasicProvider">
                    <constructor-arg ref="server.cred"/>
                </bean>
            </property>
        </bean>
    </property>
</bean>
GridGainConfiguration ggCfg = new GridGainConfiguration();

ggCfg.setAuthenticator(new JaasAuthenticator());

IgniteConfiguration igniteCfg = new IgniteConfiguration().setPluginConfigurations(ggCfg);

Ignite ignite = Ignition.start(igniteCfg);
This API is not presently available for .NET/C#. You can use XML configuration.
This API is not presently available for C++. You can use XML configuration.

JAAS authenticator can be used to configure LDAP-based authentication.

LDAP Authentication

To enable LDAP authentication, follow this procedure:

  1. Configure the JAAS authenticator as explained in JAAS Authentication section.

  2. Create a config file for the LdapLoginModule. Below is an example of such a file:

    jaas.config:
    GridJaasLoginContext {
        com.sun.security.auth.module.LdapLoginModule REQUIRED
        userProvider="ldap://serverName/ou=People,dc=nodomain"
        userFilter="uid={USERNAME}"
        authzIdentity="{<ATTR_NAME_OF_GRIDGAIN_PERMISSIONS>}"
        useSSL=false
        debug=false;
    };

    Here <ATTR_NAME_OF_GRIDGAIN_PERMISSIONS> is the attribute name of the user’s LDAP entry that contains GridGain permissions in a specific format. The following example defines a set of permissions for executing tasks and operations on caches. See Authorization and Permissions for the full list of available permissions.

    {
        {
            "cache":"partitioned",
            "permissions":["CACHE_PUT", "CACHE_REMOVE", "CACHE_READ"]
        },
        {
            "cache":"*",
            "permissions":["CACHE_READ"]
        },
        {
            "task":"org.mytasks.*",
            "permissions":["TASK_EXECUTE"]
        },
        "defaultAllow":"false"
    }
  3. Start all server nodes with the following system property:

    -Djava.security.auth.login.config=/my/path/jaas.config

    When started with this configuration file, a node will load the list of users and permissions from the provided LDAP server.

Supplying Credentials in Clients

When authentication is configured in the cluster, all client applications must provide user credentials. Refer to the following pages for the information about specific clients: