# py_webauthn
[](https://pypi.python.org/pypi/webauthn) [](https://raw.githubusercontent.com/duo-labs/py_webauthn/master/LICENSE) 
A Python3 implementation of the server-side of the [WebAuthn API](https://www.w3.org/TR/webauthn-2/) focused on making it easy to leverage the power of WebAuthn.
This library supports all FIDO2-compliant authenticators, including security keys, Touch ID, Face ID, Windows Hello, Android biometrics...and pretty much everything else.
## Installation
This module is available on **PyPI**:
`pip install webauthn`
## Requirements
- Python 3.9 and up
## Usage
The library exposes just a few core methods on the root `webauthn` module:
- `generate_registration_options()`
- `verify_registration_response()`
- `generate_authentication_options()`
- `verify_authentication_response()`
Two additional helper methods are also exposed:
- `options_to_json()`
- `base64url_to_bytes()`
Additional data structures are available on `webauthn.helpers.structs`. These dataclasses are useful for constructing inputs to the methods above, and for providing type hinting to help ensure consistency in the shape of data being passed around.
Generally, the library makes the following assumptions about how a Relying Party implementing this library will interface with a webpage that will handle calling the WebAuthn API:
- JSON is the preferred data type for transmitting registration and authentication options from the server to the webpage to feed to `navigator.credentials.create()` and `navigator.credentials.get()` respectively.
- JSON is the preferred data type for transmitting WebAuthn responses from the browser to the server.
- Bytes are not directly transmittable in either direction as JSON, and so should be encoded to and decoded from [base64url to avoid introducing any more dependencies than those that are specified in the WebAuthn spec](https://www.w3.org/TR/webauthn-2/#sctn-dependencies).
- See the [`WebAuthnBaseModel` struct](https://github.com/duo-labs/py_webauthn/blob/master/webauthn/helpers/structs.py#L13) for more information on how this is achieved
The examples mentioned below include uses of the `options_to_json()` helper (see above) to show how easily `bytes` values in registration and authentication options can be encoded to base64url for transmission to the front end.
The examples also include demonstrations of how to pass JSON-ified responses, using base64url encoding for `ArrayBuffer` values, into `parse_registration_credential_json` and `parse_authentication_credential_json` to be automatically parsed by the methods in this library. An RP can pair this with corresponding custom front end logic, or one of several frontend-specific libraries (like [@simplewebauthn/browser](https://www.npmjs.com/package/@simplewebauthn/browser), for example) to handle encoding and decoding such values to and from JSON.
Other arguments into this library's methods that are defined as `bytes` are intended to be values stored entirely on the server. Such values can more easily exist as `bytes` without needing potentially extraneous encoding and decoding into other formats. Any encoding or decoding of such values in the name of storing them between steps in a WebAuthn ceremony is left up to the RP to achieve in an implementation-specific manner.
### Registration
See **examples/registration.py** for practical examples of using `generate_registration_options()` and `verify_registration_response()`.
You can also run these examples with the following:
```sh
# See "Development" below for venv setup instructions
venv $> python -m examples.registration
```
### Authentication
See **examples/authentication.py** for practical examples of using `generate_authentication_options()` and `verify_authentication_response()`.
You can also run these examples with the following:
```sh
# See "Development" below for venv setup instructions
venv $> python -m examples.authentication
```
## Development
### Installation
Set up a virtual environment, and then install the project's requirements:
```sh
$> python3 -m venv venv
$> source venv/bin/activate
venv $> pip install -r requirements.txt
```
### Testing
Python's unittest module can be used to execute everything in the **tests/** directory:
```sh
venv $> python -m unittest
```
Auto-watching unittests can be achieved with a tool like nodemon.
**All tests:**
```sh
venv $> nodemon --exec "python -m unittest" --ext py
```
**An individual test file:**
```sh
venv $> nodemon --exec "python -m unittest tests/test_aaguid_to_string.py" --ext py
```
### Linting and Formatting
Linting is handled via `mypy`:
```sh
venv $> python -m mypy webauthn
Success: no issues found in 52 source files
```
The entire library is formatted using `black`:
```sh
venv $> python -m black webauthn --line-length=99
All done! ✨ 🍰 ✨
52 files left unchanged.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/duo-labs/py_webauthn",
"name": "webauthn",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "webauthn fido2",
"author": "Duo Labs",
"author_email": "labs@duo.com",
"download_url": "https://files.pythonhosted.org/packages/d5/30/abcc7b664cd0a7353bdfbcbefc9f40ae7eed286aaf761660ef334d4f1ea2/webauthn-2.4.0.tar.gz",
"platform": null,
"description": "# py_webauthn\n[](https://pypi.python.org/pypi/webauthn) [](https://raw.githubusercontent.com/duo-labs/py_webauthn/master/LICENSE) \n\nA Python3 implementation of the server-side of the [WebAuthn API](https://www.w3.org/TR/webauthn-2/) focused on making it easy to leverage the power of WebAuthn.\n\nThis library supports all FIDO2-compliant authenticators, including security keys, Touch ID, Face ID, Windows Hello, Android biometrics...and pretty much everything else.\n\n## Installation\n\nThis module is available on **PyPI**:\n\n`pip install webauthn`\n\n## Requirements\n\n- Python 3.9 and up\n\n## Usage\n\nThe library exposes just a few core methods on the root `webauthn` module:\n\n- `generate_registration_options()`\n- `verify_registration_response()`\n- `generate_authentication_options()`\n- `verify_authentication_response()`\n\nTwo additional helper methods are also exposed:\n\n- `options_to_json()`\n- `base64url_to_bytes()`\n\nAdditional data structures are available on `webauthn.helpers.structs`. These dataclasses are useful for constructing inputs to the methods above, and for providing type hinting to help ensure consistency in the shape of data being passed around.\n\nGenerally, the library makes the following assumptions about how a Relying Party implementing this library will interface with a webpage that will handle calling the WebAuthn API:\n\n- JSON is the preferred data type for transmitting registration and authentication options from the server to the webpage to feed to `navigator.credentials.create()` and `navigator.credentials.get()` respectively.\n- JSON is the preferred data type for transmitting WebAuthn responses from the browser to the server.\n- Bytes are not directly transmittable in either direction as JSON, and so should be encoded to and decoded from [base64url to avoid introducing any more dependencies than those that are specified in the WebAuthn spec](https://www.w3.org/TR/webauthn-2/#sctn-dependencies).\n - See the [`WebAuthnBaseModel` struct](https://github.com/duo-labs/py_webauthn/blob/master/webauthn/helpers/structs.py#L13) for more information on how this is achieved\n\nThe examples mentioned below include uses of the `options_to_json()` helper (see above) to show how easily `bytes` values in registration and authentication options can be encoded to base64url for transmission to the front end.\n\nThe examples also include demonstrations of how to pass JSON-ified responses, using base64url encoding for `ArrayBuffer` values, into `parse_registration_credential_json` and `parse_authentication_credential_json` to be automatically parsed by the methods in this library. An RP can pair this with corresponding custom front end logic, or one of several frontend-specific libraries (like [@simplewebauthn/browser](https://www.npmjs.com/package/@simplewebauthn/browser), for example) to handle encoding and decoding such values to and from JSON.\n\nOther arguments into this library's methods that are defined as `bytes` are intended to be values stored entirely on the server. Such values can more easily exist as `bytes` without needing potentially extraneous encoding and decoding into other formats. Any encoding or decoding of such values in the name of storing them between steps in a WebAuthn ceremony is left up to the RP to achieve in an implementation-specific manner.\n\n### Registration\n\nSee **examples/registration.py** for practical examples of using `generate_registration_options()` and `verify_registration_response()`.\n\nYou can also run these examples with the following:\n\n```sh\n# See \"Development\" below for venv setup instructions\nvenv $> python -m examples.registration\n```\n\n### Authentication\n\nSee **examples/authentication.py** for practical examples of using `generate_authentication_options()` and `verify_authentication_response()`.\n\nYou can also run these examples with the following:\n\n```sh\n# See \"Development\" below for venv setup instructions\nvenv $> python -m examples.authentication\n```\n\n## Development\n\n### Installation\n\nSet up a virtual environment, and then install the project's requirements:\n\n```sh\n$> python3 -m venv venv\n$> source venv/bin/activate\nvenv $> pip install -r requirements.txt\n```\n\n### Testing\n\nPython's unittest module can be used to execute everything in the **tests/** directory:\n\n```sh\nvenv $> python -m unittest\n```\n\nAuto-watching unittests can be achieved with a tool like nodemon.\n\n**All tests:**\n```sh\nvenv $> nodemon --exec \"python -m unittest\" --ext py\n```\n\n**An individual test file:**\n```sh\nvenv $> nodemon --exec \"python -m unittest tests/test_aaguid_to_string.py\" --ext py\n```\n\n### Linting and Formatting\n\nLinting is handled via `mypy`:\n\n```sh\nvenv $> python -m mypy webauthn\nSuccess: no issues found in 52 source files\n```\n\nThe entire library is formatted using `black`:\n\n```sh\nvenv $> python -m black webauthn --line-length=99\nAll done! \u2728 \ud83c\udf70 \u2728\n52 files left unchanged.\n```\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Pythonic WebAuthn",
"version": "2.4.0",
"project_urls": {
"Download": "https://github.com/duo-labs/py_webauthn/archive/2.4.0.tar.gz",
"Homepage": "https://github.com/duo-labs/py_webauthn"
},
"split_keywords": [
"webauthn",
"fido2"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aca6ce498f971ad978d77d8d1d806538785894d3ec4b5310a5c41cf22b6ecf2e",
"md5": "07f3bc1ce9c52e25f82c7e0acf92b98a",
"sha256": "2bf59646e1ad2aed113d16a1ca90196b45f1c4d160964d6271a181e60d0d03b1"
},
"downloads": -1,
"filename": "webauthn-2.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "07f3bc1ce9c52e25f82c7e0acf92b98a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 68204,
"upload_time": "2024-12-05T00:18:53",
"upload_time_iso_8601": "2024-12-05T00:18:53.281713Z",
"url": "https://files.pythonhosted.org/packages/ac/a6/ce498f971ad978d77d8d1d806538785894d3ec4b5310a5c41cf22b6ecf2e/webauthn-2.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d530abcc7b664cd0a7353bdfbcbefc9f40ae7eed286aaf761660ef334d4f1ea2",
"md5": "0218d80f17ca68c6f8fd40112ea382f8",
"sha256": "9bb4f95c5d2377f9e1abd156ca5a23cbb5def69ef1ed60a7ab70028cc68b741e"
},
"downloads": -1,
"filename": "webauthn-2.4.0.tar.gz",
"has_sig": false,
"md5_digest": "0218d80f17ca68c6f8fd40112ea382f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 114842,
"upload_time": "2024-12-05T00:18:54",
"upload_time_iso_8601": "2024-12-05T00:18:54.989818Z",
"url": "https://files.pythonhosted.org/packages/d5/30/abcc7b664cd0a7353bdfbcbefc9f40ae7eed286aaf761660ef334d4f1ea2/webauthn-2.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-05 00:18:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "duo-labs",
"github_project": "py_webauthn",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "asn1crypto",
"specs": [
[
"==",
"1.5.1"
]
]
},
{
"name": "black",
"specs": [
[
"==",
"24.8.0"
]
]
},
{
"name": "cbor2",
"specs": [
[
"==",
"5.6.5"
]
]
},
{
"name": "cffi",
"specs": [
[
"==",
"1.17.1"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "cryptography",
"specs": [
[
"==",
"43.0.3"
]
]
},
{
"name": "mccabe",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "mypy",
"specs": [
[
"==",
"1.11.2"
]
]
},
{
"name": "mypy-extensions",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "pathspec",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"4.3.6"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
"==",
"2.12.1"
]
]
},
{
"name": "pycparser",
"specs": [
[
"==",
"2.22"
]
]
},
{
"name": "pyflakes",
"specs": [
[
"==",
"3.2.0"
]
]
},
{
"name": "pyOpenSSL",
"specs": [
[
"==",
"24.2.1"
]
]
},
{
"name": "regex",
"specs": [
[
"==",
"2024.11.6"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "toml",
"specs": [
[
"==",
"0.10.2"
]
]
},
{
"name": "tomli",
"specs": [
[
"==",
"2.0.1"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
"==",
"4.12.2"
]
]
}
],
"lcname": "webauthn"
}
JSON
