Package: webauthn-rp
WebAuthn-RP is a Python 3 library to manage credentials that conform to theWeb 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 thereadthedocspage.OverviewThe 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 (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 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 thetypesmodule, these objects need
to be convertable into JSON for use in the browser. Thejsonifyfunction provided
in theconvertersmodule does this for all available data types and
allows one to work directly with typed Python objects. There is also aparsersmodule 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 theNavigatorinterface. The available
functions arenavigator.credentials.createandnavigator.credentials.getrespectively. These functions take a single options argument which corresponds to
the data typesCredentialCreationOptionsandCredentialRequestOptionsrespectively. 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 thebuildersmodule).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 CeremonyWebAuthn Browser API Functionnavigator.credentials.createWebAuthn-RP Options Python Data Typewebauthn_rp.types.CredentialCreationOptionsWebAuthn-RP Options Builderwebauthn_rp.builders.CredentialCreationOptionsBuilderWebAuthn-RP Options JSON Converterwebauthn_rp.converters.jsonifyWebAuthn-RP Public Key Credential Parserwebauthn_rp.parsers.parse_public_key_credentialUser Authentication CeremonyWebAuthn Browser API Functionnavigator.credentials.getWebAuthn-RP Options Python Data Typewebauthn_rp.types.CredentialRequestOptionsWebAuthn-RP Options Builderwebauthn_rp.builders.CredentialRequestOptionsBuilderWebAuthn-RP Options JSON Converterwebauthn_rp.converters.jsonifyWebAuthn-RP Public Key Credential Parserwebauthn_rp.parsers.parse_public_key_credentialNote thatparse_public_key_credentialtakes aDicttype 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 exampleapp.htmlfile to
see how this conversion is done in JavaScript.ExamplesAs mentioned, thereadthedocspage 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:Make sure you have a version of Python >= 3.6.1.Install poetry by following theguide.Open a poetry shell and install the dependencies from the project root using:$poetryshell
$poetryinstall
$pipinstallFlaskFlask-SQLAlchemyRun the Flask example from the root using::$python-mexamples.flask.appOpen a browser tolocalhost:5000and register a credential to a username.Authenticate using the same username and credential.Exit the example program.ReferencesWebAuthn StandardWebAuthn Browser APINavigator Interface