Registry / auth-security / pymacaroons

pymacaroons

JSON →
library0.13.0pypypi✓ verified 24d ago

PyMacaroons is a Python implementation of Macaroons, a form of bearer credential similar to cookies but with embedded caveats defining authorization requirements. It is currently at version 0.13.0 and is described as stable with infrequent changes.

pip install pymacaroons
INSTALL
IMPORT
SIG · PYMACAROONS
P
pymacaroons
auth-securitypythonv0.13.0
Install
2.0s avg
Import
55ms
Disk
22MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.058s · 23.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.0s · import 0.052s · 24MB
22MB installed
● package 22MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Macaroon
from pymacaroons import Macaroon
import pymacaroons.Macaroon
The primary classes Macaroon and Verifier are typically imported directly from the top-level package.
Verifier
from pymacaroons import Verifier
import pymacaroons.Verifier
The primary classes Macaroon and Verifier are typically imported directly from the top-level package.

This quickstart demonstrates how to create a Macaroon with a first-party caveat, serialize it, and then verify it using a Verifier with appropriate callbacks for key retrieval and caveat satisfaction.

from pymacaroons import Macaroon, Verifier # Keys for signing macaroons are associated with some identifier for later # verification. This could be stored in a database, key-value store, memory, etc. keys = { 'key-for-bob': 'asdfasdfas-a-very-secret-signing-key' } # Construct a Macaroon. The location and identifier will be visible after # construction, and identify which service and key to use to verify it. m = Macaroon( location='cool-picture-service.example.com', identifier='key-for-bob', key=keys['key-for-bob'] ) # Add a caveat for the target service m.add_first_party_caveat('picture_id = bobs_cool_cat.jpg') # Serialize for transport in a cookie, url, OAuth token, etc serialized_macaroon = m.serialize() print(f"Serialized Macaroon: {serialized_macaroon}") # --- Verification Process --- # A Verifier needs a callback to lookup keys and discharge caveats. def get_key_for_identifier(identifier): return keys.get(identifier) def verify_caveat(caveat): if caveat == 'picture_id = bobs_cool_cat.jpg': # In a real application, you'd check against your actual data/context return True return False # Deserialize the macaroon on the receiving service d = Macaroon.deserialize(serialized_macaroon) # Create a Verifier instance and register the key lookup and caveat verification callbacks v = Verifier() v.satisfy_exact('picture_id = bobs_cool_cat.jpg') # Satisfy first-party caveats directly v.satisfy_third_party(lambda c: True) # Example: satisfy third-party caveats (not used in this example) try: # Verify the macaroon verified = v.verify(d, get_key_for_identifier) print(f"Macaroon verified: {verified}") except Exception as e: print(f"Macaroon verification failed: {e}")
Debug
Known issues
gotchaThe `verify()` and `deserialize()` methods can raise general exceptions, which might make specific error handling challenging without inspecting the exception message or type.
fix
Implement broader exception handling and inspect exception details to infer the cause, or contribute to improving error typing in the library.
affects: 0.13.0 and earlier (based on open issues)
deprecatedThere is an open issue to 'Remove python2 support', indicating that future major versions will likely drop compatibility with Python 2. While 0.13.0 currently supports Python 2 and 3, users should plan to migrate to Python 3.
fix
Ensure your application uses Python 3 for future compatibility.
affects: Future major versions (not 0.13.0)
gotchaIncorrectly handling or storing signing keys (e.g., hardcoding, using weak keys, or exposing them) compromises the security of your Macaroons. The `key` parameter for `Macaroon` and the `get_key_for_identifier` callback for `Verifier` are critical security points.
fix
Store and retrieve keys securely, use strong cryptographic keys, and ensure key identifiers are robustly managed.
affects: All versions
gotchaThe `Verifier`'s API, particularly for satisfying caveats, can be ambiguous if not carefully constructed. Misinterpreting how `satisfy_exact`, `satisfy_predicates`, and `satisfy_third_party` interact can lead to incorrect authorization logic.
fix
Thoroughly review the documentation and examples for `Verifier` methods. Use precise caveat matching and test all authorization paths.
affects: All versions
deprecatedThere are open issues regarding 'Remove v1 support' and 'Make v2 the default binary serialization', which suggests that Macaroon V1 serialization might be deprecated or removed in future releases, with V2 becoming standard.
fix
Monitor library updates for official deprecation of V1 and plan to migrate to V2 serialization when it becomes the default or mandated.
affects: Future major versions (not 0.13.0)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pymacaroons'
The 'pymacaroons' library is not installed in the Python environment being used, or the Python interpreter's path is not correctly configured.
fix
Install the library using pip: `pip install pymacaroons` or ensure your IDE/environment is using the correct Python interpreter where the library is installed.
MacaroonDeserializationException
This exception occurs when attempting to deserialize an invalid or malformed macaroon string, which could be due to incorrect encoding, invalid JSON structure, or other format issues.
fix
Ensure the input string passed to `Macaroon.deserialize()` is a valid macaroon string, correctly encoded (e.g., base64 or JSON as expected by the library). You can catch this specific exception for robust error handling.
MacaroonInvalidSignatureException
This specific exception is raised during macaroon verification if the macaroon's signature does not match the expected signature, often due to tampering, an incorrect root key, or an issue with third-party caveat discharge signatures.
fix
Verify that the root key provided to the `Verifier.verify()` method is correct, and that any third-party discharge macaroons are properly prepared and bound to the root macaroon. Ensure the macaroon itself has not been altered.
MacaroonVerificationFailedException
This general exception is raised when the macaroon verification process fails for any reason, including unmet first-party caveats, unfulfilled third-party caveats, or an invalid signature.
fix
Inspect the caveats added to the macaroon and ensure that the `Verifier` object has appropriate `satisfy_exact()`, `satisfy_predicates()`, or `satisfy_third_party()` functions registered to meet all conditions. Also, confirm the root key is correct and macaroons are untampered.
Upgrade
Version history
0.13.0latest on PyPI · released Feb 21, 2018
Audit
Dependencies
pynaclrequiredCryptographic operations for Macaroons.
sixrequiredPython 2 and 3 compatibility utilities.
Agent activity
8 hits · last 30 days
node
6
OpenAI (training)
1
Resources
pymacaroons — pip install pymacaroons · libregistry