authzen-client 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- authzen_client-0.2.0/LICENSE +21 -0
- authzen_client-0.2.0/MANIFEST.in +4 -0
- authzen_client-0.2.0/PKG-INFO +89 -0
- authzen_client-0.2.0/README.md +72 -0
- authzen_client-0.2.0/docs/api.md +58 -0
- authzen_client-0.2.0/docs/authentication.md +104 -0
- authzen_client-0.2.0/docs/batch.md +68 -0
- authzen_client-0.2.0/docs/clients.md +57 -0
- authzen_client-0.2.0/docs/configuration.md +68 -0
- authzen_client-0.2.0/docs/development.md +56 -0
- authzen_client-0.2.0/docs/errors.md +37 -0
- authzen_client-0.2.0/docs/index.md +20 -0
- authzen_client-0.2.0/docs/migration.md +42 -0
- authzen_client-0.2.0/docs/quickstart.md +77 -0
- authzen_client-0.2.0/docs/search.md +81 -0
- authzen_client-0.2.0/examples/__init__.py +1 -0
- authzen_client-0.2.0/examples/async_evaluate.py +24 -0
- authzen_client-0.2.0/examples/async_oauth.py +44 -0
- authzen_client-0.2.0/examples/batch.py +30 -0
- authzen_client-0.2.0/examples/evaluate.py +32 -0
- authzen_client-0.2.0/examples/oauth.py +37 -0
- authzen_client-0.2.0/examples/search.py +30 -0
- authzen_client-0.2.0/examples/stub_pdp.py +129 -0
- authzen_client-0.2.0/pyproject.toml +65 -0
- authzen_client-0.2.0/setup.cfg +4 -0
- authzen_client-0.2.0/src/authzen_client/__init__.py +62 -0
- authzen_client-0.2.0/src/authzen_client/_client.py +201 -0
- authzen_client-0.2.0/src/authzen_client/async_client.py +179 -0
- authzen_client-0.2.0/src/authzen_client/client.py +167 -0
- authzen_client-0.2.0/src/authzen_client/exceptions.py +24 -0
- authzen_client-0.2.0/src/authzen_client/models.py +274 -0
- authzen_client-0.2.0/src/authzen_client/py.typed +0 -0
- authzen_client-0.2.0/src/authzen_client/settings.py +31 -0
- authzen_client-0.2.0/src/authzen_client/types.py +5 -0
- authzen_client-0.2.0/src/authzen_client.egg-info/PKG-INFO +89 -0
- authzen_client-0.2.0/src/authzen_client.egg-info/SOURCES.txt +46 -0
- authzen_client-0.2.0/src/authzen_client.egg-info/dependency_links.txt +1 -0
- authzen_client-0.2.0/src/authzen_client.egg-info/requires.txt +5 -0
- authzen_client-0.2.0/src/authzen_client.egg-info/top_level.txt +1 -0
- authzen_client-0.2.0/tests/fixtures/model_examples.json +164 -0
- authzen_client-0.2.0/tests/test_async_client.py +163 -0
- authzen_client-0.2.0/tests/test_client.py +252 -0
- authzen_client-0.2.0/tests/test_discovery.py +190 -0
- authzen_client-0.2.0/tests/test_examples.py +111 -0
- authzen_client-0.2.0/tests/test_extensions.py +364 -0
- authzen_client-0.2.0/tests/test_models.py +147 -0
- authzen_client-0.2.0/tests/test_oauth.py +204 -0
- authzen_client-0.2.0/tests/test_spec_examples.py +46 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Matvii Nesterenko
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: authzen-client
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: A typed Python client for the AuthZEN Authorization API.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Repository, https://github.com/kapustazh/authzen-client
|
|
7
|
+
Project-URL: Documentation, https://github.com/kapustazh/authzen-client/tree/main/docs
|
|
8
|
+
Project-URL: Issues, https://github.com/kapustazh/authzen-client/issues
|
|
9
|
+
Requires-Python: >=3.12
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Requires-Dist: httpx2<3,>=2.16.2
|
|
13
|
+
Requires-Dist: pydantic<3,>=2
|
|
14
|
+
Provides-Extra: oauth
|
|
15
|
+
Requires-Dist: authlib<2,>=1.9.8; extra == "oauth"
|
|
16
|
+
Dynamic: license-file
|
|
17
|
+
|
|
18
|
+
# authzen-client
|
|
19
|
+
|
|
20
|
+
A typed Python SDK for the [AuthZEN Authorization API](https://openid.net/specs/authorization-api-1_0.html).
|
|
21
|
+
Supports sync and async evaluation, batch requests, paginated search, discovery,
|
|
22
|
+
and authentication through HTTPX2 and Authlib.
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
Requires Python 3.12+. Install from a checkout in your application's environment.
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
git clone https://github.com/kapustazh/authzen-client.git
|
|
30
|
+
cd authzen-client
|
|
31
|
+
python -m pip install .
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
For OAuth Client Credentials, install the optional integration.
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
python -m pip install '.[oauth]'
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Quickstart
|
|
41
|
+
|
|
42
|
+
Pass the PDP's HTTPS base URL and apply its decision in your application.
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
from authzen_client import Action, AuthZENClient, EvaluationRequest, Resource, Subject
|
|
46
|
+
|
|
47
|
+
request = EvaluationRequest(
|
|
48
|
+
subject=Subject(type="user", id="alice"),
|
|
49
|
+
action=Action(name="read"),
|
|
50
|
+
resource=Resource(type="document", id="123"),
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
with AuthZENClient(base_url="https://pdp.example.com") as client:
|
|
54
|
+
response = client.evaluate(request)
|
|
55
|
+
|
|
56
|
+
if response.decision:
|
|
57
|
+
print("Access granted")
|
|
58
|
+
else:
|
|
59
|
+
print("Access denied")
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Run the bundled document-service example against an in-process PDP.
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
uv sync
|
|
66
|
+
uv run python -m examples.evaluate
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
alice: AuthZEN project notes
|
|
71
|
+
bob: access denied
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Documentation
|
|
75
|
+
|
|
76
|
+
- [Quickstart and runnable examples](docs/quickstart.md)
|
|
77
|
+
- [Sync and async clients](docs/clients.md)
|
|
78
|
+
- [Batch evaluations](docs/batch.md)
|
|
79
|
+
- [Search and pagination](docs/search.md)
|
|
80
|
+
- [Authentication](docs/authentication.md)
|
|
81
|
+
- [Configuration and discovery](docs/configuration.md)
|
|
82
|
+
- [Errors](docs/errors.md)
|
|
83
|
+
- [API reference](docs/api.md)
|
|
84
|
+
- [Migrating from 0.1](docs/migration.md)
|
|
85
|
+
- [Development and builds](docs/development.md)
|
|
86
|
+
|
|
87
|
+
## License
|
|
88
|
+
|
|
89
|
+
[MIT](LICENSE).
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# authzen-client
|
|
2
|
+
|
|
3
|
+
A typed Python SDK for the [AuthZEN Authorization API](https://openid.net/specs/authorization-api-1_0.html).
|
|
4
|
+
Supports sync and async evaluation, batch requests, paginated search, discovery,
|
|
5
|
+
and authentication through HTTPX2 and Authlib.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
Requires Python 3.12+. Install from a checkout in your application's environment.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
git clone https://github.com/kapustazh/authzen-client.git
|
|
13
|
+
cd authzen-client
|
|
14
|
+
python -m pip install .
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
For OAuth Client Credentials, install the optional integration.
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
python -m pip install '.[oauth]'
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Quickstart
|
|
24
|
+
|
|
25
|
+
Pass the PDP's HTTPS base URL and apply its decision in your application.
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
from authzen_client import Action, AuthZENClient, EvaluationRequest, Resource, Subject
|
|
29
|
+
|
|
30
|
+
request = EvaluationRequest(
|
|
31
|
+
subject=Subject(type="user", id="alice"),
|
|
32
|
+
action=Action(name="read"),
|
|
33
|
+
resource=Resource(type="document", id="123"),
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
with AuthZENClient(base_url="https://pdp.example.com") as client:
|
|
37
|
+
response = client.evaluate(request)
|
|
38
|
+
|
|
39
|
+
if response.decision:
|
|
40
|
+
print("Access granted")
|
|
41
|
+
else:
|
|
42
|
+
print("Access denied")
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Run the bundled document-service example against an in-process PDP.
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
uv sync
|
|
49
|
+
uv run python -m examples.evaluate
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
alice: AuthZEN project notes
|
|
54
|
+
bob: access denied
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Documentation
|
|
58
|
+
|
|
59
|
+
- [Quickstart and runnable examples](docs/quickstart.md)
|
|
60
|
+
- [Sync and async clients](docs/clients.md)
|
|
61
|
+
- [Batch evaluations](docs/batch.md)
|
|
62
|
+
- [Search and pagination](docs/search.md)
|
|
63
|
+
- [Authentication](docs/authentication.md)
|
|
64
|
+
- [Configuration and discovery](docs/configuration.md)
|
|
65
|
+
- [Errors](docs/errors.md)
|
|
66
|
+
- [API reference](docs/api.md)
|
|
67
|
+
- [Migrating from 0.1](docs/migration.md)
|
|
68
|
+
- [Development and builds](docs/development.md)
|
|
69
|
+
|
|
70
|
+
## License
|
|
71
|
+
|
|
72
|
+
[MIT](LICENSE).
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# API reference
|
|
2
|
+
|
|
3
|
+
## Clients
|
|
4
|
+
|
|
5
|
+
AuthZENClient and AsyncAuthZENClient accept keyword-only constructor arguments.
|
|
6
|
+
|
|
7
|
+
| Argument | Default | Purpose |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| base_url | Required | HTTPS PDP identifier |
|
|
10
|
+
| auth | None | HTTPX2 authentication |
|
|
11
|
+
| headers | None | Additional request headers |
|
|
12
|
+
| transport | None | HTTPX2 sync or async transport |
|
|
13
|
+
| timeout | 5.0 | Network-operation timeout, float, Timeout or None |
|
|
14
|
+
| limits | None | HTTPX2 connection limits |
|
|
15
|
+
| endpoints | None | Endpoints fallback configuration |
|
|
16
|
+
| http_client | None | Caller-owned HTTPX2 client |
|
|
17
|
+
|
|
18
|
+
Use the matching sync or async HTTP client and transport. Configure authentication
|
|
19
|
+
and network options directly on an injected http_client.
|
|
20
|
+
|
|
21
|
+
| Method | Input | Output |
|
|
22
|
+
| --- | --- | --- |
|
|
23
|
+
| evaluate | EvaluationRequest | EvaluationResponse |
|
|
24
|
+
| evaluate_batch | EvaluationsRequest | EvaluationsResponse |
|
|
25
|
+
| discover | None | PDPMetadata |
|
|
26
|
+
| search_resources | ResourceSearchRequest | ResourceSearchResponse |
|
|
27
|
+
| search_subjects | SubjectSearchRequest | SubjectSearchResponse |
|
|
28
|
+
| search_actions | ActionSearchRequest | ActionSearchResponse |
|
|
29
|
+
| iter_resources | ResourceSearchRequest | Iterator or AsyncIterator of Resource |
|
|
30
|
+
| iter_subjects | SubjectSearchRequest | Iterator or AsyncIterator of Subject |
|
|
31
|
+
| iter_actions | ActionSearchRequest | Iterator or AsyncIterator of Action |
|
|
32
|
+
|
|
33
|
+
Await async evaluate, batch, search and discover methods. Consume async iterators
|
|
34
|
+
with async for. Use close for the sync client and await aclose for the async one.
|
|
35
|
+
|
|
36
|
+
## Models
|
|
37
|
+
|
|
38
|
+
- Subject and Resource require string type and id, and accept JSON properties.
|
|
39
|
+
- Action requires string name and accepts JSON properties.
|
|
40
|
+
- Context wraps a JSON object through its root attribute.
|
|
41
|
+
- EvaluationRequest requires subject, action and resource, with optional Context.
|
|
42
|
+
- Decision contains a strict boolean decision and optional Context.
|
|
43
|
+
- EvaluationResponse is an alias for Decision.
|
|
44
|
+
- Evaluation contains optional entities inherited from an EvaluationsRequest.
|
|
45
|
+
- EvaluationsRequest adds evaluations and EvaluationsOptions to shared defaults.
|
|
46
|
+
- EvaluationsResponse contains ordered evaluations or a fallback decision.
|
|
47
|
+
- PageRequest accepts token, non-negative limit and JSON properties.
|
|
48
|
+
- PageResponse requires next_token and accepts non-negative count and total.
|
|
49
|
+
- SubjectQuery and ResourceQuery describe the queried entity type and properties.
|
|
50
|
+
- Search responses contain typed results, optional PageResponse and Context.
|
|
51
|
+
- PDPMetadata contains the PDP identifier, evaluation endpoint, optional endpoints
|
|
52
|
+
and supported_capabilities.
|
|
53
|
+
- Endpoints contains the five fallback paths or absolute HTTPS URLs.
|
|
54
|
+
|
|
55
|
+
Models support Pydantic validation and round-trips. Unknown protocol fields are
|
|
56
|
+
ignored. JSON attributes inside Context and properties are retained. Batch options
|
|
57
|
+
retain additional JSON options. None represents an omitted optional field in the
|
|
58
|
+
new request models. The client omits it from the wire payload.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Authentication
|
|
2
|
+
|
|
3
|
+
## Headers and HTTPX2 auth
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
import httpx2
|
|
7
|
+
from authzen_client import AuthZENClient
|
|
8
|
+
|
|
9
|
+
client = AuthZENClient(
|
|
10
|
+
base_url="https://pdp.example.com",
|
|
11
|
+
headers={"Authorization": "Bearer your-access-token"},
|
|
12
|
+
)
|
|
13
|
+
client.close()
|
|
14
|
+
|
|
15
|
+
with AuthZENClient(
|
|
16
|
+
base_url="https://pdp.example.com",
|
|
17
|
+
auth=httpx2.BasicAuth("username", "password"),
|
|
18
|
+
) as client:
|
|
19
|
+
pass
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Supply credentials from your application's configuration or secret store.
|
|
23
|
+
The application identity used to access the PDP API is independent of the Subject
|
|
24
|
+
in an evaluation request.
|
|
25
|
+
|
|
26
|
+
## OAuth Client Credentials
|
|
27
|
+
|
|
28
|
+
Install the OAuth extra from the checkout.
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
python -m pip install '.[oauth]'
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Authlib provides synchronous and asynchronous OAuth clients compatible with HTTPX2.
|
|
35
|
+
Pass an initialized OAuth client through http_client. The application owns its
|
|
36
|
+
lifecycle. Configure the token endpoint and grant type so Authlib can obtain a
|
|
37
|
+
new token when the previous one approaches expiry.
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
import os
|
|
41
|
+
from authlib.integrations.httpx_client import OAuth2Client
|
|
42
|
+
from authzen_client import AuthZENClient
|
|
43
|
+
|
|
44
|
+
token_url = os.environ["AUTHZEN_TOKEN_URL"]
|
|
45
|
+
with OAuth2Client(
|
|
46
|
+
client_id=os.environ["AUTHZEN_CLIENT_ID"],
|
|
47
|
+
client_secret=os.environ["AUTHZEN_CLIENT_SECRET"],
|
|
48
|
+
token_endpoint=token_url,
|
|
49
|
+
grant_type="client_credentials",
|
|
50
|
+
scope=os.environ.get("AUTHZEN_SCOPE"),
|
|
51
|
+
) as http:
|
|
52
|
+
http.fetch_token(token_url, grant_type="client_credentials")
|
|
53
|
+
with AuthZENClient(
|
|
54
|
+
base_url=os.environ["AUTHZEN_PDP_URL"],
|
|
55
|
+
http_client=http,
|
|
56
|
+
) as client:
|
|
57
|
+
response = client.evaluate(request)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The request variable is an EvaluationRequest as in the [quickstart](quickstart.md).
|
|
61
|
+
Use an HTTPS token endpoint. Access tokens are held by the supplied OAuth client.
|
|
62
|
+
|
|
63
|
+
## Asynchronous token acquisition
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import os
|
|
67
|
+
from authlib.integrations.httpx_client import AsyncOAuth2Client
|
|
68
|
+
from authzen_client import AsyncAuthZENClient
|
|
69
|
+
|
|
70
|
+
token_url = os.environ["AUTHZEN_TOKEN_URL"]
|
|
71
|
+
async with AsyncOAuth2Client(
|
|
72
|
+
client_id=os.environ["AUTHZEN_CLIENT_ID"],
|
|
73
|
+
client_secret=os.environ["AUTHZEN_CLIENT_SECRET"],
|
|
74
|
+
token_endpoint=token_url,
|
|
75
|
+
grant_type="client_credentials",
|
|
76
|
+
scope=os.environ.get("AUTHZEN_SCOPE"),
|
|
77
|
+
) as http:
|
|
78
|
+
await http.fetch_token(token_url, grant_type="client_credentials")
|
|
79
|
+
async with AsyncAuthZENClient(
|
|
80
|
+
base_url=os.environ["AUTHZEN_PDP_URL"],
|
|
81
|
+
http_client=http,
|
|
82
|
+
) as client:
|
|
83
|
+
response = await client.evaluate(request)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Authlib coordinates renewal for concurrent calls sharing one AsyncOAuth2Client.
|
|
87
|
+
The initial token request and later renewal use asynchronous HTTP operations.
|
|
88
|
+
For Client Credentials, a new access token is obtained using client credentials.
|
|
89
|
+
|
|
90
|
+
## Configured-server examples
|
|
91
|
+
|
|
92
|
+
Provide AUTHZEN_PDP_URL, AUTHZEN_TOKEN_URL, AUTHZEN_CLIENT_ID and
|
|
93
|
+
AUTHZEN_CLIENT_SECRET in your environment. AUTHZEN_SCOPE is optional and must
|
|
94
|
+
match your provider configuration. The examples check user alice reading document
|
|
95
|
+
123. Adapt these entities to your policies.
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
uv sync --extra oauth
|
|
99
|
+
uv run --extra oauth python -m examples.oauth
|
|
100
|
+
uv run --extra oauth python -m examples.async_oauth
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
These examples contact the configured servers. Unit tests exercise the same
|
|
104
|
+
Authlib integration through controlled HTTPX2 transports.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Batch evaluations
|
|
2
|
+
|
|
3
|
+
Use evaluate_batch to send several evaluations in one HTTPS request.
|
|
4
|
+
The default endpoint is /access/v1/evaluations.
|
|
5
|
+
|
|
6
|
+
## Shared defaults
|
|
7
|
+
|
|
8
|
+
```python
|
|
9
|
+
from authzen_client import (
|
|
10
|
+
Action, AuthZENClient, Evaluation, EvaluationsRequest, Resource, Subject,
|
|
11
|
+
)
|
|
12
|
+
|
|
13
|
+
request = EvaluationsRequest(
|
|
14
|
+
subject=Subject(type="user", id="alice"),
|
|
15
|
+
action=Action(name="read"),
|
|
16
|
+
evaluations=[
|
|
17
|
+
Evaluation(resource=Resource(type="document", id="123")),
|
|
18
|
+
Evaluation(resource=Resource(type="document", id="456")),
|
|
19
|
+
],
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
with AuthZENClient(base_url="https://pdp.example.com") as client:
|
|
23
|
+
response = client.evaluate_batch(request)
|
|
24
|
+
|
|
25
|
+
for decision in response.evaluations or []:
|
|
26
|
+
print(decision.decision)
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Each entry inherits omitted subject, action, resource and context from the
|
|
30
|
+
top-level request. An entry replaces a supplied entity in full. An explicitly
|
|
31
|
+
empty Context overrides a shared Context with an empty object.
|
|
32
|
+
|
|
33
|
+
Each effective evaluation must provide a subject, action and resource. Models
|
|
34
|
+
validate these requirements before sending the request.
|
|
35
|
+
|
|
36
|
+
## Execution semantics
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
from authzen_client import EvaluationsOptions
|
|
40
|
+
|
|
41
|
+
options = EvaluationsOptions(evaluations_semantic="deny_on_first_deny")
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The supported semantics are execute_all, deny_on_first_deny and
|
|
45
|
+
permit_on_first_permit. Execute all is the default. A PDP may return only the
|
|
46
|
+
evaluated prefix. The client returns that response as sent.
|
|
47
|
+
|
|
48
|
+
Results preserve request order. Additional PDP options can be passed through
|
|
49
|
+
EvaluationsOptions.model_validate with JSON-compatible extra fields.
|
|
50
|
+
|
|
51
|
+
An empty or omitted evaluations array uses the protocol's single-evaluation
|
|
52
|
+
fallback. In that case, provide top-level subject, action and resource and read
|
|
53
|
+
the response decision field.
|
|
54
|
+
|
|
55
|
+
## Errors
|
|
56
|
+
|
|
57
|
+
A general HTTP or protocol error raises an SDK exception. Individual negative
|
|
58
|
+
decisions, including PDP-provided error details in Context, remain ordered results.
|
|
59
|
+
|
|
60
|
+
For large workloads, choose batch sizes according to your PDP's documented limits.
|
|
61
|
+
Requests are sent as provided. The asynchronous client offers the same method
|
|
62
|
+
with await.
|
|
63
|
+
|
|
64
|
+
Run the bundled example.
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
uv run python -m examples.batch
|
|
68
|
+
```
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Sync and async clients
|
|
2
|
+
|
|
3
|
+
## Synchronous use
|
|
4
|
+
|
|
5
|
+
Use one client across related operations to reuse HTTP connections.
|
|
6
|
+
|
|
7
|
+
```python
|
|
8
|
+
from authzen_client import AuthZENClient
|
|
9
|
+
|
|
10
|
+
with AuthZENClient(base_url="https://pdp.example.com") as client:
|
|
11
|
+
response = client.evaluate(request)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
The request variable represents an EvaluationRequest created as in the
|
|
15
|
+
[quickstart](quickstart.md).
|
|
16
|
+
|
|
17
|
+
## Asynchronous use
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from authzen_client import AsyncAuthZENClient
|
|
21
|
+
|
|
22
|
+
async with AsyncAuthZENClient(base_url="https://pdp.example.com") as client:
|
|
23
|
+
response = await client.evaluate(request)
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Batch, search and discovery methods are awaited in the same way.
|
|
27
|
+
Use async for to consume asynchronous result iterators.
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
async with AsyncAuthZENClient(base_url="https://pdp.example.com") as client:
|
|
31
|
+
async for resource in client.iter_resources(search_request):
|
|
32
|
+
print(resource.id)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The application controls task scheduling and concurrency. For several independent
|
|
36
|
+
requests, it can use asyncio.gather and an appropriate concurrency limit.
|
|
37
|
+
|
|
38
|
+
## Your own HTTP connection
|
|
39
|
+
|
|
40
|
+
A normal client does not pass http_client. The library opens the connection and
|
|
41
|
+
closes it at the end of the with block.
|
|
42
|
+
|
|
43
|
+
Pass http_client when you already have an HTTPX2 client. The OAuth guide does
|
|
44
|
+
this with an Authlib client that gets the access token. The library sends the
|
|
45
|
+
access check through that connection and does not close it. You close it.
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
import httpx2
|
|
49
|
+
from authzen_client import AuthZENClient
|
|
50
|
+
|
|
51
|
+
with httpx2.Client() as http:
|
|
52
|
+
with AuthZENClient(base_url="https://pdp.example.com", http_client=http) as client:
|
|
53
|
+
response = client.evaluate(request)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Set authentication, transport, timeout, and connection limits on http. The
|
|
57
|
+
library rejects those arguments when http_client is set.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Configuration and discovery
|
|
2
|
+
|
|
3
|
+
## Network settings
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
import httpx2
|
|
7
|
+
from authzen_client import AuthZENClient
|
|
8
|
+
|
|
9
|
+
client = AuthZENClient(
|
|
10
|
+
base_url="https://pdp.example.com",
|
|
11
|
+
timeout=httpx2.Timeout(10.0, connect=3.0),
|
|
12
|
+
limits=httpx2.Limits(max_connections=20, max_keepalive_connections=10),
|
|
13
|
+
)
|
|
14
|
+
client.close()
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The default timeout is five seconds per network operation. Pass None to disable
|
|
18
|
+
it. Connection limits use HTTPX2 defaults unless configured. Cancellation in an
|
|
19
|
+
async caller propagates normally.
|
|
20
|
+
|
|
21
|
+
For an injected http_client, configure these values on the HTTP client itself.
|
|
22
|
+
HTTPX2 uses the operating system trust store for TLS verification by default.
|
|
23
|
+
Custom TLS and proxy configuration can be supplied through an injected client.
|
|
24
|
+
|
|
25
|
+
## Endpoint defaults
|
|
26
|
+
|
|
27
|
+
| Operation | Default path |
|
|
28
|
+
| --- | --- |
|
|
29
|
+
| Single evaluation | /access/v1/evaluation |
|
|
30
|
+
| Batch evaluations | /access/v1/evaluations |
|
|
31
|
+
| Subject Search | /access/v1/search/subject |
|
|
32
|
+
| Resource Search | /access/v1/search/resource |
|
|
33
|
+
| Action Search | /access/v1/search/action |
|
|
34
|
+
|
|
35
|
+
These are defaults from the AuthZEN HTTPS binding. A path prefix in base_url is
|
|
36
|
+
preserved when constructing endpoint URLs.
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
from authzen_client import AuthZENClient, Endpoints
|
|
40
|
+
|
|
41
|
+
client = AuthZENClient(
|
|
42
|
+
base_url="https://pdp.example.com/tenant",
|
|
43
|
+
endpoints=Endpoints(resources="/custom/search"),
|
|
44
|
+
)
|
|
45
|
+
client.close()
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The resulting resource search URL is https://pdp.example.com/tenant/custom/search.
|
|
49
|
+
Endpoints can also be absolute HTTPS URLs. Settings belong to each client.
|
|
50
|
+
|
|
51
|
+
## Discovery
|
|
52
|
+
|
|
53
|
+
Call discover explicitly, or await discover on the asynchronous client.
|
|
54
|
+
|
|
55
|
+
The client retrieves unsigned JSON metadata from the AuthZEN well-known location,
|
|
56
|
+
validates it, and requires an exact match between policy_decision_point and the
|
|
57
|
+
configured base_url. For a tenant path, the well-known segment is inserted before
|
|
58
|
+
that path as required by the protocol.
|
|
59
|
+
|
|
60
|
+
Advertised endpoint URLs take precedence over configured fallback paths. Optional
|
|
61
|
+
endpoints absent from metadata retain their fallback paths as described by the
|
|
62
|
+
HTTPS binding. A PDP may respond with an error for an unsupported operation.
|
|
63
|
+
The last valid metadata is exposed through client.metadata.
|
|
64
|
+
|
|
65
|
+
A failed discovery raises an exception and preserves the previous configuration.
|
|
66
|
+
Metadata is replaced only after validation succeeds. Signed metadata verification
|
|
67
|
+
is a possible future extension. Configure a trusted PDP and protect its metadata
|
|
68
|
+
endpoint because discovered URLs determine where subsequent requests are sent.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Development and builds
|
|
2
|
+
|
|
3
|
+
## Set up
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
uv sync --group dev
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Checks
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
uv run pytest
|
|
13
|
+
uv run ruff check src tests examples
|
|
14
|
+
uv run ruff format --check src tests examples
|
|
15
|
+
uv run ty check
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
ty checks the library, tests and examples with every diagnostic enabled as an
|
|
19
|
+
error. Strict equality and generic narrowing are enabled.
|
|
20
|
+
|
|
21
|
+
Tests use controlled HTTPX2 transports. OAuth tests exercise Authlib token
|
|
22
|
+
acquisition, renewal, errors and asynchronous concurrency. Deployed PDP/provider
|
|
23
|
+
integration and workload-specific performance still require verification.
|
|
24
|
+
|
|
25
|
+
## Build and install
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
uv build
|
|
29
|
+
python -m pip install dist/authzen_client-0.2.0-py3-none-any.whl
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The source distribution includes the documentation, examples, tests and JSON
|
|
33
|
+
fixtures. The wheel contains the library and its py.typed marker.
|
|
34
|
+
|
|
35
|
+
Project metadata and the MIT license are included in the distribution.
|
|
36
|
+
|
|
37
|
+
## Continuous integration
|
|
38
|
+
|
|
39
|
+
`.github/workflows/ci.yml` runs on every push and pull request.
|
|
40
|
+
|
|
41
|
+
- Ruff, ty, and `uv build` run on Python 3.12. The built distributions are
|
|
42
|
+
uploaded as a workflow artifact.
|
|
43
|
+
- pytest runs on Python 3.12, 3.13, and 3.14.
|
|
44
|
+
|
|
45
|
+
`.github/workflows/publish.yml` publishes to PyPI when a GitHub release is
|
|
46
|
+
published. It uses PyPI trusted publishing and the `pypi` GitHub environment.
|
|
47
|
+
Configure that environment and the PyPI project before the first release.
|
|
48
|
+
|
|
49
|
+
## Pull requests
|
|
50
|
+
|
|
51
|
+
Develop changes on a separate branch and submit them through a pull request.
|
|
52
|
+
Run the local checks before requesting review.
|
|
53
|
+
|
|
54
|
+
`.github/workflows/pr-size.yml` fails a pull request that changes more than 200
|
|
55
|
+
lines, counting additions and deletions. `uv.lock` is excluded. A push still
|
|
56
|
+
succeeds.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Errors
|
|
2
|
+
|
|
3
|
+
| Situation | Result |
|
|
4
|
+
| --- | --- |
|
|
5
|
+
| Valid HTTP 200 with decision=false | Regular denial result |
|
|
6
|
+
| Connection failure or timeout | TransportError |
|
|
7
|
+
| Unexpected HTTP status | ProtocolError |
|
|
8
|
+
| Invalid content type, encoding or response model | ProtocolError |
|
|
9
|
+
| Authentication failure during an SDK request | ProtocolError or TransportError |
|
|
10
|
+
| Invalid input model | Pydantic ValidationError |
|
|
11
|
+
| Invalid client configuration | ValueError |
|
|
12
|
+
|
|
13
|
+
TransportError and ProtocolError inherit from AuthZENError. The original cause
|
|
14
|
+
is preserved through exception chaining. ProtocolError exposes response when one
|
|
15
|
+
is available.
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
from authzen_client import AuthZENError
|
|
19
|
+
|
|
20
|
+
try:
|
|
21
|
+
response = client.evaluate(request)
|
|
22
|
+
except AuthZENError:
|
|
23
|
+
# Choose an application policy for a failed authorization check.
|
|
24
|
+
raise
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
A timeout can occur after the PDP has processed the request. The caller then has
|
|
28
|
+
an unknown result and must choose its failure policy. A protected operation may
|
|
29
|
+
be blocked while the technical error is logged or reported separately.
|
|
30
|
+
|
|
31
|
+
Initial Authlib fetch_token calls in the application raise Authlib or HTTPX2
|
|
32
|
+
exceptions directly. Failures while an injected OAuth client renews a token
|
|
33
|
+
inside an SDK operation are translated at the SDK request boundary.
|
|
34
|
+
|
|
35
|
+
The SDK performs one request per operation. Retry policy can be applied by the
|
|
36
|
+
caller using its overall deadline and the PDP's requirements. Take care with
|
|
37
|
+
credentials, tokens and sensitive attributes in logs.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# AuthZEN Client
|
|
2
|
+
|
|
3
|
+
Ask a Policy Decision Point whether a subject may perform an action on a resource.
|
|
4
|
+
The SDK validates protocol data and handles HTTPS communication. Your application
|
|
5
|
+
applies the returned decision.
|
|
6
|
+
|
|
7
|
+
The SDK implements the [AuthZEN Authorization API 1.0](https://openid.net/specs/authorization-api-1_0.html).
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- Typed Pydantic models and JSON serialization.
|
|
12
|
+
- Synchronous and asynchronous clients using HTTPX2.
|
|
13
|
+
- Single and batch evaluations, including shared defaults and short-circuit semantics.
|
|
14
|
+
- Subject, resource and action search with manual or automatic pagination.
|
|
15
|
+
- Discovery of all five API endpoints.
|
|
16
|
+
- Headers, HTTPX2 authentication and optional Authlib OAuth integration.
|
|
17
|
+
- Per-client endpoints, timeouts and connection limits.
|
|
18
|
+
|
|
19
|
+
Start with the [quickstart](quickstart.md). For migration from the HTTPX-based
|
|
20
|
+
release, see the [migration guide](migration.md).
|