Skip to content

Commit f7929ef

Browse files
mneethirajmneethiraj
committed
RANGER-5309: add authz-api module
1 parent 82082f1 commit f7929ef

17 files changed

Lines changed: 1817 additions & 0 deletions

‎authz-api/README.txt‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one or more
2+
# contributor license agreements. See the NOTICE file distributed with
3+
# this work for additional information regarding copyright ownership.
4+
# The ASF licenses this file to You under the Apache License, Version 2.0
5+
# (the "License"); you may not use this file except in compliance with
6+
# the License. You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
16+
17+
1. Introduction
18+
Authorization APIs introduced in this module make it simpler for applications to use Apache Ranger to authorize
19+
access to their resources. This document includes few examples of authorization requests and corresponding
20+
responses. Libraries in Java and Python will be made available for easier integration in applications using
21+
these languages. Support for other languages will be added later as needed.
22+
23+
2. Terminology
24+
2.1. User
25+
An actor who performs actions on resources. Each user is identified by an unique name. A user can belong
26+
to multiple groups and can have multiple roles. A user can also have multiple attributes, like department
27+
name, work location. Apache Ranger policies can be setup to grant access to resources based on any of the
28+
following: user name, groups the user belongs to, roles the user is assigned to and user attributes.
29+
30+
2.2. Resource
31+
Any object on which actions can be performed. Few examples of resources and actions performed on them:
32+
- file: create, delete, write, read
33+
- table: create, alter, drop, insert, select, delete
34+
- topic: create, alter, delete, produce, consume
35+
36+
Resources are identified by their name, in format: "resource-type:resource-value". Few examples of resource
37+
names:
38+
- path:/warehouse/hive/mktg/visitors
39+
- table:db1.tbl1
40+
- object:s3a://mybucket/p1/p2/data.parquet
41+
42+
Resources can have attributes, like owner, createTime. Access to resources can be granted based on resource
43+
attributes, like: owner of a resource should be allowed all actions.
44+
45+
Resources can have sub-resources, like columns of a table. This is useful in optimizing authorization for
46+
access to a resource and several of its sub-resources in a single request.
47+
48+
2.3. Action
49+
An action performed on a resource. Examples of actions include: query, list, read, write, delete. In the
50+
context of authorization, the action given in the request is used only to record in audit log and does not
51+
affect the authorization decision. The authorization decision is based on the permissions requested for the
52+
resource.
53+
54+
2.4. Permission
55+
A privilege necessary to perform an action on a resources. Apache Ranger policies are used to grant or deny
56+
permissions to users. An action might require one or more permissions. Examples of permissions include:
57+
select, insert, read, write, delete.
58+
59+
2.5. Context
60+
Additional information about the request that can be used to make authorization decisions. Examples of
61+
context information include: access time, client IP address, cluster name, cluster type.
62+
63+
2.6. Decision
64+
The result of the authorization request. The decision can be either "ALLOWED" or "DENIED". The decision is
65+
based on the policies defined in Apache Ranger and the user, resource, permissions and context information
66+
provided in the request.
67+
68+
2.7. Row Filter
69+
For resources that support rows, like tables, Apache Ranger policies can be setup to filter rows that a user
70+
can access. Response from authorization request for such resources can include a row filter that should be
71+
applied by the caller, to ensure that the user only accesses rows they are allowed to. For example, a row
72+
filter can be defined to restrict access to rows in a table based on the department the user belongs to.
73+
74+
2.8. Data Mask
75+
For resources that support data masking, like columns of a table, Apache Ranger policies can be setup to
76+
mask (or transformation) values of columns having sensitive data. Response from authorization request for
77+
such resources can include a data mask that should be applied by the caller, to ensure that the user only
78+
has accesses to masked value of sensitive data. For example, a data mask can be defined on a column having
79+
phone number, credit card number or social security number.
80+
81+
3. Examples
82+
This section includes few examples of authorization requests and corresponding responses. The examples include
83+
authorizing access to a single resource, authorizing access to a resource and sub-resources, authorizing access
84+
to multiple resources in a single request, row-filter and data-mask information in the response.
85+
86+
3.1 Authorize access to a single resource - a path
87+
request:
88+
{
89+
"requestId": "9198b532-a386-4464-9770-d61a8e8bc206",
90+
"user": { "name": "gary.adams", "groups": [ "fte", "mktg" ], "roles": [ "analyst" ] }
91+
"access": { "resource": "path:/warehouse/hive/mktg/visitors", "action": "LIST", "permissions": [ "list" ], "attributes": { "OWNER": "nancy.boxer" } }
92+
"context": { "accessTime": 1755543894, "clientIpAddress": "12.051.242", "forwardedIpAddresses": [], "additionalInfo": { "clientType": "CLI", "clusterName": "cl1", "clusterType": "onprem" } }
93+
}
94+
95+
result:
96+
{
97+
"requestId": "9198b532-a386-4464-9770-d61a8e8bc206",
98+
"decision": "ALLOWED",
99+
"permissions": {
100+
"list": { "access": { "result": "ALLOWED", "policy": { "id": 1, "version": 1 } }
101+
}
102+
}
103+
}
104+
105+
3.2 Authorize access to a single resource and its sub-resources - a table and 3 columns
106+
request:
107+
{
108+
"requestId": "0a4134c1-44af-42e1-8a27-f15f18e60850",
109+
"user": { "name": "gary.adams", "groups": [ "fte", "mktg" ], "roles": [ "analyst" ] }
110+
"access": { "resource": "table:db1.tbl1", "subResources: [ "column:col1", "column:col2", "column:col3" ], "action": "QUERY", "permissions": [ "select" ], "attributes": { "OWNER": "nancy.boxer" } }
111+
"context": { "accessTime": 1755543894, "clientIpAddress": "12.051.242", "forwardedIpAddresses": [], "additionalInfo": { "clientType": "CLI", "clusterName": "cl1", "clusterType": "onprem" } }
112+
}
113+
114+
result:
115+
{
116+
"requestId": "0a4134c1-44af-42e1-8a27-f15f18e60850",
117+
"decision": "ALLOWED",
118+
"permissions": {
119+
"select": {
120+
"rowFilter": { "filterExpression": "dept = 'mktg'", "policy": { "id": 11, "version": 3 } }
121+
"subResources": {
122+
"column:col1": { "access": { "decision": "ALLOWED", "policy": { "id": 5, "version": 1 } },
123+
"dataMask": { "maskType": "MASK_SHOW_LAST_4", "maskedValue": "mask_show_last_n({col}, 4, 'x', 'x', 'x', -1, '1')", "policy": { "id": 26, "version": 2 } } },
124+
"column:col2": { "access": { "decision": "ALLOWED", "policy": { "id": 2, "version": 1 } },
125+
"dataMask": { "maskType": "MASK_HASH", "maskedValue": "mask_hash({col})", "policy": { "id": 27, "version": 4 } } },
126+
"column:col3": { "access": { "decision": "ALLOWED", "policy": { "id": 3, "version": 1 } },
127+
"dataMask": { "maskType": "MASK_HASH", "maskedValue": "mask_hash({col})", "policy": { "id": 27, "version": 4 } } }
128+
}
129+
}
130+
}
131+
}
132+
133+
3.3: Authorize access to multiple resources - select on 2 tables and create on a table
134+
request:
135+
{
136+
"requestId": "4aa68265-34f1-4115-b026-d88dff292669",
137+
"user": { "name": "gary.adams", "groups": [ "fte", "mktg" ], "roles": [ "analyst" ] }
138+
"accesses": [
139+
{ "resource": "table:db1.tbl1", "action": "QUERY", "permissions": [ "select" ], "attributes": { "OWNER": "nancy.boxer" } },
140+
{ "resource": "table:db1.tbl2", "action": "QUERY", "permissions": [ "select" ], "attributes": { "OWNER": "nancy.boxer" } },
141+
{ "resource": "table:db1.vw1", "action": "CREATE", "permissions": [ "create" ] }
142+
],
143+
"context": { "accessTime": 1755543894, "clientIpAddress": "12.051.242", "forwardedIpAddresses": [], "additionalInfo": { "clientType": "CLI", "clusterName": "cl1", "clusterType": "onprem" } }
144+
}
145+
146+
result:
147+
{
148+
"requestId": "4aa68265-34f1-4115-b026-d88dff292669",
149+
"decision": "DENIED",
150+
"accesses": [
151+
{
152+
"decision": "ALLOWED",
153+
"permissions": {
154+
"select": {
155+
"access": { "decision": "ALLOWED", "policy": { "id": 1, "version": 1 } },
156+
"rowFilter": { "filterExpression": "dept = 'mktg'", "policy": { "id": 11, "version": 3 } }
157+
}
158+
}
159+
},
160+
{
161+
"decision": "DENIED",
162+
"permissions": {
163+
"select": {
164+
"access": { "decision": "DENIED", "policy": { "id": 21, "version": 1 } }
165+
}
166+
}
167+
},
168+
{
169+
"decision": "ALLOWED",
170+
"permissions": {
171+
"create": {
172+
"access": { "decision": "ALLOWED", "policy": { "id": 23, "version": 3 } }
173+
}
174+
}
175+
}
176+
]
177+
}

‎authz-api/pom.xml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
Licensed to the Apache Software Foundation (ASF) under one or more
4+
contributor license agreements. See the NOTICE file distributed with
5+
this work for additional information regarding copyright ownership.
6+
The ASF licenses this file to You under the Apache License, Version 2.0
7+
(the "License"); you may not use this file except in compliance with
8+
the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
-->
18+
<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">
19+
<modelVersion>4.0.0</modelVersion>
20+
21+
<parent>
22+
<groupId>org.apache.ranger</groupId>
23+
<artifactId>ranger</artifactId>
24+
<version>3.0.0-SNAPSHOT</version>
25+
<relativePath>..</relativePath>
26+
</parent>
27+
28+
<artifactId>ranger-authz-api</artifactId>
29+
<packaging>jar</packaging>
30+
31+
<name>Ranger Authorization API</name>
32+
<description>Ranger Authorization API</description>
33+
34+
<properties>
35+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
36+
</properties>
37+
38+
<dependencies>
39+
<dependency>
40+
<groupId>com.fasterxml.jackson.core</groupId>
41+
<artifactId>jackson-annotations</artifactId>
42+
<version>${fasterxml.jackson.version}</version>
43+
</dependency>
44+
45+
<dependency>
46+
<groupId>org.slf4j</groupId>
47+
<artifactId>slf4j-api</artifactId>
48+
<version>2.0.17</version>
49+
<scope>compile</scope>
50+
</dependency>
51+
52+
<dependency>
53+
<groupId>org.junit.jupiter</groupId>
54+
<artifactId>junit-jupiter-api</artifactId>
55+
<version>${junit.jupiter.version}</version>
56+
<scope>test</scope>
57+
</dependency>
58+
59+
<dependency>
60+
<groupId>org.junit.jupiter</groupId>
61+
<artifactId>junit-jupiter-engine</artifactId>
62+
<version>${junit.jupiter.version}</version>
63+
<scope>test</scope>
64+
</dependency>
65+
</dependencies>
66+
</project>

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.apache.ranger.authz.api;
21+
22+
import org.apache.ranger.authz.model.RangerAuthzRequest;
23+
import org.apache.ranger.authz.model.RangerAuthzResult;
24+
import org.apache.ranger.authz.model.RangerMultiAuthzRequest;
25+
import org.apache.ranger.authz.model.RangerMultiAuthzResult;
26+
27+
import java.util.Properties;
28+
29+
public abstract class RangerAuthorizer implements AutoCloseable {
30+
protected final Properties properties;
31+
32+
protected RangerAuthorizer(Properties properties) {
33+
this.properties = properties;
34+
}
35+
36+
public abstract RangerAuthzResult authorize(RangerAuthzRequest request) throws RangerAuthzException;
37+
38+
public abstract RangerMultiAuthzResult authorize(RangerMultiAuthzRequest request) throws RangerAuthzException;
39+
}

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

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
package org.apache.ranger.authz.api;
21+
22+
import java.util.Properties;
23+
24+
import static org.apache.ranger.authz.api.RangerAuthzApiErrorCode.AUTHZ_FACTORY_INITIALIZATION_FAILED;
25+
import static org.apache.ranger.authz.api.RangerAuthzApiErrorCode.AUTHZ_FACTORY_NOT_INITIALIZED;
26+
27+
public class RangerAuthorizerFactory {
28+
public static final String PROPERTY_RANGER_AUTHORIZER_IMPL_CLASS = "ranger.authorizer.impl.class";
29+
public static final String DEFAULT_RANGER_AUTHORIZER_IMPL_CLASS = "org.apache.ranger.authz.embedded.RangerEmbeddedAuthorizer";
30+
31+
private static RangerAuthorizerFactory instance;
32+
33+
private final Properties properties;
34+
private final RangerAuthorizer authorizer;
35+
36+
public static RangerAuthorizerFactory getOrCreateInstance(Properties properties) throws RangerAuthzException {
37+
RangerAuthorizerFactory instance = RangerAuthorizerFactory.instance;
38+
39+
if (instance == null) {
40+
synchronized (RangerAuthorizerFactory.class) {
41+
instance = RangerAuthorizerFactory.instance;
42+
43+
if (instance == null) {
44+
instance = new RangerAuthorizerFactory(properties);
45+
46+
RangerAuthorizerFactory.instance = instance;
47+
}
48+
}
49+
}
50+
51+
return instance;
52+
}
53+
54+
public static RangerAuthorizerFactory getInstance() throws RangerAuthzException {
55+
RangerAuthorizerFactory ret = instance;
56+
57+
if (ret == null) {
58+
throw new RangerAuthzException(AUTHZ_FACTORY_NOT_INITIALIZED);
59+
}
60+
61+
return ret;
62+
}
63+
64+
private RangerAuthorizerFactory(Properties properties) throws RangerAuthzException {
65+
this.properties = properties;
66+
67+
String implClass = this.properties.getProperty(PROPERTY_RANGER_AUTHORIZER_IMPL_CLASS, DEFAULT_RANGER_AUTHORIZER_IMPL_CLASS);
68+
69+
try {
70+
authorizer = (RangerAuthorizer) Class.forName(implClass).getDeclaredConstructor(Properties.class).newInstance(properties);
71+
} catch (Exception e) {
72+
throw new RangerAuthzException(AUTHZ_FACTORY_INITIALIZATION_FAILED, e);
73+
}
74+
}
75+
76+
public RangerAuthorizer getAuthorizer() {
77+
return authorizer;
78+
}
79+
}

0 commit comments

Comments
 (0)