grad_pylib
Graduate College Python common library for web application APIs and other related projects.
Additional docs in the repository root:
Authentication
Applications authenticate with Azure AD through grad_pylib.core.auth. A few things are worth
knowing before deploying a service that uses it.
Set ENVIRONMENT
ENVIRONMENT must be set explicitly for every deployment (production for production). Only
development, local and test are treated as development environments. Outside those, the
.env file is not loaded at all, so a stray dotenv file in the working directory cannot override
production configuration.
The development API key is a full bypass
When ENABLE_DEV_API_KEY is turned on, a request carrying the Api-Key header authenticates as
any role it asks for through the Api-Role header, with no token involved. This is intentional:
arbitrary impersonation is needed for local development and automated end-to-end tests. It is
guarded as follows:
ENABLE_DEV_API_KEYmust be explicitly enabled, and settings validation refuses it outside a development environment.- The request must arrive from a loopback address. Forwarding headers such as
X-Forwarded-Forare ignored, so a leaked key is not remotely exploitable. - A request that presents
Api-Keywhen the bypass is unavailable, or presents the wrong key, is rejected with a 401 and audited. It never falls through to Azure AD authentication.
Validating the requested role against the application's roles is the consuming project's
responsibility, inside its api_key_user_builder.
Audit logging
Every authentication decision is emitted to the grad_pylib.audit.auth logger as a structured
event: auth.access.granted, auth.access.denied, auth.failed, auth.token.rejected,
auth.api_key.bypass and auth.roles.overridden. Records include the subject, policy,
mechanism, effective roles, client address and request path. Note that override_loader is a
privilege-granting hook, and any override that changes the effective roles is logged.
Identities
Only illinois.edu and uillinois.edu UPNs are accepted; other domains and tokens without a UPN
claim are rejected with a 401. Only the application's own user object is stored on
request.state.user, so the raw access token is not left where an error handler or APM
integration could serialize it.
The library's contract for a user is the AuthUser protocol — a read-only effective_roles
sequence. An application can satisfy it with any immutable type it likes; BaseUser is a
ready-made implementation, not a required base class. Its fields are stored exactly as declared
(tuples, and a read-only attribute mapping), so untrusted values are normalized where they enter
the application, with parse_roles() and parse_distinct_strings(). Users are immutable — use
with_roles_override() or dataclasses.replace() to derive a modified user.
Authorization configuration
AuthConfiguration is a frozen pydantic model that is validated once, at startup:
policy_rolesentries must name roles fromvalid_roles. They are matched case-insensitively and stored in the canonical casing, so a typo or a casing mismatch is a startup error rather than an endpoint that silently never grants access.- A policy with no roles is rejected at construction rather than when its dependency is built.
- The policy mapping and its role sets are deep-frozen, so a caller holding a reference to what it passed in cannot change authorization decisions at runtime.
A policy grants access when the user holds any of its roles.
1 maintainer
Metadata
1 maintainer
Release files for grad-pylib 5.0.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| grad_pylib-5.0.5.tar.gz | 150.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| grad_pylib-5.0.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 256.6 kB
Release files / grad_pylib-5.0.5.tar.gz
| Download URL | grad_pylib-5.0.5.tar.gz |
|---|---|
| Size | 150.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1f420baff47c3d6a7b504705351fbfd43df134f71789aa859b90159822a2580f
|
|
BLAKE2b-256 checksum How to use checksums |
43d66f5c1cf94c444f3f616c502d5f61e34c40fb7f6689edb2c82f1aba95b0ae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / grad_pylib-5.0.5-py3-none-any.whl
| Download URL | grad_pylib-5.0.5-py3-none-any.whl |
|---|---|
| Size | 106.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a378705865f063ec2d6972502c6e9842cdbb51fb39c19aa2be30bc7559caec9
|
|
BLAKE2b-256 checksum How to use checksums |
cebe5badfe9bfcdbc44fcf5a6c33fa6dc818e35b916be704cb7ae6b27336be2e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
