authz-api
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
parent directory.. | ||||
# 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 466A 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": { "name": ""path:/warehouse/hive/mktg/visitors", "attributes": { "OWNER": "nancy.boxer" } }, "action": "LIST", "permissions": [ "list" ] }, "context": { "serviceName": "s3", "accessTime": 1755543894, "clientIpAddress": "172.16.45.59", "additionalInfo": { "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": { "name": ""table:db1.tbl1", "subResources: [ "column:col1", "column:col2", "column:col3" ], "attributes": { "OWNER": "nancy.boxer" } }, "action": "QUERY", "permissions": [ "select" ] }, "context": { "serviceName": "hive", "accessTime": 1755543894, "clientIpAddress": "172.16.120.64", "additionalInfo": { "clientType": "beeline", "clusterName": "cl1", "clusterType": "onprem" } } } result: { "requestId": "0a4134c1-44af-42e1-8a27-f15f18e60850", "decision": "ALLOWED", "permissions": { "select": { "rowFilter": { "filterExpr": "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": { "name": "table:db1.tbl1", "attributes": { "OWNER": "nancy.boxer" } }, "action": "QUERY", "permissions": [ "select" ] }, { "resource": { "name": "table:db1.tbl2", "attributes": { "OWNER": "nancy.boxer" } }, "action": "QUERY", "permissions": [ "select" ] }, { "resource": { "name": "table:db1.vw1" }, "action": "CREATE", "permissions": [ "create" ] } ], "context": { "serviceName": "hive", "accessTime": 1755543894, "clientIpAddress": "172.16.27.152", "additionalInfo": { "clientType": "jdbc", "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": { "filterExpr": "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 } } } } } ] }