/py_webauthn

A WebAuthn Python module.

Primary LanguagePythonBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

PyWebAuthn

PyPI GitHub license

PyWebAuthn is a Python module which can be used to handle WebAuthn registration and assertion. Currently, WebAuthn is supported in Firefox, Chrome, and Edge.

Installation

pip install webauthn

Usage

Generating credential options, (to be passed to navigator.credentials.create):

make_credential_options = webauthn.WebAuthnMakeCredentialOptions(
    challenge,
    rp_name,
    rp_id,
    user_id,
    username,
    display_name,
    icon_url)

Creating a WebAuthnUser object. Used during the assertion (login) process:

webauthn_user = webauthn.WebAuthnUser(
    user.id,
    user.username,
    user.display_name,
    user.icon_url,
    user.credential_id,
    user.pub_key,
    user.sign_count,
    user.rp_id)

Generating assertion options, (to be passed to navigator.credentials.get):

webauthn_assertion_options = webauthn.WebAuthnAssertionOptions(
    webauthn_user,
    challenge)

Verifying a registration response, (result of navigator.credentials.create):

webauthn_registration_response = webauthn.WebAuthnRegistrationResponse(
    RP_ID,
    ORIGIN,
    registration_response,
    challenge,
    trust_anchor_dir,
    trusted_attestation_cert_required,
    self_attestation_permitted,
    none_attestation_permitted,
    uv_required=False)  # User Verification

try:
    webauthn_credential = webauthn_registration_response.verify()
except Exception as e:
    return jsonify({'fail': 'Registration failed. Error: {}'.format(e)})

# Create User

Verifying an assertion response, (result of navigator.credentials.get):

webauthn_user = webauthn.WebAuthnUser(
    user.ukey,
    user.username,
    user.display_name,
    user.icon_url,
    user.credential_id,
    user.pub_key,
    user.sign_count,
    user.rp_id)

webauthn_assertion_response = webauthn.WebAuthnAssertionResponse(
    webauthn_user,
    assertion_response,
    challenge,
    origin,
    uv_required=False)  # User Verification

try:
    sign_count = webauthn_assertion_response.verify()
except Exception as e:
    return jsonify({'fail': 'Assertion failed. Error: {}'.format(e)})

# Update counter.
user.sign_count = sign_count

Flask Demo

There is a Flask demo available in the flask_demo directory. Follow these steps to run the Flask web app:

  1. cd flask_demo
  2. pip install -r requirements.txt
  3. python create_db.py
  4. python app.py
  5. Go to https://localhost:5000 in your web browser. Try registering and logging in with a compatible U2F or WebAuthn authenticator.
  6. Profit?

Flask Demo (Docker)

To run the Flask demo with Docker:

  1. Install Docker.
  2. docker-compose up -d
  3. Go to https://localhost:5000 in your web browser. Try registering and logging in with a compatible U2F or WebAuthn authenticator.

Demo Troubleshooting

By default, both the local and Docker demos try to run the web app using HTTPS. This may cause issues such as NET::ERR_CERT_AUTHORITY_INVALID on Chrome. To get around this issue on Chrome, you can do the following:

  1. Generate a self-signed certificate through tools like mkcert
  2. Enable requests to localhost over HTTPS through the following flag: chrome://flags/#allow-insecure-localhost.

For Firefox, you should be able to proceed to the page being served by the Flask app by doing the following:

  1. Clicking 'Advanced'
  2. Clicking 'Accept the Risk and Continue'.

Unit Tests

To run the unit tests, use the following command from the top directory:

python3 -m unittest

This will run both the py_webauthn library tests and the Flask demo tests.

Note

Currently, PyWebAuthn does not support performing the following verifications.