{"id":5401,"library":"pymacaroons","title":"PyMacaroons","description":"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.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/ecordell/pymacaroons","tags":["security","macaroons","cryptography","authorization","authentication"],"install":[{"cmd":"pip install pymacaroons","lang":"bash","label":"Install PyMacaroons"}],"dependencies":[{"reason":"Cryptographic operations for Macaroons.","package":"pynacl","optional":false},{"reason":"Python 2 and 3 compatibility utilities.","package":"six","optional":false}],"imports":[{"note":"The primary classes Macaroon and Verifier are typically imported directly from the top-level package.","wrong":"import pymacaroons.Macaroon","symbol":"Macaroon","correct":"from pymacaroons import Macaroon"},{"note":"The primary classes Macaroon and Verifier are typically imported directly from the top-level package.","wrong":"import pymacaroons.Verifier","symbol":"Verifier","correct":"from pymacaroons import Verifier"}],"quickstart":{"code":"from pymacaroons import Macaroon, Verifier\n\n# Keys for signing macaroons are associated with some identifier for later\n# verification. This could be stored in a database, key-value store, memory, etc.\nkeys = {\n    'key-for-bob': 'asdfasdfas-a-very-secret-signing-key'\n}\n\n# Construct a Macaroon. The location and identifier will be visible after\n# construction, and identify which service and key to use to verify it.\nm = Macaroon(\n    location='cool-picture-service.example.com',\n    identifier='key-for-bob',\n    key=keys['key-for-bob']\n)\n\n# Add a caveat for the target service\nm.add_first_party_caveat('picture_id = bobs_cool_cat.jpg')\n\n# Serialize for transport in a cookie, url, OAuth token, etc\nserialized_macaroon = m.serialize()\nprint(f\"Serialized Macaroon: {serialized_macaroon}\")\n\n# --- Verification Process ---\n\n# A Verifier needs a callback to lookup keys and discharge caveats.\ndef get_key_for_identifier(identifier):\n    return keys.get(identifier)\n\ndef verify_caveat(caveat):\n    if caveat == 'picture_id = bobs_cool_cat.jpg':\n        # In a real application, you'd check against your actual data/context\n        return True\n    return False\n\n\n# Deserialize the macaroon on the receiving service\nd = Macaroon.deserialize(serialized_macaroon)\n\n# Create a Verifier instance and register the key lookup and caveat verification callbacks\nv = Verifier()\nv.satisfy_exact('picture_id = bobs_cool_cat.jpg') # Satisfy first-party caveats directly\nv.satisfy_third_party(lambda c: True) # Example: satisfy third-party caveats (not used in this example)\n\ntry:\n    # Verify the macaroon\n    verified = v.verify(d, get_key_for_identifier)\n    print(f\"Macaroon verified: {verified}\")\nexcept Exception as e:\n    print(f\"Macaroon verification failed: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Implement broader exception handling and inspect exception details to infer the cause, or contribute to improving error typing in the library.","message":"The `verify()` and `deserialize()` methods can raise general exceptions, which might make specific error handling challenging without inspecting the exception message or type.","severity":"gotcha","affected_versions":"0.13.0 and earlier (based on open issues)"},{"fix":"Ensure your application uses Python 3 for future compatibility.","message":"There 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.","severity":"deprecated","affected_versions":"Future major versions (not 0.13.0)"},{"fix":"Store and retrieve keys securely, use strong cryptographic keys, and ensure key identifiers are robustly managed.","message":"Incorrectly 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Thoroughly review the documentation and examples for `Verifier` methods. Use precise caveat matching and test all authorization paths.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor library updates for official deprecation of V1 and plan to migrate to V2 serialization when it becomes the default or mandated.","message":"There 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.","severity":"deprecated","affected_versions":"Future major versions (not 0.13.0)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}