Apache Solr agent

The Solr agent is an authorization plugin of the nodes: Solr asks it about every request, and it answers from the solr data service's signed policies. The distribution ships it as one Java 11 JAR, agents/solr/grantforge-agent-solr-<version>.jar, with its dependencies embedded and relocated.

The repository's Testcontainers integration tests run the JAR inside SolrCloud nodes of Solr 9.8.1, 9.10.1, 9.11.0 and 10.0.0. This does not certify every other release. The service plugin is described in Apache Solr.

How it works

• Requests are classified as Solr classifies them. Each request handler names the permission it needs, such as read or collection-admin-edit, as it does for Solr's own rule-based plugin; the agent turns that name into an access type, and a handler that names none is decided by the request's type.
• Every request to a collection is decided at its request path too. The agent decides a query of sales through /select at collection sales and at sales with path /select: a denial at either refuses it, so a policy can deny one handler of a collection.
• Teams administer their own collections. A Collections API request that names collections needs admin_collection on each of them, so a policy can let a team create, reload or delete only the collections whose name starts with its prefix.
• The cluster's administrators may do everything. admin on the cluster grants every request, as Solr's own all permission does.
• Policies can hold for some networks only. Every check carries the client's address; behind proxies the agent trusts, the client is the last address of X-Forwarded-For that no trusted proxy added.
• A JSON web token's verified roles count as groups. With Solr's JWT authentication, the roles the token's claim gives the user are groups of the decision, beside those GrantForge puts the user in.
• Refusals are logged with their reason. Solr answers a refused request with its own 403; the node's log names the GrantForge policy that denied it, or that none allows it.
• Decisions are kept and accesses folded. The decisions of the current snapshot are kept, by default 100,000 for 10 seconds, and a new snapshot starts afresh. Identical allowed accesses within a window, by default 10 seconds, are reported as one access event saying how many there were; refusals are reported one by one at once. Every event names the collection and path, or the cluster, and the client address.
• The nodes are not checked. Requests between the nodes, which Solr signs as the node itself, pass; a request without a user is asked to sign in.

Deployment

1. Add a solr data service and configure its policies, including admin on the cluster for Solr's administrators. Open Data permissions → Agents, select the service and issue an agent token. It is shown only once; store it in a file only Solr's account can read.

2. Copy the JAR into server/solr-webapp/webapp/WEB-INF/lib of every node, such as /opt/solr/server/solr-webapp/webapp/WEB-INF/lib, and restart the nodes one at a time.

3. Set the authorization section of the cluster's security.json, beside an authentication plugin, replacing the example address, paths and instance name:

   {
     "authentication": {
       "class": "solr.BasicAuthPlugin",
       "blockUnknown": true,
       "credentials": { "solr": "<salted SHA-256 hash> <salt>" }
     },
     "authorization": {
       "class": "org.devlive.grantforge.solr.agent.GrantForgeSolrAuthorizer",
       "grantforge.server.url": "https://grantforge.example.com",
       "grantforge.token.file": "/var/solr/data/grantforge.token",
       "grantforge.instance": "solr-cluster",
       "grantforge.cache.dir": "/var/solr/data/grantforge-cache"
     }
   }

   Upload it with bin/solr zk cp file:security.json zk:/security.json -z <zookeeper>; the nodes take it without a restart. Authentication must be enabled, so that requests have users.

4. On Solr 9, mind Java's security manager, which Solr enables by default: keep the token, the pinned key and the cache directory under SOLR_HOME, such as /var/solr/data, and grant the agent what it needs beyond Solr's own policy, in server/etc/security.policy or a policy file of your own that -Djava.security.properties adds as policy.url.3:

   grant {
     permission java.security.SecurityPermission "getProperty.org.devlive.grantforge.solr.agent.internal.bouncycastle.*";
   };

   Solr 10 runs without the security manager.

5. Move existing permissions first: the permissions and user roles of Solr's rule-based plugin no longer apply. Create matching policies beforehand. Until the agent has its first snapshot, requests other than those between the nodes are refused.

Users, groups and roles

Policies name the user Solr's authentication signs in, such as a basic authentication user or a JSON web token's principal. Groups are the roles a JSON web token verified for the user, together with the groups GrantForge puts the user in; roles are those GrantForge gives the user.

Decisions and limits

• Without a usable snapshot everything is refused but the requests between the nodes. A service that is not in use leaves Solr unchecked, as without an authorization plugin.
• A token bound to a service whose type is not solr refuses everything.
• A Collections API request that names its collections only in a JSON body, as some v2 API requests do, names none the agent can see, and needs admin on the cluster.
• Solr resolves aliases to their collections before it asks, so policies name collections, not aliases.
• Solr's /admin/authorization API cannot edit the agent's rules: GrantForge holds the policies.
• Client addresses are addresses and ranges only; a host name matches nothing.
• Decisions are kept for grantforge.decision.cache.ttl.ms, so a policy starts or stops applying up to that much later.

Related guides

• Apache Solr
• Data services, policies and agents