-
-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #7 from passwordless-id/docs
added F.A.Q. and minor corrections
- Loading branch information
Showing
6 changed files
with
224 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| Coming soon | ||
| =========== |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| For Devs | ||
| ======== | ||
|
|
||
| Is it "production-ready"? | ||
| ------------------------- | ||
|
|
||
| Let's be honest, it is **not** *yet*. It works, it's secure, it's usable, | ||
| but it is still slightly incomplete and lacks the polish to really use it in production right now. | ||
| It's more in a proof-of-concept stage than a finished service. | ||
|
|
||
| Is it scalable? | ||
| --------------- | ||
|
|
||
| **Yes**, it is. We use so called "edge computing" and a distributed database. Basically, the code is distributed on hundreds of data-centers around the globe and the code invoked on-demand. This ensures infinite scalability, elasticity to handle bursts and optimal latency for every location. | ||
|
|
||
| Who are we? | ||
| ----------- | ||
|
|
||
| Let's not beat around the bush, the "*we*" is an "*I*". That's right, this is a solo endeavor. Who am I? | ||
| Arnaud Dagnelies, a senior software developer in the fortys, living in Germany, having programmed since high-school. | ||
|
|
||
| Why is it better than rolling your own? | ||
| --------------------------------------- | ||
|
|
||
| There are two reasons for this. The first is that it's a lot of work rolling your own. It's not just understanding and invoking the complex WebAuthn protocol. | ||
| It's managing fallbacks in case the browser does not support it, recovery mechanisms, enrolling multiple devices, managing the profile, ensuring security, updates... | ||
|
|
||
| The other is related to user comfort. Since the WebAuthn/Passkeys protocol is device/account bound, the user has to register multiple devices ...and it's no fun to do that for every website. It's much more comfortable to do it in a single place. That's why I'm convinced the "Sign in with ..." will remain more popular than "Duh, I have to register my devices here again". | ||
|
|
||
|
|
||
| How can this be free? | ||
| --------------------- | ||
|
|
||
| It is our conviction that making it publicly available is the best way to make the internet a safer place as a whole. | ||
| We want to keep it free for everyone and forever without catch. | ||
|
|
||
| However, being free is not sustainable in the long term. We need food on the plate. [Sponsors welcome!](https://github.com/sponsors/passwordless-id) | ||
|
|
||
|
|
||
| For Users | ||
| ========= | ||
|
|
||
| Is it secure? | ||
| ------------- | ||
|
|
||
| Yes, it is. Security comes from multiple aspects, but the core is the protocol. | ||
| You basically require a key stored on your device (*) and a local user verification to sign in. | ||
| This results in a two-factor authentication in a single step: | ||
|
|
||
| - Something you have | ||
| - Something you are or know (in case of biometric or PIN verification) | ||
|
|
||
| In a later stage, it's also planned to add further security using an optional third factor: your location. | ||
|
|
||
|
|
||
| (*) Is it really device bound? | ||
| ------------------------------ | ||
|
|
||
| Yes and no. The underlying WebAuthn protocol enables us to "prefer" device-bound credentials but not enforce it. | ||
| As of speaking, Windows, Android, Linux and USB keys do use device-bound credentials. | ||
| On the opposite, Apple always syncs the credentials on all your devices, like password managers. | ||
|
|
||
|
|
||
| What if I loose my device? | ||
| -------------------------- | ||
|
|
||
| Passwordless.ID enables you to register multiple devices from multiple operating systems. | ||
| Adding a device is as simple as scanning a QR code or clicking on a link received per e-mail. | ||
|
|
||
| However, *if* you loose all your registered devices *and* have no recovery mechanisms in place (like an e-mail or SMS), then yes, you inccur the risk of locking yourself out of your account. Therefore, we highly recommend to register multiple devices or fill e-mail and phone number in your profile. | ||
|
|
||
|
|
||
| What about privacy? | ||
| ------------------- | ||
|
|
||
| We do not use, resell nor exchange your data with anyone else. | ||
| Everything that you write here stays here, except if you give explicit consent to share part of your profile information with another website. | ||
| We do not track (yet) your activity (like when you sign-in and from where), but we plan to do so in the future for the sole purpose of intrusion attempts detection and boosting security even further. Like before, this data will not be sent to any third-party. | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| Getting Started - Javascript | ||
| ============================ | ||
|
|
||
| > In this tutorial, we will create a simple page with a "Sign in" button. | ||
| > Once clicked, the user will be redirected to passwordless.ID to authenticate and return back to this page and show the user profile. | ||
| - The demo can be seen here: https://passwordless-id.github.io/demo/ | ||
| - The full source code is available here: https://github.com/passwordless-id/demo | ||
|
|
||
| 1. Create an HTML page | ||
| ---------------------- | ||
|
|
||
| ```html | ||
| <!DOCTYPE html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="UTF-8" /> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> | ||
| <title>Sign in with Passwordless.ID demo</title> | ||
| <script type="module" src="sign-in-with.js" defer></script> | ||
| </head> | ||
| <body> | ||
|
|
||
| <button id="sign-in" class="btn btn-light" onclick="app.signIn()">Sign In</button> | ||
|
|
||
| <section id="profile" class="card shadow" hidden> | ||
| <div class="card-body"> | ||
| <img id="picture" style="height:100px" /> | ||
| <h3 id="nickname">Nickname</h3> | ||
| </div> | ||
| </section> | ||
|
|
||
| <button id="sign-out" class="btn btn-light" onclick="app.signOut()" hidden>Sign Out</button> | ||
|
|
||
| <footer> | ||
| <a href="https://github.com/passwordless-id/demo">See the code on GitHub</a> | ||
| </footer> | ||
| </body> | ||
| </html> | ||
| ``` | ||
|
|
||
|
|
||
| 2. Trigger the sign-in | ||
| ---------------------- | ||
|
|
||
| It uses the OAuth2 / OpenID flow using the [@passwordless-id/connect](https://github.com/passwordless-id/connect) library. | ||
|
|
||
|
|
||
| The code for that looks as follows. | ||
|
|
||
| ```js | ||
| import passwordless from 'https://unpkg.com/@passwordless-id/[email protected]/dist/connect.min.js' | ||
|
|
||
| // the information requested from the profile | ||
| const scope = 'openid avatar email' | ||
|
|
||
| function onClickSignIn() => { | ||
| // performs a redirect to let the user authenticate and/or authorize this app | ||
| passwordless.auth({ scope }) | ||
| } | ||
|
|
||
| function onClickSignOut = async () => { | ||
| // performs a redirect to let the user sign out | ||
| passwordless.logout() | ||
| } | ||
|
|
||
| async function init() { | ||
| // retrieves the user profile and `id_token` if available | ||
| const user = await passwordless.id({ scope }) | ||
| if (user.signedIn && user.scopeGranted) | ||
| showUser(user) | ||
| else | ||
| showSignIn() | ||
| } | ||
| init() | ||
| ``` | ||
|
|
||
| 3. Show the profile | ||
| ------------------- | ||
|
|
||
| The retrieved `user` has the following structure. | ||
|
|
||
| ```json | ||
| { | ||
| "signedIn": true, | ||
| "scopeGranted": true, | ||
| "id_token": "eyJ0eXAiOiJK...", | ||
| "profile": { | ||
| "nickname": "Johny", | ||
| "picture": "https://ui.passwordless.id/avatars/sam.svg", | ||
| "preferred_username": "johndoe", | ||
| "...": "...more attributes depending on requested scope" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 4. Trigger the sign-out | ||
| ----------------------- | ||
|
|
||
| 5. Using the token for API calls | ||
| -------------------------------- | ||
|
|
||
| Once you obtain the user, you can also send the `token_id` to your server API as proof of the user's authenticity. This is a Json Web Token containing a signature that can be verified by common libraries. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| RFC: https://datatracker.ietf.org/doc/html/rfc6749 | ||
|
|
||
| **Authorization code** | ||
|
|
||
| | Parameter | Description | | ||
| | ------------- | ---------------------------------------------------- | | ||
| | `grant_type` | The type of grant requested (e.g., "authorization_code", "password", "client_credentials"). | | ||
| | `redirect_uri` | The redirection URI to which the authorization server will send the user-agent after the user grants/denies consent. | | ||
| | `code` | The authorization code received from the authorization server (for the "authorization_code" grant type). | | ||
|
|
||
| **Refresh token** | ||
|
|
||
| | `client_id` | The unique identifier of the client making the request. | | ||
| | `client_secret` | The secret key or password associated with the client, used for client authentication. | | ||
| | `username` | The resource owner's username (for the "password" grant type). | | ||
| | `password` | The resource owner's password (for the "password" grant type). | | ||
| | `scope` | The scope of access requested by the client. Specifies what resources the client intends to access. | | ||
| | `refresh_token` | A refresh token used to obtain a new access token when the original access token expires (for grant types that support refresh tokens). | | ||
|
|
||
| **Other grants** |