This feature is introduced as an added layer of security on top of existing TransportLayer authorization framework. In order to leverage these feature some core changes need to be made at Route registration level. This document talks about how you can achieve this.

**NOTE:** This doesn't replace Transport Layer Authorization. Plugin developers may choose to skip creating transport actions for APIs that do not need interaction with the Transport Layer.

The security plugin must be installed and operational in your OpenSearch cluster for this feature to work.

Once the routes are defined as NamedRoute, they, along-with their handlers, will be registered the same way as Route objects. When a request comes in, `SecurityRestFilter.java` applies an authorization check which extracts information about the NamedRoute.

Next we get the unique name and actionNames associated with that route and evaluate these against existing `cluster_permissions` across all roles of the requesting user. If the authorization check succeeds, the request chain proceeds as normal. If it fails, a 401 response is returned to the user.

NOTE:

1. The action names defined in roles must exactly match the names of registered routes, or else, the request would be deemed unauthorized.

2. This check will not be implemented for plugins who do not use NamedRoutes.

Here is a sample of an existing route converted to a named route:

Before:

With new scheme:

`actionNames()` are optional. They correspond to any current actions defined as permissions in roles.

Ensure that these name-to-route mappings are easily accessible to the cluster admins to allow granting access to these APIs.

We will continue on the above example of translating `/uri` from Route to NamedRoute.

Consider these roles are defined in the cluster:

plugin_role:

reserved: true

cluster_permissions:

- 'plugin:uri'

plugin_role_legacy:

reserved: true

cluster_permissions:

- 'cluster:admin/opensearch/plugin/uri'

Unsuccessful authz scenarios for a user:

2. The user is mapped to a different role which doesn't grant the cluster permissions: `plugin:uri` OR `cluster:admin/opensearch/plugin/uri`/

As part of this effort a new uri `GET /whoamiprotected` was introduced as a NamedRoute version of `GET /whoami`. Here is how you can test it:

Follow [DEVELOPER_GUIDE](DEVELOPER_GUIDE.md) to setup OpenSearch cluster and initialize security plugin. Once you have verified that security plugin is installed correctly and OpenSearch is running, execute following curl requests:

package org.opensearch.security.rest;

import com.carrotsearch.randomizedtesting.annotations.ThreadLeakScope;

import org.apache.hc.core5.http.HttpStatus;

import org.junit.ClassRule;

import org.junit.Test;

import org.junit.runner.RunWith;

import org.opensearch.test.framework.TestSecurityConfig;

import org.opensearch.test.framework.TestSecurityConfig.Role;

import org.opensearch.test.framework.cluster.ClusterManager;

import org.opensearch.test.framework.cluster.LocalCluster;

import org.opensearch.test.framework.cluster.TestRestClient;

import static org.hamcrest.MatcherAssert.assertThat;

import static org.hamcrest.Matchers.equalTo;

import static org.opensearch.test.framework.TestSecurityConfig.AuthcDomain.AUTHC_HTTPBASIC_INTERNAL;

@RunWith(com.carrotsearch.randomizedtesting.RandomizedRunner.class)

@ThreadLeakScope(ThreadLeakScope.Scope.NONE)

public class WhoAmITests {

protected final static TestSecurityConfig.User WHO_AM_I = new TestSecurityConfig.User("who_am_i_user").roles(

new Role("who_am_i_role").clusterPermissions("security:whoamiprotected")

);

protected final static TestSecurityConfig.User WHO_AM_I_LEGACY = new TestSecurityConfig.User("who_am_i_user_legacy").roles(

new Role("who_am_i_role_legacy").clusterPermissions("cluster:admin/opendistro_security/whoamiprotected")

);

protected final static TestSecurityConfig.User WHO_AM_I_NO_PERM = new TestSecurityConfig.User("who_am_i_user_no_perm").roles(

new Role("who_am_i_role_no_perm")

);

protected final static TestSecurityConfig.User WHO_AM_I_UNREGISTERED = new TestSecurityConfig.User("who_am_i_user_no_perm");

public static final String WHOAMI_ENDPOINT = "_plugins/_security/whoami";

public static final String WHOAMI_PROTECTED_ENDPOINT = "_plugins/_security/whoamiprotected";

@ClassRule

public static LocalCluster cluster = new LocalCluster.Builder().clusterManager(ClusterManager.THREE_CLUSTER_MANAGERS)

.authc(AUTHC_HTTPBASIC_INTERNAL)

.users(WHO_AM_I, WHO_AM_I_LEGACY, WHO_AM_I_NO_PERM)

.build();

@Test

public void testWhoAmIWithGetPermissions() throws Exception {

try (TestRestClient client = cluster.getRestClient(WHO_AM_I)) {

assertThat(client.get(WHOAMI_PROTECTED_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_OK));

}

try (TestRestClient client = cluster.getRestClient(WHO_AM_I)) {

assertThat(client.get(WHOAMI_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_OK));

}

}

@Test

public void testWhoAmIWithGetPermissionsLegacy() throws Exception {

try (TestRestClient client = cluster.getRestClient(WHO_AM_I_LEGACY)) {

assertThat(client.get(WHOAMI_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_OK));

}

try (TestRestClient client = cluster.getRestClient(WHO_AM_I_LEGACY)) {

assertThat(client.get(WHOAMI_PROTECTED_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_OK));

}

}

@Test

public void testWhoAmIWithoutGetPermissions() throws Exception {

try (TestRestClient client = cluster.getRestClient(WHO_AM_I_NO_PERM)) {

assertThat(client.get(WHOAMI_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_OK));

}

try (TestRestClient client = cluster.getRestClient(WHO_AM_I_NO_PERM)) {

assertThat(client.get(WHOAMI_PROTECTED_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_UNAUTHORIZED));

}

}

@Test

public void testWhoAmIPost() throws Exception {

try (TestRestClient client = cluster.getRestClient(WHO_AM_I)) {

assertThat(client.post(WHOAMI_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_OK));

}

try (TestRestClient client = cluster.getRestClient(WHO_AM_I_LEGACY)) {

assertThat(client.post(WHOAMI_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_OK));

}

try (TestRestClient client = cluster.getRestClient(WHO_AM_I_NO_PERM)) {

assertThat(client.post(WHOAMI_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_OK));

}

try (TestRestClient client = cluster.getRestClient(WHO_AM_I_UNREGISTERED)) {

assertThat(client.post(WHOAMI_ENDPOINT).getStatusCode(), equalTo(HttpStatus.SC_OK));

}

}

}

import org.opensearch.security.privileges.RestLayerPrivilegesEvaluator;

private volatile RestLayerPrivilegesEvaluator restLayerEvaluator;

restLayerEvaluator = new RestLayerPrivilegesEvaluator(clusterService, threadPool, auditLog, cih, namedXContentRegistry);

restLayerEvaluator,

dcf.registerDCFListener(restLayerEvaluator);

components.add(restLayerEvaluator);

msg.addPrivilege(privilege);

import org.opensearch.rest.NamedRoute;

return routes.stream().flatMap(r -> Arrays.stream(prefixes).map(p -> {

if (r instanceof NamedRoute) {

NamedRoute nr = (NamedRoute) r;

return new NamedRoute.Builder().method(nr.getMethod())

.path(p + nr.getPath())

.uniqueName(nr.name())

.legacyActionNames(nr.actionNames())

.build();

}

return new Route(r.getMethod(), p + r.getPath());

})).collect(ImmutableList.toImmutableList());