diff --git a/_config.yml b/_config.yml index b07f369..1beb4b7 100644 --- a/_config.yml +++ b/_config.yml @@ -9,8 +9,9 @@ author: Arnaud Dagnelies navbar-var-length: true navbar-links: + F.A.Q.: faq/index Getting Started: - - Javascript - Vanilla: https://github.com/passwordless-id/demo + - Javascript - Vanilla: getting_started/javascript_spa - Python - FastAPI: https://github.com/passwordless-id/fast-api-demo - Java - Spring Boot: https://github.com/passwordless-id/spring-boot-demo - Want more?: getting_started/want_more @@ -20,14 +21,22 @@ navbar-links: - OpenID configuration: usage/openid # - Verifying an `id_token`: usage/id_token Pricing: pricing - Webauthn: - - Introduction: protocols/webauthn/1_introduction - - Registration: protocols/webauthn/2_registration - - Authentication: protocols/webauthn/3_authentication - - Webauthn Helper Library: usage/webauthn - - Security & Privacy: protocols/webauthn/4_security - - E-Mails vs Usernames: thoughts/emails-vs-usernames - - User Guidance: thoughts/guidance + Protocols: + OAuth2: + - Introduction: protocols/oauth2/1_introduction + - /authorize: protocols/oauth2/2_authorize + - /token: protocols/oauth2/3_token + OpenID: + - Introduction: TODO + - /authorize: TODO + Webauthn: + - Introduction: protocols/webauthn/1_introduction + - Registration: protocols/webauthn/2_registration + - Authentication: protocols/webauthn/3_authentication + - Webauthn Helper Library: usage/webauthn + - Security & Privacy: protocols/webauthn/4_security + - E-Mails vs Usernames: thoughts/emails-vs-usernames + - User Guidance: thoughts/guidance Community: - Logos, icons & banners: community/logos_icons_banners - Discord: https://discord.gg/v73cHHnqzZ diff --git a/faq/TODO.md b/faq/TODO.md new file mode 100644 index 0000000..ad6d153 --- /dev/null +++ b/faq/TODO.md @@ -0,0 +1,2 @@ +Coming soon +=========== \ No newline at end of file diff --git a/faq/index.md b/faq/index.md new file mode 100644 index 0000000..98b67d7 --- /dev/null +++ b/faq/index.md @@ -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. + + diff --git a/getting_started/javascript_spa.md b/getting_started/javascript_spa.md new file mode 100644 index 0000000..624272f --- /dev/null +++ b/getting_started/javascript_spa.md @@ -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 + + + + + + Sign in with Passwordless.ID demo + + + + + + + + + + + + + +``` + + +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/connect@1.2.0/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. \ No newline at end of file diff --git a/protocols/oauth2/2_authorize.md b/protocols/oauth2/2_authorize.md index 9e9f70f..d0258a7 100644 --- a/protocols/oauth2/2_authorize.md +++ b/protocols/oauth2/2_authorize.md @@ -11,12 +11,12 @@ If the user is already authenticated and has already granted permissions, the ca | `client_id` | The unique identifier assigned to the client application by the authorization server. | | `redirect_uri` | The URI to which the authorization server will redirect the user after successful authentication and authorization. | | `response_type` | Specifies the type of response the application expects. For the Authorization Code Flow, this should be set to "code" to indicate that the application is requesting an authorization code. | -| `state` | A unique and random value generated by the client application to prevent cross-site request forgery (CSRF) attacks. | ### Optional Parameters | Parameter | Description | |----------------|-----------------------------------------------------------------------------------------------------------| +| `state` | *Recommended*. An opaque value used by the client to maintain state between the request and callback. This value is included when redirecting the user-agent back to the client. It also helps to prevent cross-site-request-forgery, where an attacker sends its own authorization code to induce the user in manipulating the wrong resource. [More information here](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12) | | `acr_values` | Specifies the level of authentication and attribute requirements. Largely unused/unsupported in practice. | | `claims` | Requests specific user claims to be included in the ID Token or UserInfo response. | | `code_challenge` | Used when implementing PKCE (Proof Key for Code Exchange) for added security. | diff --git a/protocols/oauth2/3_token.md b/protocols/oauth2/3_token.md new file mode 100644 index 0000000..eea8c1b --- /dev/null +++ b/protocols/oauth2/3_token.md @@ -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** \ No newline at end of file