apache-ranger 0.0.13

Apache Ranger Python client

Apache Ranger Python Client

apache-ranger is the official Python client package for Apache Ranger. It provides typed helpers for Ranger Admin, user/group management, KMS, Governed Data Sharing (GDS), and Policy Decision Point (PDP) APIs.

Requirements

• Python 3.13 or later
• Apache Ranger Admin, KMS, or PDP service reachable from your Python process

Installation

Install the client from PyPI:

pip install apache-ranger

For Kerberos/SPNEGO authentication, install the optional Kerberos dependency:

pip install requests-kerberos

Verify the installed package:

python -m pip show apache-ranger

Supported Clients

• RangerClient: Ranger Admin APIs for service definitions, services, policies, roles, security zones, plugin information, and policy delta maintenance.
• RangerUserMgmtClient: user, group, and user-group management APIs.
• RangerKMSClient: Ranger KMS key management APIs.
• RangerGdsClient: Governed Data Sharing APIs for datasets, projects, datashares, shared resources, and GDS policies.
• RangerPDPClient: PDP authorization APIs for single authorization, batch authorization, and effective resource permissions.

Quick Start

Ranger Admin

from apache_ranger.client.ranger_client import RangerClient

ranger = RangerClient("http://localhost:6080", ("admin", "rangerR0cks!"))

services = ranger.find_services()
print(f"{len(services.list)} services found")

User And Group Management

from apache_ranger.client.ranger_client import RangerClient
from apache_ranger.client.ranger_user_mgmt_client import RangerUserMgmtClient

ranger = RangerClient("http://localhost:6080", ("admin", "rangerR0cks!"))
user_mgmt = RangerUserMgmtClient(ranger)

users = user_mgmt.find_users()
groups = user_mgmt.find_groups()

print(f"{len(users.list)} users found")
print(f"{len(groups.list)} groups found")

Ranger KMS

from apache_ranger.client.ranger_client import HadoopSimpleAuth
from apache_ranger.client.ranger_kms_client import RangerKMSClient

kms = RangerKMSClient("http://localhost:9292", HadoopSimpleAuth("keyadmin"))

print(kms.kms_status())

Governed Data Sharing

from apache_ranger.client.ranger_client import RangerClient
from apache_ranger.client.ranger_gds_client import RangerGdsClient

ranger = RangerClient("http://localhost:6080", ("admin", "rangerR0cks!"))
gds = RangerGdsClient(ranger)

datasets = gds.find_datasets()
print(f"{len(datasets.list)} datasets found")

Policy Decision Point

from apache_ranger.client.ranger_pdp_client import RangerPDPClient
from apache_ranger.model.ranger_authz import (
    RangerAccessContext,
    RangerAccessInfo,
    RangerAuthzRequest,
    RangerResourceInfo,
    RangerUserInfo,
)

pdp = RangerPDPClient(
    "http://localhost:6500",
    auth=None,
    headers={"X-Forwarded-User": "hive"},
)

request = RangerAuthzRequest({
    "requestId": "req-1",
    "user": RangerUserInfo({"name": "alice"}),
    "access": RangerAccessInfo({
        "resource": RangerResourceInfo({"name": "table:default/test_tbl1"}),
        "permissions": ["select"],
    }),
    "context": RangerAccessContext({
        "serviceType": "hive",
        "serviceName": "dev_hive",
    }),
})

result = pdp.authorize(request)
print(result.decision)

Authentication

Use the authentication mechanism configured for the Ranger service you are calling:

• Basic auth: pass a (username, password) tuple to RangerClient.
• Kerberos/SPNEGO: pass requests_kerberos.HTTPKerberosAuth() after installing requests-kerberos.
• KMS Hadoop simple auth: use HadoopSimpleAuth("user") when simple auth is enabled for Ranger KMS.
• Custom headers or query parameters: pass headers or query_params to the client constructor when the deployment requires them.
• PDP trusted-header or JWT auth: pass the configured trusted caller header or Authorization: Bearer <token> header to RangerPDPClient.

