Skip to main content

WebAuthn-RP is a Python 3 library to manage credentials that conform to the Web Authentication specification.

Project description






WebAuthn-RP is a Python 3 library to manage credentials that conform to the Web Authentication specification.

The following is an overview and some highlights of the library. To see the autogenerated docs and the getting started guide (which covers the Flask example under /examples/flask) please visit the readthedocs page.

Overview

The aim of this project is to enable Relying Parties to easily use public key credentials in Python backend web applications. Support is only for Python 3.x considering that Python 2.x reached its end of life in early 2020. This allows for the use of many features of Python 3 such as built-in type hinting and static type checking with mypy.

The general flow diagram for web authentication is shown in the diagrams below (from the spec):

WebAuthn Registration Flow

WebAuthn Registration Flow (Figure 1 of WebAuthn Standard)

In the case of registration, the Relying Party server must send a challenge along with information about the user that is to be registered and the specific Relying Party to which that user is associated. This library is meant to aid in the generation of messages used in step 1 and the validation performed in step 6. Steps 0 and 5 are typically handled by an application-specific client library while the routing and parsing operations of steps 1 and 6 will need to be managed by the application-specific backend although some utilities are provided. Steps 2, 3, and 4, however, are completely managed by the browser and authenticator and are not part of this library. In fact, they are mostly covered by a different specification (the Client To Authenticator Protocol, or CTAP).

Authentication is very much like registration, however some of the message formats are different and consequently the parsing and validation operations as well. The steps and how they are handled mirror those of the registration flow:

WebAuthn Registration Flow

WebAuthn Authentication Flow (Figure 2 of WebAuthn Standard)

The WebAuthn specification is designed for modern browsers and so most of the data types and functions have JavaScript and JSON in mind. Although all of the necessary data types are provided as Python objects in the types module, these objects need to be convertable into JSON for use in the browser. The jsonify function provided in the converters module does this for all available data types and allows one to work directly with typed Python objects. There is also a parsers module that provides functions that can take JSON objects of specific types of data and parse them into their Python object counterparts. Note that given JSON cannot represent raw bytes directly, bytes are base64 encoded when converted into JSON and base64 decoded when being parsed from JSON. This becomes important when passing data to the browser API functions described below because there, JavaScript ArrayBuffers are expected in place of base64 encoded strings.

Both the registration and authentication ceremonies have corresponding API functions available in the browser as part of the Navigator interface. The available functions are navigator.credentials.create and navigator.credentials.get respectively. These functions take a single options argument which corresponds to the data types CredentialCreationOptions and CredentialRequestOptions respectively. These data types have a number of configurable options that may need to be set using nested objects. To simply their construction there are builder classes available which can also provide a way to encapsulate shared options across different users (see the builders module).

All of this is summarized in the following two tables which describe some of the different functions and types that'll need to be considered when performing user registration and user authentication.

User Registration Ceremony
WebAuthn Browser API Function navigator.credentials.create
WebAuthn-RP Options Python Data Type webauthn_rp.types.CredentialCreationOptions
WebAuthn-RP Options Builder webauthn_rp.builders.CredentialCreationOptionsBuilder
WebAuthn-RP Options JSON Converter webauthn_rp.converters.jsonify
WebAuthn-RP Public Key Credential Parser webauthn_rp.parsers.parse_public_key_credential
User Authentication Ceremony
WebAuthn Browser API Function navigator.credentials.get
WebAuthn-RP Options Python Data Type webauthn_rp.types.CredentialRequestOptions
WebAuthn-RP Options Builder webauthn_rp.builders.CredentialRequestOptionsBuilder
WebAuthn-RP Options JSON Converter webauthn_rp.converters.jsonify
WebAuthn-RP Public Key Credential Parser webauthn_rp.parsers.parse_public_key_credential

Note that parse_public_key_credential takes a Dict type corresponding to a JSON-encoded version of the public key credential JavaScript object returned by the WebAuthn browser function. Data that was originally bytes is expected to have been encoded using standard base64. Please see the Flask example app.html file to see how this conversion is done in JavaScript.

Examples

As mentioned, the readthedocs page has a getting started guide that goes into depth with the Flask example, however, if you want to be able to directly run the example from this GitHub repository follow these steps after cloning this project locally:

  1. Make sure you have a version of Python >= 3.6.1.

  2. Install poetry by following the guide.

  3. Open a poetry shell and install the dependencies from the project root using:

    $ poetry shell
    $ poetry install
    $ pip install Flask Flask-SQLAlchemy
    
  4. Run the Flask example from the root using::

    $ python -m examples.flask.app
    
  5. Open a browser to localhost:5000 and register a credential to a username.

  6. Authenticate using the same username and credential.

  7. Exit the example program.

References

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

webauthn-rp-0.0.11.tar.gz (45.4 kB view details)

Uploaded Source

Built Distribution

webauthn_rp-0.0.11-py3-none-any.whl (46.9 kB view details)

Uploaded Python 3

File details

Details for the file webauthn-rp-0.0.11.tar.gz.

File metadata

  • Download URL: webauthn-rp-0.0.11.tar.gz
  • Upload date:
  • Size: 45.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.8.5

File hashes

Hashes for webauthn-rp-0.0.11.tar.gz
Algorithm Hash digest
SHA256 0fdd14dff78d86a8dd35a072bebb9c75832e0a1310387dbf92c3377cc912e4bb
MD5 ba5fc6818301da8214d8734143ab09d4
BLAKE2b-256 cb64a8efe4ed80339bfdc0e831e10ea8628e8ee4803450f502c0738a6c93e6f5

See more details on using hashes here.

File details

Details for the file webauthn_rp-0.0.11-py3-none-any.whl.

File metadata

  • Download URL: webauthn_rp-0.0.11-py3-none-any.whl
  • Upload date:
  • Size: 46.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.8.5

File hashes

Hashes for webauthn_rp-0.0.11-py3-none-any.whl
Algorithm Hash digest
SHA256 e950a6a18f836b668803eb06ab15f4969d14f338638c824bb9d4de99255ba8c3
MD5 b01be5364cf216a99b6e05163130fb72
BLAKE2b-256 5e9e80a38be6ea558253ff77f0bc106733e127785361012dc1491ad93961268e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page