Chapter 3. Security Realms

Security realms define identity, encryption, authentication, and authorization configuration for Data Grid Server endpoints.

3.1. Property Realms

Property realms use property files to define users and groups.

users.properties maps usernames to passwords in plain-text format. Passwords can also be pre-digested if you use the DIGEST-MD5 SASL mechanism or Digest HTTP mechanism. 

myuser=a_password
user2=another_password

groups.properties maps users to roles. 

myuser=supervisor,reader,writer
user2=supervisor

Endpoint authentication mechanisms

When you configure Data Grid Server to use a property realm, you can configure endpoints to use the following authentication mechanisms:

  • Hot Rod (SASL): PLAIN, DIGEST-*, and SCRAM-*
  • REST (HTTP): Basic and Digest

Property realm configuration

<security xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="urn:infinispan:server:12.1 https://infinispan.org/schemas/infinispan-server-12.1.xsd"
          xmlns="urn:infinispan:server:12.1">
   <security-realms>
      <security-realm name="default">
         <!-- Defines groups as roles for server authorization. -->
         <properties-realm groups-attribute="Roles">
            <!-- Specifies the properties file that holds usernames and passwords. -->
            <!-- The plain-text="true" attribute stores passwords in plain text. -->
            <user-properties path="users.properties"
                             relative-to="infinispan.server.config.path"
                             plain-text="true"/>
            <!-- Specifies the properties file that defines roles for users. -->
            <group-properties path="groups.properties"
                              relative-to="infinispan.server.config.path"/>
         </properties-realm>
      </security-realm>
   </security-realms>
</security>

3.1.1. Creating and Modifying Users

Add Data Grid user credentials and assign permissions to control access to data.

Data Grid server installations use a property realm to authenticate users for the Hot Rod and REST endpoints. This means you need to create at least one user before you can access Data Grid.

By default, users also need roles with permissions to access caches and interact with Data Grid resources. You can assign roles to users individually or add users to groups that have role permissions.

You create users and assign roles with the user command in the Data Grid command line interface (CLI).

Tip

Run help user from a CLI session to get complete command details.

3.1.1.1. Adding Credentials

You need an admin user for the Data Grid Console and full control over your Data Grid environment. For this reason you should create a user with admin permissions the first time you add credentials.

Procedure

  1. Open a terminal in $RHDG_HOME.

  2. Create an admin user with the user create command in the CLI. 

    $ bin/cli.sh user create myuser -p changeme -g admin

    Alternatively, the username "admin" automatically gets admin permissions. 

    $ bin/cli.sh user create admin -p changeme

  3. Open user.properties and groups.properties with any text editor to verify users and groups. 

    $ cat server/conf/users.properties

#$REALM_NAME=default$
#$ALGORITHM=encrypted$
myuser=scram-sha-1\:BYGcIAwvf6b...

$ cat server/conf/groups.properties

myuser=admin

3.1.1.2. Assigning Roles to Users

Assign roles to users so they have the correct permissions to access data and modify Data Grid resources.

