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"]`