RANGER-5309: add authz-api module

authz-api/README.txt

@@ -0,0 +1,177 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+1. Introduction
+   Authorization APIs introduced in this module make it simpler for applications to use Apache Ranger to authorize
+   access to their resources. This document includes few examples of authorization requests and corresponding
+   responses. Libraries in Java and Python will be made available for easier integration in applications using
+   these languages. Support for other languages will be added later as needed.
+
+2. Terminology
+   2.1. User
+        An actor who performs actions on resources. Each user is identified by an unique name. A user can belong
+        to multiple groups and can have multiple roles. A user can also have multiple attributes, like department
+        name, work location. Apache Ranger policies can be setup to grant access to resources based on any of the
+        following: user name, groups the user belongs to, roles the user is assigned to and user attributes.
+
+   2.2. Resource
+        Any object on which actions can be performed. Few examples of resources and actions performed on them:
+         - file: create, delete, write, read
+         - table: create, alter, drop, insert, select, delete
+         - topic: create, alter, delete, produce, consume
+
+        Resources are identified by their name, in format: "resource-type:resource-value". Few examples of resource
+        names:
+         - path:/warehouse/hive/mktg/visitors
+         - table:db1.tbl1
+         - object:s3a://mybucket/p1/p2/data.parquet
+
+        Resources can have attributes, like owner, createTime. Access to resources can be granted based on resource
+        attributes, like: owner of a resource should be allowed all actions.
+
+        Resources can have sub-resources, like columns of a table. This is useful in optimizing authorization for
+        access to a resource and several of its sub-resources in a single request.
+
+   2.3. Action
+        An action performed on a resource. Examples of actions include: query, list, read, write, delete. In the
+        context of authorization, the action given in the request is used only to record in audit log and does not
+        affect the authorization decision. The authorization decision is based on the permissions requested for the
+        resource.
+
+   2.4. Permission
+        A privilege necessary to perform an action on a resources. Apache Ranger policies are used to grant or deny
+        permissions to users. An action might require one or more permissions. Examples of permissions include:
+        select, insert, read, write, delete.
+
+   2.5. Context
+        Additional information about the request that can be used to make authorization decisions. Examples of
+        context information include: access time, client IP address, cluster name, cluster type.
+
+   2.6. Decision
+        The result of the authorization request. The decision can be either "ALLOWED" or "DENIED". The decision is
+        based on the policies defined in Apache Ranger and the user, resource, permissions and context information
+        provided in the request.
+
+   2.7. Row Filter
+        For resources that support rows, like tables, Apache Ranger policies can be setup to filter rows that a user
+        can access. Response from authorization request for such resources can include a row filter that should be
+        applied by the caller, to ensure that the user only accesses rows they are allowed to. For example, a row
+        filter can be defined to restrict access to rows in a table based on the department the user belongs to.
+
+   2.8. Data Mask
+        For resources that support data masking, like columns of a table, Apache Ranger policies can be setup to
+        mask (or transformation) values of columns having sensitive data. Response from authorization request for
+        such resources can include a data mask that should be applied by the caller, to ensure that the user only
+        has accesses to masked value of sensitive data. For example, a data mask can be defined on a column having
+        phone number, credit card number or social security number.
+
+3. Examples
+   This section includes few examples of authorization requests and corresponding responses. The examples include
+   authorizing access to a single resource, authorizing access to a resource and sub-resources, authorizing access
+   to multiple resources in a single request, row-filter and data-mask information in the response.
+
+   3.1 Authorize access to a single resource - a path
+    request:
+    {
+      "requestId": "9198b532-a386-4464-9770-d61a8e8bc206",
+      "user":      { "name": "gary.adams", "groups": [ "fte", "mktg" ], "roles": [ "analyst" ] }
+      "access":    { "resource": "path:/warehouse/hive/mktg/visitors", "action": "LIST", "permissions": [ "list" ], "attributes": { "OWNER": "nancy.boxer" } }
+      "context":   { "accessTime": 1755543894, "clientIpAddress": "12.051.242", "forwardedIpAddresses": [], "additionalInfo": { "clientType": "CLI", "clusterName": "cl1", "clusterType": "onprem" } }
+    }
+
+    result:
+    {
+      "requestId": "9198b532-a386-4464-9770-d61a8e8bc206",
+      "decision":  "ALLOWED",
+      "permissions": {
+        "list": { "access": { "result": "ALLOWED", "policy": { "id": 1, "version": 1 } }
+        }
+      }
+    }
+
+   3.2 Authorize access to a single resource and its sub-resources - a table and 3 columns
+    request:
+    {
+      "requestId": "0a4134c1-44af-42e1-8a27-f15f18e60850",
+      "user":      { "name": "gary.adams", "groups": [ "fte", "mktg" ], "roles": [ "analyst" ] }
+      "access":    { "resource": "table:db1.tbl1", "subResources: [ "column:col1", "column:col2", "column:col3" ], "action": "QUERY", "permissions": [ "select" ], "attributes": { "OWNER": "nancy.boxer" } }
+      "context":   { "accessTime": 1755543894, "clientIpAddress": "12.051.242", "forwardedIpAddresses": [], "additionalInfo": { "clientType": "CLI", "clusterName": "cl1", "clusterType": "onprem" } }
+    }
+
+    result:
+    {
+      "requestId": "0a4134c1-44af-42e1-8a27-f15f18e60850",
+      "decision":  "ALLOWED",
+      "permissions": {
+        "select": {
+          "rowFilter": { "filterExpression": "dept = 'mktg'", "policy": { "id": 11, "version": 3 } }
+          "subResources": {
+            "column:col1": { "access":   { "decision": "ALLOWED", "policy": { "id": 5, "version": 1 } },
+	                         "dataMask": { "maskType": "MASK_SHOW_LAST_4", "maskedValue": "mask_show_last_n({col}, 4, 'x', 'x', 'x', -1, '1')", "policy": { "id": 26, "version": 2 } } },
+            "column:col2": { "access":   { "decision": "ALLOWED", "policy": { "id": 2, "version": 1 } },
+	                          "dataMask": { "maskType": "MASK_HASH", "maskedValue": "mask_hash({col})", "policy": { "id": 27, "version": 4 } } },
+            "column:col3": { "access":   { "decision": "ALLOWED", "policy": { "id": 3, "version": 1 } },
+	                         "dataMask": { "maskType": "MASK_HASH", "maskedValue": "mask_hash({col})", "policy": { "id": 27, "version": 4 } } }
+          }
+        }
+      }
+    }
+
+   3.3: Authorize access to multiple resources - select on 2 tables and create on a table
+    request:
+    {
+      "requestId": "4aa68265-34f1-4115-b026-d88dff292669",
+      "user":      { "name": "gary.adams", "groups": [ "fte", "mktg" ], "roles": [ "analyst" ] }
+      "accesses": [
+        { "resource": "table:db1.tbl1", "action": "QUERY", "permissions": [ "select" ], "attributes": { "OWNER": "nancy.boxer" } },
+        { "resource": "table:db1.tbl2", "action": "QUERY", "permissions": [ "select" ], "attributes": { "OWNER": "nancy.boxer" } },
+        { "resource": "table:db1.vw1",  "action": "CREATE", "permissions": [ "create" ] }
+      ],
+      "context": { "accessTime": 1755543894, "clientIpAddress": "12.051.242", "forwardedIpAddresses": [], "additionalInfo": { "clientType": "CLI", "clusterName": "cl1", "clusterType": "onprem" } }
+    }
+
+    result:
+    {
+      "requestId": "4aa68265-34f1-4115-b026-d88dff292669",
+      "decision":  "DENIED",
+      "accesses": [
+        {
+          "decision": "ALLOWED",
+          "permissions": {
+            "select": {
+              "access":    { "decision": "ALLOWED", "policy": { "id": 1, "version": 1 } },
+              "rowFilter": { "filterExpression": "dept = 'mktg'", "policy": { "id": 11, "version": 3 } }
+            }
+          }
+        },
+        {
+          "decision": "DENIED",
+          "permissions": {
+            "select": {
+              "access": { "decision": "DENIED", "policy": { "id": 21, "version": 1 } }
+            }
+          }
+        },
+        {
+          "decision": "ALLOWED",
+          "permissions": {
+            "create": {
+              "access": { "decision": "ALLOWED", "policy": { "id": 23, "version": 3 } }
+            }
+          }
+        }
+      ]
+    }

authz-api/pom.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.apache.ranger</groupId>
+        <artifactId>ranger</artifactId>
+        <version>3.0.0-SNAPSHOT</version>
+        <relativePath>..</relativePath>
+    </parent>
+
+    <artifactId>ranger-authz-api</artifactId>
+    <packaging>jar</packaging>
+
+    <name>Ranger Authorization API</name>
+    <description>Ranger Authorization API</description>
+
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-annotations</artifactId>
+            <version>${fasterxml.jackson.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <version>2.0.17</version>
+            <scope>compile</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <version>${junit.jupiter.version}</version>
+            <scope>test</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <version>${junit.jupiter.version}</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

authz-api/src/main/java/org/apache/ranger/authz/api/RangerAuthorizer.java

@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.authz.api;
+
+import org.apache.ranger.authz.model.RangerAuthzRequest;
+import org.apache.ranger.authz.model.RangerAuthzResult;
+import org.apache.ranger.authz.model.RangerMultiAuthzRequest;
+import org.apache.ranger.authz.model.RangerMultiAuthzResult;
+
+import java.util.Properties;
+
+public abstract class RangerAuthorizer implements AutoCloseable {
+    protected final Properties properties;
+
+    protected RangerAuthorizer(Properties properties) {
+        this.properties = properties;
+    }
+
+    public abstract RangerAuthzResult authorize(RangerAuthzRequest request) throws RangerAuthzException;
+
+    public abstract RangerMultiAuthzResult authorize(RangerMultiAuthzRequest request) throws RangerAuthzException;
+}

authz-api/src/main/java/org/apache/ranger/authz/api/RangerAuthorizerFactory.java

@@ -0,0 +1,79 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.ranger.authz.api;
+
+import java.util.Properties;
+
+import static org.apache.ranger.authz.api.RangerAuthzApiErrorCode.AUTHZ_FACTORY_INITIALIZATION_FAILED;
+import static org.apache.ranger.authz.api.RangerAuthzApiErrorCode.AUTHZ_FACTORY_NOT_INITIALIZED;
+
+public class RangerAuthorizerFactory {
+    public static final String PROPERTY_RANGER_AUTHORIZER_IMPL_CLASS = "ranger.authorizer.impl.class";
+    public static final String DEFAULT_RANGER_AUTHORIZER_IMPL_CLASS  = "org.apache.ranger.authz.embedded.RangerEmbeddedAuthorizer";
+
+    private static RangerAuthorizerFactory instance;
+
+    private final Properties       properties;
+    private final RangerAuthorizer authorizer;
+
+    public static RangerAuthorizerFactory getOrCreateInstance(Properties properties) throws RangerAuthzException {
+        RangerAuthorizerFactory instance = RangerAuthorizerFactory.instance;
+
+        if (instance == null) {
+            synchronized (RangerAuthorizerFactory.class) {
+                instance = RangerAuthorizerFactory.instance;
+
+                if (instance == null) {
+                    instance = new RangerAuthorizerFactory(properties);
+
+                    RangerAuthorizerFactory.instance = instance;
+                }
+            }
+        }
+
+        return instance;
+    }
+
+    public static RangerAuthorizerFactory getInstance() throws RangerAuthzException {
+        RangerAuthorizerFactory ret = instance;
+
+        if (ret == null) {
+            throw new RangerAuthzException(AUTHZ_FACTORY_NOT_INITIALIZED);
+        }
+
+        return ret;
+    }
+
+    private RangerAuthorizerFactory(Properties properties) throws RangerAuthzException {
+        this.properties = properties;
+
+        String implClass = this.properties.getProperty(PROPERTY_RANGER_AUTHORIZER_IMPL_CLASS, DEFAULT_RANGER_AUTHORIZER_IMPL_CLASS);
+
+        try {
+            authorizer = (RangerAuthorizer) Class.forName(implClass).getDeclaredConstructor(Properties.class).newInstance(properties);
+        } catch (Exception e) {
+            throw new RangerAuthzException(AUTHZ_FACTORY_INITIALIZATION_FAILED, e);
+        }
+    }
+
+    public RangerAuthorizer getAuthorizer() {
+        return authorizer;
+    }
+}