Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve README formatting and clarify terminology #34

Merged
merged 5 commits into from
Oct 27, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading