` claim.
Set the same endpoints, claim name, and permission mapping on every server node. Otherwise, the nodes do not start.
### OpenIdAuthenticator Properties
`OpenIdAuthenticator` supports the following properties:
| Property | Description | Default |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `userInfoUrl` | The UserInfo endpoint that returns the verified identity claims for the Control Center user's request. Set at least one of `userInfoUrl`, `jwkSetUrl`, or `wellKnownUrl`. | `N/A` |
| `jwkSetUrl` | The JWK set endpoint that publishes the keys used to validate the Control Center user's request. Set at least one of `userInfoUrl`, `jwkSetUrl`, or `wellKnownUrl`. | `N/A` |
| `wellKnownUrl` | The URL of the OpenID Connect provider metadata to take the JWK set endpoint and the expected token issuer. Set at least one of `userInfoUrl`, `jwkSetUrl`, or `wellKnownUrl`. | `N/A` |
| `issuer` | The expected token issuer. A token with a different `iss` claim is rejected. Set it only together with `jwkSetUrl`. | `N/A` |
| `audience` | The expected token audience. A token that is not issued for this audience is rejected. Applies to local validation only. | `N/A` |
| `jwsAlgorithms` | The accepted token signature algorithms. A token signed with any other algorithm is rejected. Applies to local validation only. | `RS256` |
| `jwkSetTimeout` | The connect and read timeout of the JWK set and provider metadata requests, in milliseconds. `0` means no timeout. | `5000` |
| `claimName` | The name of the claim that holds the role. | `gg-role` |
| `permissionsJson` | The mapping of a role name to permissions, in JSON form. This property is mandatory. Refer to the [Authorization and Permissions](/docs/gridgain/gridgain-8/security/authentication-and-authorization/authorization-permissions.md) for the full list of supported permissions. | `N/A` |
### Getting the Role from the UserInfo Endpoint
The example below sets up the cluster for working with [PingOne](https://admin.pingone.com/) OpenID Connect provider with `gg-role` set to `claimName`:
{% tabs %}
{% tab title="XML" %}
```xml
```
{% endtab %}
{% tab title="Java" %}
```java
// Set the passcode auth for the cluster.
GridPasscodeAuthenticator passcodeAuth = new GridPasscodeAuthenticator();
passcodeAuth.setAclProvider(new GridAuthenticationAclBasicProvider(
F.asMap(userCred1, jsonSpec1)));
// Set up OpenID authenticator for Control Center.
OpenIdAuthenticator openIdAuth = new OpenIdAuthenticator();
openIdAuth.setUserInfoUrl("https://auth.example.com/userinfo");
// Set claim name explicitly. If not specified, claim name is set to gg-role.
openIdAuth.setClaimName("my-role");
openIdAuth.setPermissionsJson(F.asMap(userCred2, jsonSpec2));
// Set up composite authenticator with passcode and OpenID authenticators.
CompositeAuthenticator auth = new CompositeAuthenticator();
auth.setAuthenticators(F.asList(passcodeAuth, openIdAuth));
// Override default authentication.
IgniteConfiguration igniteCfg = new IgniteConfiguration();
GridPluginConfiguration gCfg = new GridPluginConfiguration();
gCfg.setAuthenticator(auth);
igniteCfg.setPluginConfigurations(gCfg);
// Start GridGain.
Ignite ignite = Ignition.start(igniteCfg);
```
{% endtab %}
{% tab title=".NET/C#" %}
Not supported.
{% endtab %}
{% tab title="C++" %}
Not supported.
{% endtab %}
{% endtabs %}
### Validating Control Center user's requests by claim in access token
In the example below, the cluster validates the access token as a signed JWT instead of sending a UserInfo request. The JWK set endpoint and the expected issuer come from the provider metadata, and a token is accepted only if it is issued for the `gridgain-cluster` audience. Use this authenticator in place of the `OpenIdAuthenticator` bean of the previous example:
{% tabs %}
{% tab title="XML" %}
```xml
```
{% endtab %}
{% tab title="Java" %}
```java
OpenIdAuthenticator openIdAuth = new OpenIdAuthenticator();
// The JWK set endpoint and the expected issuer are taken from the provider metadata.
openIdAuth.setWellKnownUrl("https://auth.example.com/.well-known/openid-configuration");
openIdAuth.setAudience("gridgain-cluster");
openIdAuth.setPermissionsJson(F.asMap("admin", "{defaultAllow:true}"));
```
{% endtab %}
{% tab title=".NET/C#" %}
Not supported.
{% endtab %}
{% tab title="C++" %}
Not supported.
{% endtab %}
{% endtabs %}
To point the cluster at the JWK set endpoint directly, set `jwkSetUrl` instead of `wellKnownUrl`. In that case the `iss` claim of the token is not verified:
```xml
```
The signing keys are loaded on demand and cached, and they are kept for a while if the JWK set endpoint becomes unavailable, so a short outage of the identity provider does not block authentication.
Local validation checks the token signature, the expiration time, the audience when it is set, and the issuer. The token must also carry the `sub` and `exp` claims.
{% hint style="info" %}
Because the cluster does not call the identity provider on every authentication, a revoked token or a withdrawn role takes effect only after the token expires.
{% endhint %}
{% hint style="warning" %}
While `jwkSetUrl` or `wellKnownUrl` is set, server nodes that run a version without access token validation cannot join the cluster. Configure the authenticator the same way on all server nodes in the cluster after the upgrade.
{% endhint %}
## LDAP and AD Authentication
Permissions can be assigned from permission strings in LDAP or AD records, or by looking up a role defined in the server configuration. JAAS uses the `authzIdentity` configuration value as a query to look up the identity to assign an authenticated user. This identity may be interpreted as a role name or as a permission string. GridGain first searches the map in the `JaasBasicPermissionsProvider` constructor arguments for a key, and then assigns the permissions associated with that map key. If the role map lookup fails, GridGain defaults to using the `authzIdentity` result as a permission string for the authenticated user.
### Permissions Granted Directly from LDAP or AD
To enable LDAP authentication, follow this procedure:
1. Configure the JAAS authenticator as explained in [JAAS Authentication](#jaas-authentication) section.
2. Create a config file for the [LdapLoginModule](https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/LdapLoginModule.html). Below is an example of such a file:
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 `` is the attribute name of the user’s LDAP entry that contains GridGain permissions in a [specific format](/docs/gridgain/gridgain-8/security/authentication-and-authorization/authorization-permissions.md). The following example defines a set of permissions for executing tasks and operations on caches. See [Authorization and Permissions](/docs/gridgain/gridgain-8/security/authentication-and-authorization/authorization-permissions.md) for the full list of available permissions.
```json
{
{
"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:
```shell
-Djava.security.auth.login.config=/my/path/jaas.config
```
When started with this configuration file, the node loads the list of users and permissions from the provided LDAP server.
### Role-based Authentication with Active Directory
It is often required to authenticate GridGain users based on their AD role (i.e., the authentication/authorization group they belong to). Typical requirements for a GridGain cluster running within an Active Directory domain would be as follows:
* Every node or client application has to authenticate itself with the domain providing correct credentials of one of the user accounts.
* Access to the cluster has to be restricted based on groups; i.e., a user can be granted a certain set of permissions if and only if that user is a member of a specific group.
#### Active Directory Settings
1. Define requirements and create Active Directory groups and users to be used for access control. For example:
* Read-only users - can read from any cache in the cluster, but can't do updates
* Read-write users - can both read and update data in caches
* Superusers - have full access to all cluster functions.
2. Assign users to the groups.
On the cluster side, you need to separately configure JAAS and GridGain. The JAAS part defines how you interact with Active Directory. The GridGain part provides the actual permissions for the different groups and ties everything together.
#### Cluster Configuration - JAAS
GridGain assumes that every user has a special attribute in LDAP to store GridGain permissions as a JSON string (name of the attribute is provided to [JAAS](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jaas/JAASRefGuide.html) via the `authzIdentity` parameter). This does not work with the typical Active Directory structure. You want to assign permissions based on groups and roles rather than store them directly in LDAP.
Specify the `userFilter` parameter to search for the user entry that is included in a particular group. Filter conditions like `memberOf=GROUP_NAME` mimic the "contains" operation and return `true` if one of the items in the `memberOf` collection equals the provided name.
Apply the above approach to every group one-by-one. In JAAS terms, you create multiple login modules, one for each group. Here is the full configuration:
```json
GridJaasLoginContext {
com.sun.security.auth.module.LdapLoginModule SUFFICIENT
userProvider="ldap://18.218.245.71:389/CN=Users,DC=gridfoo,DC=com"
authIdentity="{USERNAME}@gridfoo.com"
userFilter="(&(sAMAccountName={USERNAME})(memberOf=CN=GG_CacheReadOnlyUsers,CN=Users,DC=gridfoo,DC=com))"
authzIdentity="GG_CacheReadOnlyUsers";
com.sun.security.auth.module.LdapLoginModule SUFFICIENT
userProvider="ldap://18.218.245.71:389/CN=Users,DC=gridfoo,DC=com"
authIdentity="{USERNAME}@gridfoo.com"
userFilter="(&(sAMAccountName={USERNAME})(memberOf=CN=GG_CacheReadWriteUsers,CN=Users,DC=gridfoo,DC=com))"
authzIdentity="GG_CacheReadWriteUsers";
com.sun.security.auth.module.LdapLoginModule SUFFICIENT
userProvider="ldap://18.218.245.71:389/CN=Users,DC=gridfoo,DC=com"
authIdentity="{USERNAME}@gridfoo.com"
userFilter="(&(sAMAccountName={USERNAME})(memberOf=CN=GG_MonitoringUsers,CN=Users,DC=gridfoo,DC=com))"
authzIdentity="GG_MonitoringUsers";
com.sun.security.auth.module.LdapLoginModule SUFFICIENT
userProvider="ldap://18.218.245.71:389/CN=Users,DC=gridfoo,DC=com"
authIdentity="{USERNAME}@gridfoo.com"
userFilter="(&(sAMAccountName={USERNAME})(memberOf=CN=GG_SuperUsers,CN=Users,DC=gridfoo,DC=com))"
authzIdentity="GG_SuperUsers";
};
```
The above defines four LDAP login modules, each marked as `SUFFICIENT`. This means that if at least one module is successful, the user is authenticated. Two common parameters are self-explanatory — `userProvider` and `authIdentity`. The `userFilter` and `authzIdentity` parameters are unique for every module, and are used to identify which group the user is part of (if any).
For every module, JAAS will go through the following process:
1. Connect to the LDAP server and authenticate with the provided username and password.
2. Use the `userFilter` search string to look for the user entry based on the username and the group name the current module is responsible for.
3. If the above user entry exists (i.e., the user is included in the group), create a principal with the name provided in the `authzIdentity` parameter, and stop the process with success.
4. If the above user entry can't be found, move on to the next module (or fail if there are no modules left).
As a result, a successfully authenticated user is created with a principal holding the group name. This name is then passed to GridGain's permissions provider.
{% hint style="info" %}
If you want to assign a user to multiple AD groups, convert all login modules in the above configuration from `SUFFICIENT` to `OPTIONAL`. This instructs JAAS to not stop after the first successful module, but rather continue going through the list and collect all authorization identities applicable to the user. GridGain then merges all the relevant permissions together and provides the expected user access behavior. This option is available starting from GridGain 8.7.8.
{% endhint %}
#### Cluster Configuration - GridGain
In the GridGain configuration, enable `JaasAuthenticator` and use the permission provider to specify the mapping between the possible group names and the corresponding permissions. For the latter, use `JaasBasicPermissionsProvider`, which GridGain includes out-of-the-box.
For the four groups created earlier, the XML configuration looks like this:
```xml
```
In the above configuration, you set [permissions](/docs/gridgain/gridgain-8/security/authentication-and-authorization/authorization-permissions.md#supported-permissions) for every group. For example, users included in GG\_CacheReadOnlyUsers will have access to all caches, but will only be able to read the data.
#### Example
A basic example that demonstrates role/group-based authentication for AD users.
GridGain server node configuration (`server.xml`):
```xml
127.0.0.1:47500..47509
```
GridGain client node configuration (`client.xml`):
```xml
127.0.0.1:47500..47509
```
JAAS configuration (`jaas.config`):
```json
GridJaasLoginContext {
com.sun.security.auth.module.LdapLoginModule SUFFICIENT
userProvider="ldap://3.15.156.212:389/CN=Users,DC=gridfoo,DC=com"
authIdentity="{USERNAME}@gridfoo.com"
userFilter="(&(sAMAccountName={USERNAME})(memberOf=CN=GG_CacheReadOnlyUsers,CN=Users,DC=gridfoo,DC=com))"
authzIdentity="GG_CacheReadOnlyUsers"
useSSL=false
debug=false;
com.sun.security.auth.module.LdapLoginModule SUFFICIENT
userProvider="ldap://3.15.156.212:389/CN=Users,DC=gridfoo,DC=com"
authIdentity="{USERNAME}@gridfoo.com"
userFilter="(&(sAMAccountName={USERNAME})(memberOf=CN=GG_CacheReadWriteUsers,CN=Users,DC=gridfoo,DC=com))"
authzIdentity="GG_CacheReadWriteUsers"
useSSL=false
debug=false;
com.sun.security.auth.module.LdapLoginModule SUFFICIENT
userProvider="ldap://3.15.156.212:389/CN=Users,DC=gridfoo,DC=com"
authIdentity="{USERNAME}@gridfoo.com"
userFilter="(&(sAMAccountName={USERNAME})(memberOf=CN=GG_MonitoringUsers,CN=Users,DC=gridfoo,DC=com))"
authzIdentity="GG_MonitoringUsers"
useSSL=false
debug=false;
com.sun.security.auth.module.LdapLoginModule SUFFICIENT
userProvider="ldap://3.15.156.212:389/CN=Users,DC=gridfoo,DC=com"
authIdentity="{USERNAME}@gridfoo.com"
userFilter="(&(sAMAccountName={USERNAME})(memberOf=CN=GG_SuperUsers,CN=Users,DC=gridfoo,DC=com))"
authzIdentity="GG_SuperUsers"
useSSL=false
debug=false;
};
```
The server application (`Server.java`):
```java
import org.apache.ignite.Ignite;
import org.apache.ignite.IgniteCache;
import org.apache.ignite.Ignition;
import org.apache.ignite.events.EventType;
import org.apache.ignite.plugin.security.SecuritySubject;
import org.gridgain.grid.GridGain;
public class Server {
public static void main(String[] args) {
Ignite ignite = Ignition.start("server.xml");
ignite.events().localListen(event -> {
System.out.println("Authenticated subjects:");
GridGain gg = ignite.plugin(GridGain.PLUGIN_NAME);
for (SecuritySubject subject : gg.security().authenticatedSubjects())
System.out.println(" " + subject.login() + ": " + subject.permissions());
return true;
},
EventType.EVT_NODE_JOINED);
IgniteCache cache = ignite.cache("TestCache");
for (int i = 0; i < 10; i++)
cache.put(i, i);
}
}
```
The above application uses a special user account called `GG_ServerAccount`, which is a member of the `GG_SuperUsers` group. This means that it has full access to all APIs and cluster functions. This is a general practice: although server nodes have to authenticate in the same way as clients, there is typically no need to put restrictions on them.
The client application (`Client.java`):
```java
import org.apache.ignite.Ignite;
import org.apache.ignite.IgniteCache;
import org.apache.ignite.Ignition;
public class Client {
public static void main(String[] args) {
try (Ignite ignite = Ignition.start("client.xml")) {
IgniteCache cache = ignite.cache("TestCache");
System.out.println("Cache value for key 5: " + cache.get(5));
cache.put(5, 100);
}
}
}
```
The above application authenticates with the read-only account, which is created at the very beginning. Therefore, this application is only able to read the data, but not update it. Indeed, when trying to execute a cache PUT operation, it fails with an authorization error:
```shell
org.apache.ignite.plugin.security.SecurityException: Authorization failed [perm=CACHE_PUT, name=TestCache, subject=SecuritySubjectAdapter [id=60c0c45e-69a1-498f-aa9d-5aeb1c78125d, subjType=REMOTE_NODE, addr=/0:0:0:0:0:0:0:1:0, permissions=SecurityBasicPermissionSet [cachePermissions=LinkedHashMap {*=ArrayList [CACHE_READ]}, taskPermissions=HashMap {}, servicePermissions=HashMap {}, systemPermissions=null, dfltAllowAll=false], login=user1]]
```
In addition, the server is configured to print out a list of currently authenticated users every time a new node joins the topology. This way, you can confirm that everything is configured correctly. Here is the output after both server and client nodes are up:
```shell
Authenticated subjects:
GG_ServerAccount: SecurityBasicPermissionSet [cachePermissions=HashMap {}, taskPermissions=HashMap {}, servicePermissions=HashMap {}, systemPermissions=null, dfltAllowAll=true]
user1: SecurityBasicPermissionSet [cachePermissions=LinkedHashMap {*=ArrayList [CACHE_READ]}, taskPermissions=HashMap {}, servicePermissions=HashMap {}, systemPermissions=null, dfltAllowAll=false]
```
The example above results in a user running under the server account with all the possible permissions — that is the server node. The second user is the client, which has the `CACHE_READ` permission only.
## 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:
* [Thin clients](/docs/connectors/gridgain-8/clients/getting-started-with-thin-clients.md#authentication)
* [JDBC driver](/docs/connectors/gridgain-8/sql/jdbc/jdbc-driver.md#parameters)
* [ODBC driver](/docs/connectors/gridgain-8/sql/odbc/connection-string-dsn.md#supported-arguments)
* [REST API](/docs/gridgain/gridgain-8/gridgain8-development/accessing-data/rest-api.md#security)