Example Kerberos setup:

from requests_kerberos import HTTPKerberosAuth
from apache_ranger.client.ranger_client import RangerClient

ranger = RangerClient("https://ranger.example.com:6182", HTTPKerberosAuth())

PDP Request Notes

RangerPDPClient sends requests to the PDP REST APIs exposed under /authz/v1.

• authorize(request) calls POST /authz/v1/authorize.
• authorize_multi(request) calls POST /authz/v1/authorizeMulti.
• get_resource_permissions(request) calls POST /authz/v1/permissions.

PDP authorization requests should include:

• context.serviceType, for example hive, hdfs, or kafka.
• context.serviceName, the Ranger service name.
• user.name for authorize and authorize_multi calls.

If the authenticated caller is different from request.user.name, the caller must be allowed to delegate for that service. Without delegation permission, PDP returns 403 FORBIDDEN.

Examples and Code References

The quick starts above cover the basics. For day-to-day API usage — creating services and policies, managing users, calling KMS or PDP, or working with GDS — use the runnable samples and client sources below.

Running sample scripts

After pip install apache-ranger, run a sample directly:

python ranger-examples/sample-client/src/main/python/sample_client.py

When working from a Ranger source checkout without installing the package, set PYTHONPATH to the client sources first:

# from the repository root
PYTHONPATH=intg/src/main/python \
  python ranger-examples/sample-client/src/main/python/sample_client.py

Edit the ranger_url, ranger_auth, and other connection settings at the top of each sample before running it against your environment.

Runnable examples by task

Task	Sample script	What it demonstrates
Ranger Admin — services, policies, roles, tags CRUD	sample_client.py	service-def and service, access/data-masking/row-filter policies, roles, service tags
User and group management	user_mgmt.py	List/create/delete users and groups, group-user mappings
Ranger KMS	sample_kms_client.py	Key lifecycle, encrypt/decrypt/reencrypt, metadata and status
PDP AuthZ	sample_pdp_client.py	Authz/MultiAuthz calls to PDP Server
Governed Data Sharing (GDS)	sample_gds_client.py	Projects, datasets, datashares, shared resources, GDS policies
Security zones (v2)	security_zone_v2.py	Create/update security zones and zone resources

All samples live under ranger-examples/sample-client/src/main/python.

Client API source code

Each public client is implemented under intg/src/main/python/apache_ranger/client/:

Client	Source file	REST base path
RangerClient	ranger_client.py	service/public/v2/api
RangerUserMgmtClient	ranger_user_mgmt_client.py	user/group APIs on Ranger Admin
RangerKMSClient	ranger_kms_client.py	KMS REST APIs
RangerGdsClient	ranger_gds_client.py	GDS APIs on Ranger Admin
RangerPDPClient	ranger_pdp_client.py	/authz/v1

Request and response models are under intg/src/main/python/apache_ranger/model/.

Unit tests

intg/src/test/python/test_ranger_client.py contains mocked examples for Admin, GDS, and PDP client wiring. Run from intg/:

PYTHONPATH=src/main/python python -B src/test/python/test_ranger_client.py

Troubleshooting

• ModuleNotFoundError: requests_kerberos: install requests-kerberos.
• 401 Unauthorized: verify the credentials, Kerberos ticket, or auth headers used by the target Ranger service.
• 403 Forbidden: verify Ranger permissions and PDP delegation configuration when authorizing on behalf of another user.
• SSL certificate errors: configure a valid trust store for production. For local testing only, ranger.session.verify = False can disable certificate verification.
• Connection timeouts: verify the Ranger Admin, KMS, or PDP URL and confirm the service is reachable from the client host.

Release 0.0.13 Highlights

• Python 3.13+ support.
• New GDS client coverage for datasets, projects, datashares, shared resources, and GDS policy APIs.
• New PDP client coverage for Ranger authorization APIs.
• New authorization request and response models.
• User/group management, KMS, Ranger Admin, and model updates.