Merge pull request #226 from duo-labs/mm/more-docs

Add Authentication docs

source/_static/styles.css

@@ -7,3 +7,36 @@ div.body p, div.body dd, div.body li, div.body blockquote {
   -webkit-hyphens: none;
   hyphens: none;
 }
+
+pre {
+  padding: 11px 14px;
+}
+
+.highlight {
+  background: #EEE;
+}
+
+/* Admonitions */
+
+div.warning, div.caution, div.attention, div.important {
+  background: #fff3cd;
+  border: 1px solid #CCC;
+}
+
+div.danger, div.error {
+  background: #f9e1e4;
+  border: 1px solid #CCC;
+  box-shadow: initial;
+  -webkit-box-shadow: initial;
+  -moz-box-shadow: initial;
+}
+
+div.hint, div.tip, div.seealso {
+  background: #d6ece1;
+  border: 1px solid #CCC;
+}
+
+div.note {
+  background: #dce7fc;
+  border: 1px solid #CCC;
+}

source/advanced_use_cases.md

@@ -0,0 +1,9 @@
+# Advanced Use Cases
+
+## Passkeys
+
+Coming Soon
+
+## Conditional UI
+
+Coming Soon

source/api_reference.md

@@ -0,0 +1,3 @@
+# API Reference
+
+Coming Soon

source/authentication.md

@@ -1,9 +1,103 @@
 # Authentication
 
-Coming Soon
+WebAuthn authentication ceremonies can be broken up into two operations:
 
-## Examples
+1. Generate WebAuthn API options
+2. Verify the WebAuthn response
 
-Additional examples of the use of `generate_authentication_options` and `verify_authentication_response` are available here:
+Upon successful completion of a WebAuthn ceremony, the Relying Party can use information provided in the authenticator's response to confirm (or even determine) which user should be logged in.
 