Procedure

  1. Start a CLI session with an admin user. 

    $ bin/cli.sh

  2. Assign the deployer role to "katie". 

    [//containers/default]> user roles grant --roles=deployer katie

  3. List roles for "katie". 

    [//containers/default]> user roles ls katie
["deployer"]

3.1.1.3. Adding Users to Groups

Groups let you change permissions for multiple users. You assign a role to a group and then add users to that group. Users inherit permissions from the group role.

Procedure

  1. Start a CLI session with an admin user.

  2. Use the user create command to create a group.

    1. Specify "developers" as the group name with the --groups argument.

    2. Set a username and password for the group.

      In a property realm, a group is a special type of user that also requires a username and password. 

      [//containers/default]> user create --groups=developers developers -p changeme

  3. List groups. 

    [//containers/default]> user ls --groups
["developers"]

  4. Assign the application role to the "developers" group. 

    [//containers/default]> user roles grant --roles=application developers

  5. List roles for the "developers" group. 

    [//containers/default]> user roles ls developers
["application"]

  6. Add existing users, one at a time, to the group as required. 

    [//containers/default]> user groups john --groups=developers

3.2. LDAP Realms

LDAP realms connect to LDAP servers, such as OpenLDAP, Red Hat Directory Server, Apache Directory Server, or Microsoft Active Directory, to authenticate users and obtain membership information.

Note

LDAP servers can have different entry layouts, depending on the type of server and deployment. It is beyond the scope of this document to provide examples for all possible configurations.

Endpoint authentication mechanisms

When you configure Data Grid Server to use an LDAP realm, you can configure endpoints to use the following authentication mechanisms:

  • Hot Rod (SASL): PLAIN, DIGEST-*, and SCRAM-*
  • REST (HTTP): Basic and Digest

LDAP realm configuration

<security xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="urn:infinispan:server:12.1 https://infinispan.org/schemas/infinispan-server-12.1.xsd"
          xmlns="urn:infinispan:server:12.1">
   <security-realms>
      <security-realm name="default">
        <!-- Names an LDAP realm and specifies connection properties. -->
        <ldap-realm name="ldap"
                    url="ldap://my-ldap-server:10389"
                    principal="uid=admin,ou=People,dc=infinispan,dc=org"
                    credential="strongPassword"
                    connection-timeout="3000"
                    read-timeout="30000"
                    connection-pooling="true"
                    referral-mode="ignore"
                    page-size="30"
                    direct-verification="true">
            <!-- Defines how principals are mapped to LDAP entries. -->
            <identity-mapping rdn-identifier="uid"
                              search-dn="ou=People,dc=infinispan,dc=org"
                              search-recursive="false">
               <!-- Retrieves all the groups of which the user is a member. -->
               <attribute-mapping>
                  <attribute from="cn"
                             to="Roles"
                             filter="(&amp;(objectClass=groupOfNames)(member={1}))"
                             filter-dn="ou=Roles,dc=infinispan,dc=org"/>
               </attribute-mapping>
            </identity-mapping>
         </ldap-realm>
      </security-realm>
   </security-realms>
</security>

Important

The principal for LDAP connections must have necessary privileges to perform LDAP queries and access specific attributes.

As an alternative to verifying user credentials with the direct-verification attribute, you can specify an LDAP password with the user-password-mapper element.

The rdn-identifier attribute specifies an LDAP attribute that finds the user entry based on a provided identifier, which is typically a username; for example, the uid or sAMAccountName attribute. Add search-recursive="true" to the configuration to search the directory recursively. By default, the search for the user entry uses the (rdn_identifier={0}) filter. Specify a different filter with the filter-name attribute.

The attribute-mapping element retrieves all the groups of which the user is a member. There are typically two ways in which membership information is stored:

  • Under group entries that usually have class groupOfNames in the member attribute. In this case, you can use an attribute filter as in the preceding example configuration. This filter searches for entries that match the supplied filter, which locates groups with a member attribute equal to the user’s DN. The filter then extracts the group entry’s CN as specified by from, and adds it to the user’s Roles.

  • In the user entry in the memberOf attribute. In this case you should use an attribute reference such as the following:

    <attribute-reference reference="memberOf" from="cn" to="Roles" />

    This reference gets all memberOf attributes from the user’s entry, extracts the CN as specified by from, and adds them to the user’s Roles.

3.2.1. LDAP Realm Principal Rewriting

Some SASL authentication mechanisms, such as GSSAPI, GS2-KRB5 and Negotiate, supply a username that needs to be cleaned up before you can use it to search LDAP servers. 

<security xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="urn:infinispan:server:12.1 https://infinispan.org/schemas/infinispan-server-12.1.xsd"
          xmlns="urn:infinispan:server:12.1">
   <security-realms>
      <security-realm name="default">
         <ldap-realm name="ldap"
                     url="ldap://${org.infinispan.test.host.address}:10389"
                     principal="uid=admin,ou=People,dc=infinispan,dc=org"
                     credential="strongPassword">
            <name-rewriter>
               <!-- Defines a rewriter that extracts the username from the principal using a regular expression. -->
               <regex-principal-transformer name="domain-remover"
                                            pattern="(.*)@INFINISPAN\.ORG"
                                            replacement="$1"/>
            </name-rewriter>
            <identity-mapping rdn-identifier="uid"
                              search-dn="ou=People,dc=infinispan,dc=org">
               <attribute-mapping>
                  <attribute from="cn" to="Roles"
                             filter="(&amp;(objectClass=groupOfNames)(member={1}))"
                             filter-dn="ou=Roles,dc=infinispan,dc=org" />
               </attribute-mapping>
               <user-password-mapper from="userPassword" />
            </identity-mapping>
         </ldap-realm>
      </security-realm>
   </security-realms>
</security>

3.3. Token Realms

Token realms use external services to validate tokens and require providers that are compatible with RFC-7662 (OAuth2 Token Introspection), such as Red Hat SSO.

Endpoint authentication mechanisms

When you configure Data Grid Server to use a token realm, you must configure endpoints to use the following authentication mechanisms:

  • Hot Rod (SASL): OAUTHBEARER
  • REST (HTTP): Bearer

Token realm configuration

<security xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="urn:infinispan:server:12.1 https://infinispan.org/schemas/infinispan-server-12.1.xsd"
          xmlns="urn:infinispan:server:12.1">
   <security-realms>
      <security-realm name="default">
         <!-- Specifies the URL of the authentication server. -->
         <token-realm name="token"
                      auth-server-url="https://oauth-server/auth/">
            <!-- Specifies the URL of the token introspection endpoint. -->
            <oauth2-introspection
                    introspection-url="https://oauth-server/auth/realms/infinispan/protocol/openid-connect/token/introspect"
                    client-id="infinispan-server"
                    client-secret="1fdca4ec-c416-47e0-867a-3d471af7050f"/>
         </token-realm>
      </security-realm>
   </security-realms>
</security>

3.4. Trust Store Realms

Trust store realms use certificates, or certificates chains, that verify Data Grid Server and client identities when they negotiate connections.

Keystores
Contain server certificates that provide a Data Grid Server identity to clients. If you configure a keystore with server certificates, Data Grid Server encrypts traffic using industry standard SSL/TLS protocols.
Trust stores
Contain client certificates, or certificate chains, that clients present to Data Grid Server. Client trust stores are optional and allow Data Grid Server to perform client certificate authentication.

Client certificate authentication

You must add the require-ssl-client-auth="true" attribute to the endpoint configuration if you want Data Grid Server to validate or authenticate client certificates.

Endpoint authentication mechanisms

If you configure Data Grid Server with a keystore only, you can use encryption in combination with any authentication mechanism.

When you configure Data Grid Server to use a client trust store, you must configure endpoints to use the following authentication mechanisms:

  • Hot Rod (SASL): EXTERNAL
  • REST (HTTP): CLIENT_CERT

Trust store realm configuration

<security xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="urn:infinispan:server:12.1 https://infinispan.org/schemas/infinispan-server-12.1.xsd"
          xmlns="urn:infinispan:server:12.1">
   <security-realms>
      <security-realm name="default">
         <server-identities>
            <ssl>
               <!-- Provides an SSL/TLS identity with a keystore that
                    contains server certificates. -->
               <keystore path="server.p12"
                         relative-to="infinispan.server.config.path"
                         keystore-password="secret"
                         alias="server"/>
               <!-- Configures a trust store that contains client certificates
                    or part of a certificate chain. -->
               <truststore path="trust.p12"
                           relative-to="infinispan.server.config.path"
                           password="secret"/>
            </ssl>
         </server-identities>
         <!-- Authenticates client certificates against the trust store.
              If you configure this, the trust store must contain
              the public certificates for all clients. -->
         <truststore-realm/>
      </security-realm>
   </security-realms>
</security>
<!-- Configures Data Grid Server to require client certificates
     with the "require-ssl-client-auth" attribute. -->
<endpoints xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="urn:infinispan:server:12.1 https://infinispan.org/schemas/infinispan-server-12.1.xsd"
           xmlns="urn:infinispan:server:12.1"
           socket-binding="default"
           security-realm="default"
           require-ssl-client-auth="true">
   <hotrod-connector>
     <!-- Configures the Hot Rod endpoint for client certificate authentication. -->
     <authentication>
       <sasl mechanisms="EXTERNAL"
             server-name="infinispan"
             qop="auth"/>
     </authentication>
   </hotrod-connector>
   <rest-connector>
      <!-- Configures the REST endpoint for client certificate authentication. -->
      <authentication mechanisms="CLIENT_CERT"/>
   </rest-connector>
</endpoints>