Skip to content

Commit

Permalink
Improve README formatting and clarify terminology (#34)
Browse files Browse the repository at this point in the history
  • Loading branch information
Firehed committed Oct 27, 2023
1 parent 0af23e4 commit ae5e600
Showing 1 changed file with 16 additions and 7 deletions.
23 changes: 16 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,13 @@ This also means that users do not have to manage passwords for individual websit
## Using this library: A Crash Course

This will cover the basic workflows for integrating this library to your web application.
Classes referenced in the examples may omit the `Firehed\WebAuthn` namespace prefix for brevity.

> [!NOTE]
> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
> NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
> "MAY", and "OPTIONAL" in this document are to be interpreted as
> described in BCP 14 [RFC2119] [RFC8174] when, and only when, they
> appear in all capitals, as shown here.
### Sample Code
There's a complete set of working examples in the [`examples`](examples) directory.
Expand All @@ -30,12 +36,13 @@ This **MUST** match the complete origin that users will interact with; e.g. `htt
The protocol is always required; the port must only be present if using a non-standard port and must be excluded for standard ports.

```php
$rp = new RelyingParty('https://www.example.com');
$rp = new \Firehed\WebAuthn\RelyingParty('https://www.example.com');
```

Important: WebAuthn will only work in a "secure context".
This means that the domain MUST run over `https`, with a sole exception for `localhost`.
See https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts for more info.
> [!IMPORTANT]
> WebAuthn will only work in a "secure context".
> This means that the domain MUST run over `https`, with a sole exception for `localhost`.
> See [https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts]() for more info.
### Registering a WebAuthn credential to a user

Expand Down Expand Up @@ -190,7 +197,7 @@ header('HTTP/1.1 200 OK');
Note: this workflow may be a little different if supporting [passkeys](https://developer.apple.com/passkeys/).
Updated samples will follow.

Before starting, you will need to collect the username or id of the user trying to authenticate, and retreive the user info from storage.
Before starting, you will need to collect the username or id of the user trying to authenticate, and retrieve the user info from storage.
This assumes the same schema from the previous Registration example.

1) Create an endpoint that will return a Challenge and any credentials associated with the authenticating user:
Expand Down Expand Up @@ -436,7 +443,9 @@ Similarly, for data storage, the output of `Codecs\Credential::encode()` are als
Challenges generated by your server SHOULD expire after a short amount of time.
You MAY use the `ExpiringChallenge` class for convenience (e.g. `$challenge = ExpiringChallenge::withLifetime(60);`), which will throw an exception if the specified expiration window has been exceeded.
It is RECOMMENDED that your javascript code uses the `timeout` setting (denoted in milliseconds) and matches the server-side challenge expiration, give or take a few seconds.
Note: the W3C specification recommends a timeout in the range of 15-120 seconds.

> [!NOTE]
> The W3C specification recommends a timeout in the range of 15-120 seconds.
### Error Handling

Expand Down

0 comments on commit ae5e600

Please sign in to comment.