-<https://github.com/duo-labs/py_webauthn/blob/master/examples/authentication.py>
+## Generate Options
+
+Authentication options are created using the following method:
+
+```py
+from webauthn import generate_authentication_options
+from webauthn.helpers.structs import (
+    PublicKeyCredentialDescriptor,
+    UserVerificationRequirement,
+)
+
+# Simple Options
+simple_authentication_options = generate_authentication_options(
+    rp_id="example.com",
+)
+
+# Complex Options
+complex_authentication_options = generate_authentication_options(
+    rp_id="example.com",
+    challenge=b"1234567890",
+    timeout=12000,
+    allow_credentials=[PublicKeyCredentialDescriptor(
+        id=b"1234567890",
+    )],
+    user_verification=UserVerificationRequirement.REQUIRED,
+)
+```
+
+[See the docstrings](https://github.com/duo-labs/py_webauthn/blob/2219507f483e5592ec980ec95d97a5d3563fa45b/webauthn/authentication/generate_authentication_options.py#L11-L30) for details about the various required and optional **kwargs**.
+
+The output from `generate_authentication_options()` can be passed into `webauthn.helpers.options_to_json()` to quickly convert them to a `str` value that can be sent to the browser as JSON.
+
+:::{tip}
+If you are using [@simplewebauthn/browser](overview.md#simplewebauthn-browser) in your front end code then you can pass...
+```py
+opts = options_to_json(
+    generate_authentication_options(**kwargs)
+)
+```
+...directly into its `startAuthentication(opts)` method.
+:::
+
+## Verify Response
+
+Authentication responses can be verified using the following method:
+
+```py
+from webauthn import (
+    verify_authentication_response,  # <--
+    base64url_to_bytes,
+)
+
+verification = verify_authentication_response(
+    # Demonstrating the ability to handle a stringified JSON
+    # version of the WebAuthn response
+    credential="""{
+        "id": "...",
+        "rawId": "...",
+        "response": {
+            "authenticatorData": "...",
+            "clientDataJSON": "...",
+            "signature": "...",
+            "userHandle": "..."
+        },
+        "type": "public-key",
+        "authenticatorAttachment": "cross-platform",
+        "clientExtensionResults": {}
+    }""",
+    expected_challenge=base64url_to_bytes("..."),
+    expected_rp_id="example.com",
+    expected_origin="https://example.com",
+    credential_public_key=base64url_to_bytes("..."),
+    credential_current_sign_count=0,
+    require_user_verification=True,
+)
+```
+
+[See the docstrings](https://github.com/duo-labs/py_webauthn/blob/2219507f483e5592ec980ec95d97a5d3563fa45b/webauthn/authentication/verify_authentication_response.py#L46-L79) for details about the various required and optional **kwargs**.
+
+:::{tip}
+If you are using [@simplewebauthn/browser](overview.md#simplewebauthn-browser) in your front end code then you can pass the output from `startAuthentication(opts)` directly into `verify_authentication_response(**kwargs)` as the `credential` kwarg.
+:::
+
+:::{admonition} About `userHandle`
+:class: note
+
+When present, `credential["response"]["userHandle"]` can be used to determine which account to log the user in as. This value is a **base64url-encoded string** of `options.user.id` bytes [returned by `generate_registration_options()`](registration.md#generate-options)
+:::
+
+After verifying a response, **update the following values** from `verification` above for the logged-in user's credential record in the database that matches `credential["id"]`:
+
+- `verification.new_sign_count`
+- `verification.credential_device_type`
+- `verification.credential_backed_up`

source/conf.py

@@ -19,6 +19,7 @@
 templates_path = ["_templates"]
 exclude_patterns = []
 html_copy_source = False
+pygments_style = "default"
 
 
 # -- Options for HTML output -------------------------------------------------

source/debug.md

@@ -0,0 +1,46 @@
+:::{toctree}
+:hidden:
+:::
+
+# Debug
+
+
+```{attention}
+attention
+```
+
+```{caution}
+caution
+```
+
+```{danger}
+danger
+```
+
+```{error}
+error
+```
+
+```{hint}
+hint
+```
+
+```{important}
+important
+```
+
+```{note}
+note
+```
+
+```{seealso}
+seealso
+```
+
+```{tip}
+tip
+```
+
+```{warning}
+warning
+```

source/index.md

@@ -25,5 +25,6 @@ pip install webauthn
 overview
 registration
 authentication
-passkeys
+advanced_use_cases
+api_reference
 ```

source/registration.md

@@ -65,6 +65,16 @@ complex_registration_options = generate_registration_options(
 
 The output from `generate_registration_options()` can be passed into `webauthn.helpers.options_to_json()` to quickly convert them to a `str` value that can be sent to the browser as JSON.
 
+:::{tip}
+If you are using [@simplewebauthn/browser](overview.md#simplewebauthn-browser) in your front end code then you can pass...
+```py
+opts = options_to_json(
+    generate_registration_options(**kwargs)
+)
+```
+...directly into its `startRegistration(opts)` method.
+:::
+
 ## Verify Response
 
 Registration responses can be verified using the following method:
@@ -91,21 +101,23 @@ verification = verify_registration_response(
     },
     # The value of `options.challenge` from above
     expected_challenge=base64url_to_bytes("..."),
-    expected_origin="https://example.com",
     expected_rp_id="example.com",
+    expected_origin="https://example.com",
     require_user_verification=True,
 )
 ```
 
 [See the docstrings](https://github.com/duo-labs/py_webauthn/blob/2219507f483e5592ec980ec95d97a5d3563fa45b/webauthn/registration/verify_registration_response.py#L67-L100) for details about the various required and optional **kwargs**.
 
-:::{note}
-After verifying a response, store the following values from `verification` above for the logged-in user so that the user can use this passkey later to sign in:
+:::{tip}
+If you are using [@simplewebauthn/browser](overview.md#simplewebauthn-browser) in your front end code then you can pass the output from `startRegistration(opts)` directly into `verify_registration_response(**kwargs)` as the `credential` kwarg.
+:::
+
+After verifying a response, **store the following values** from `verification` above for the logged-in user in the database so that they can use this passkey later to sign in:
 
 - `verification.credential_id`
 - `verification.credential_public_key`
 - `verification.sign_count`
 - `verification.credential_device_type`
 - `verification.credential_backed_up`
-- The value of `response.transports` from the JSON passed in as the `credential` kwarg
-:::
+- `credential["response"]["transports"]`