diff --git a/docs/getting-started/local-development.mdx b/docs/getting-started/local-development.mdx index bc328bc838..80c4626d65 100644 --- a/docs/getting-started/local-development.mdx +++ b/docs/getting-started/local-development.mdx @@ -140,5 +140,5 @@ Using the Ory Tunnel has two key limitations currently. - Your local machine is usually available on both `localhost` and `127.0.0.1`. For the browser these two domains are different domains. Cookies set on `localhost` will not be sent in requests to `127.0.0.1` and vice versa. If you encounter cookie issues, make sure that all of your requests are sent to `localhost` and not `127.0.0.1`. -- [WebAuthn](../kratos/mfa/webauthn-fido-yubikey) does not support cross-domain use currently. We are working together with the - [W3C to figure out solutions](https://github.com/w3c/webauthn/issues/1372). +- WebAuthn does not support cross-domain use currently. + We are working together with the [W3C to figure out solutions](https://github.com/w3c/webauthn/issues/1372). diff --git a/docs/integrates-with/mfa/duo-security.mdx b/docs/integrates-with/mfa/duo-security.mdx index b17af967c3..38020a3b96 100644 --- a/docs/integrates-with/mfa/duo-security.mdx +++ b/docs/integrates-with/mfa/duo-security.mdx @@ -30,8 +30,8 @@ Ory Identities (Kratos) doesn't natively support Duo. You integrate it with an O 4. Your handler waits for the response: long-poll for push, synchronous for OTP. 5. When Duo allows, you return success. When Duo denies, you block the sign-in. -For most use cases, [native WebAuthn MFA](../../kratos/mfa/20_webauthn-fido-yubikey.mdx) is the simpler path with equivalent or -better security. +For most use cases, native WebAuthn MFA is the +simpler path with equivalent or better security. ## Notable diff --git a/docs/integrates-with/mfa/okta-verify.mdx b/docs/integrates-with/mfa/okta-verify.mdx index c1b424a63d..a6332cb1cc 100644 --- a/docs/integrates-with/mfa/okta-verify.mdx +++ b/docs/integrates-with/mfa/okta-verify.mdx @@ -29,8 +29,8 @@ You add an Ory Action on `login.after` with `can_interrupt: true`: 4. Your handler polls Okta for the result. 5. On `SUCCESS` you return success. On `REJECTED` or timeout, you block the sign-in. -For most use cases, native [WebAuthn MFA](../../kratos/mfa/20_webauthn-fido-yubikey.mdx) or TOTP is simpler. Okta Verify makes -sense primarily when it's already deployed across the workforce. +For most use cases, native WebAuthn MFA or TOTP is +simpler. Okta Verify makes sense primarily when it's already deployed across the workforce. ## Notable diff --git a/docs/integrates-with/mfa/yubikey.mdx b/docs/integrates-with/mfa/yubikey.mdx index a0678d25eb..17c4c19fc0 100644 --- a/docs/integrates-with/mfa/yubikey.mdx +++ b/docs/integrates-with/mfa/yubikey.mdx @@ -7,7 +7,7 @@ sidebar_label: YubiKey --- - + ```mdx-code-block @@ -15,7 +15,7 @@ import Admonition from '@theme/Admonition' This page is a short overview; YubiKey support is built in via WebAuthn / FIDO2. See -[Multi-factor authentication with WebAuthn](../../kratos/mfa/20_webauthn-fido-yubikey.mdx) for the full guide. +Multi-factor authentication with WebAuthn for the full guide. ``` diff --git a/docs/kratos/debug/csrf.mdx b/docs/kratos/debug/csrf.mdx deleted file mode 100644 index 2f6890f537..0000000000 --- a/docs/kratos/debug/csrf.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -id: csrf -title: CSRF troubleshooting ---- - -import useBaseUrl from "@docusaurus/useBaseUrl" -import CodeFromRemote from "@site/src/theme/CodeFromRemote" - -For general CRSF troubleshooting visit the [CSRF troubleshooting](../../troubleshooting/10_crsf.mdx). - -This document contains troubleshooting advice regarding CRSF and cookie errors specific to self-hosted Ory Identities Kratos. - -## Common issues - -### SameSite attribute - -If you run Ory Kratos in `--dev` mode, it disables `SameSite=Lax` as Google Chrome rejects all cookies that have `SameSite=Lax` -but have `secure` set to `false`. If you require `SameSite=Lax`, you need to run Ory Kratos with HTTPS and not use the `--dev` -flag. - -### Running over HTTP without `--dev` mode - -Ory Kratos' cookies have the `Secure` flag enabled by default. This means that the browser won't send the cookie unless the URL is -a HTTPS URL. If you want Ory Kratos to work with HTTP (for example on localhost) you can add the `--dev` flag: -`kratos serve --dev`. - -**Don't do this in production!** - -### Running on separate (sub)domains - -Cookies work best on the same domain. While it's possible to get cookies running on subdomains it isn't possible to do that across -Top Level Domains (TLDs). - -Make sure that your application (for example the Quickstart self service app ) and Ory Kratos Public API are available on the same -domain - preferably without subdomains. Hosting both systems and routing paths with a Reverse Proxy such as Nginx or Envoy or AWS -API Gateway is the best solution. For example, routing `https://my-website/kratos/...` to Ory Kratos and -`https://my-website/dashboard` to the SecureApp's Dashboard. Alternatively you can use piping in your app as we do in the -Quickstart guide. - -We don't recommend running them on separate subdomains, such as `https://kratos.my-website/` and `https://secureapp.my-website/`. - -To allow cookies to work across subdomains, make sure to set the domain name in the Kratos config file under -[`session.cookie.domain`](https://www.ory.com/kratos/docs/next/guides/configuring-cookies/#session-cookies). - -Running the apps on different domains won't work at all, such as `https://kratos-my-website/` and `https://secureapp-my-website/`. - -Running the services on different ports is ok, if the domain stays the same. - -### Mixing up 127.0.0.1 and localhost - -Make sure that the domain stays the same. This is also true for `127.0.0.1` and `localhost` which are both separate domains. Make -sure that you use `127.0.0.1` or `localhost` consistently across your configuration! diff --git a/docs/kratos/debug/performance-out-of-memory-password-hashing-argon2.md b/docs/kratos/debug/performance-out-of-memory-password-hashing-argon2.md deleted file mode 100644 index 5890b7d600..0000000000 --- a/docs/kratos/debug/performance-out-of-memory-password-hashing-argon2.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -id: performance-out-of-memory-password-hashing-argon2 -title: Performance problems and out of memory panics caused by password hashing ---- - -:::info - -This document only applies if you use Argon2 hashing. - -::: - -To securely check if passwords match, Ory Kratos stores the Argon2 hash of every password. This algorithm has to be tuned to match -the desired security level as well as responsiveness. Because it isn't easy to determine the exact values without trying them out, -Ory Kratos comes with a [CLI](../cli/kratos-hashers-argon2-calibrate.md) that automatically calibrates the values, following best -practices. You can read more about these best practices in our -[blog post](https://www.ory.com/choose-recommended-argon2-parameters-password-hashing). - -## Common errors - -There are some errors that indicate your Argon2 parameters need adjustment: - -1. Very slow login and registration requests, might cause network timeouts; -2. Ory Kratos fails with `fatal error: runtime: out of memory`; -3. The host environment on Minikube, Docker, or Kubernetes crashes or becomes unresponsive; - -In any of these cases, try reducing the resources used by Argon2 or increasing the resources available to Kratos. Use the -[Argon2 calibrate CLI](../cli/kratos-hashers-argon2-calibrate.md) to detect the best practice values for your server. Note that -the calibration has to be done under the exact same conditions that the server runs at. diff --git a/docs/kratos/debug/troubleshooting.md b/docs/kratos/debug/troubleshooting.md deleted file mode 100644 index fa809ca94a..0000000000 --- a/docs/kratos/debug/troubleshooting.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -id: troubleshooting -title: General troubleshooting ---- - -:::info - -Please add your troubleshooting tricks and other tips to this document, You can either open a -[discussion](https://github.com/ory/kratos/discussions) or -[edit the page directly](https://github.com/ory/docs/edit/master/docs/kratos/debug/troubleshooting.md). - -::: - -### `permission denied` / `EPERM` reading a config, schema, template, or certificate - -If `kratos serve` logs `permission denied` opening a path that is owned by the right user and has the right Unix permissions, the -[Landlock filesystem sandbox](../../security-compliance/landlock-sandbox.mdx) on Ory Network and OEL binaries is most likely -denying the access. Check the startup logs for the `Landlock filesystem sandbox is active` line and the preceding `roPaths` / -`rwDirs` lists, then either add the missing path to `security.landlock.allowed_paths` or temporarily set -`security.landlock.disabled: true` to confirm. The sandbox page has the full troubleshooting walkthrough, including how to read -kernel audit records and use `strace`. - -### `400: Bad Request` on self-service flows - -Make sure you are starting and finishing the request in one browser. Self-service browser flows need to be executed in the same -browser from start to finish! Starting the flow in Safari and completing it in Chrome won't work. API Clients like Electron, -Postman or Insomnia are browsers themselves, which can cause requests to fail. For testing purposes [cURL](https://curl.se/) is a -good choice. - -### How can I separate customers/employee data, but have them use the same login dialog - -> We want to separate our customers and employees, so we store them in different databases. But we would like to have them use the -> same login dialog for our portal. - -You can deploy Ory Kratos two times, and use the same login UI pointing to two different Kratos login endpoints - -`/login/customer` or `/login/employee`, either by having two different login routes, or by adding some logic to your login UI that -reroutes customers to `/login/customer` and employees to `/login/employee`. So you define the same login or registration UI URLs -in both of the Kratos configurations. You may need to tell your login/registration UI which Kratos it's supposed to talk to. The -instances are cheap to deploy and the databases are isolated from each other. For example something like `/login/customer` and -`/login/employee`. - -### Automatic user migration from legacy system - -> For example configure a callback to the legacy system when you can't find the corresponding user, and store the identity on -> successful legacy system response. - -An alternative to callback and custom code is fronting the legacy system with Ory OAuth2 & OpenID Connect (Ory Hydra) and then -using that as an upstream in Ory Identities (Ory Kratos). - -### Safari ITP limits cookies to 7 days - -Safari's Intelligent Tracking Prevention (ITP) limits cookies to 7 days. If you set a cookie with a longer lifespan, Safari -ignores the configured duration and expires the cookie after 7 days. This behavior can affect Ory Identities, because the cookies -used for authentication and session management may expire sooner than expected. - -This happens when an AJAX request is made from a URL that does not match the custom domain you configured for Ory. - -For example, if your login UI runs on `ui.example.com`, Ory is available at `ory.example.com` via a CNAME, and you use AJAX to -submit the login form, Safari ITP will limit the cookie lifespan to 7 days. - -To resolve this issue, you can either: - -1. Use Cloudflare for the domain that makes the AJAX request to Ory. This makes Ory and your domain appear as the same party to - Safari. -2. Change the form submission from AJAX to a normal form submission. Safari does not apply ITP restrictions to top-level - navigations. - -Read more about CNAME cloaking: https://www.cookiestatus.com/safari/#cname-cloaking diff --git a/docs/kratos/emails-sms/05_custom-email-templates.mdx b/docs/kratos/emails-sms/05_custom-email-templates.mdx index fde79541e8..11ec6da56e 100644 --- a/docs/kratos/emails-sms/05_custom-email-templates.mdx +++ b/docs/kratos/emails-sms/05_custom-email-templates.mdx @@ -64,7 +64,8 @@ To learn more about the verification flow, read When you enable the one-time code method the login flow will need to send out an email to users signing in through the one-time code method. The system will then use the `login_code.valid` template to send the login code to the user. -To learn more about login via a one-time code, read the [one-time code](../passwordless/07_code.mdx) documentation. +To learn more about login via a one-time code, read the one-time +code documentation. ```mdx-code-block @@ -75,7 +76,8 @@ To learn more about login via a one-time code, read the [one-time code](../passw When you enable the one-time code method the registration flow will need to send out an email to users signing up using the one-time code method. The system will then use the `registration_code.valid` template to send the registration code to the user. -To learn more about registration via a one-time code, read the [one-time code](../passwordless/07_code.mdx) documentation. +To learn more about registration via a one-time code, read the one-time +code documentation. ```mdx-code-block diff --git a/docs/kratos/guides/deploy-kratos-example.mdx b/docs/kratos/guides/deploy-kratos-example.mdx index df4b267159..929842a1c4 100644 --- a/docs/kratos/guides/deploy-kratos-example.mdx +++ b/docs/kratos/guides/deploy-kratos-example.mdx @@ -713,7 +713,7 @@ We need to set up secure keys and run Ory Kratos in production mode: - Fork the [Ory Kratos Node.js UI Reference](https://github.com/ory/kratos-selfservice-ui-node) or [build a custom UI in the language of your choice](../sdk/01_overview.md). -- [Add Two Factor Authentication (2FA) to your App](../mfa/01_overview.mdx) +- Add Two Factor Authentication (2FA) to your App - [Configure The Password Policy](../../concepts/password-policy.mdx) - [Integrate using webhooks](../hooks/01_configure-hooks.mdx) - Review the [Landlock filesystem sandbox](../../security-compliance/landlock-sandbox.mdx) — Ory Network and OEL binaries restrict diff --git a/docs/kratos/guides/setting-up-password-hashing-parameters.md b/docs/kratos/guides/setting-up-password-hashing-parameters.md index de85d34ce1..227d4c06ed 100644 --- a/docs/kratos/guides/setting-up-password-hashing-parameters.md +++ b/docs/kratos/guides/setting-up-password-hashing-parameters.md @@ -24,4 +24,4 @@ Head to [our blogpost](https://www.ory.com/choose-recommended-argon2-parameters- how this command and password checking in Ory Kratos works. If you encounter any problems like timeouts or out-of-memory errors, consolidate our -[troubleshooting guide](../debug/performance-out-of-memory-password-hashing-argon2.md). +[troubleshooting guide](/docs/oel/kratos/debug/performance-out-of-memory-password-hashing-argon2). diff --git a/docs/kratos/mfa/01_overview.mdx b/docs/kratos/mfa/01_overview.mdx deleted file mode 100644 index 86899a7ba0..0000000000 --- a/docs/kratos/mfa/01_overview.mdx +++ /dev/null @@ -1,162 +0,0 @@ ---- -id: overview -title: Multi-factor authentication in Ory Network -sidebar_label: Multi-factor authentication ---- - -# Overview - -Multi-factor authentication (MFA) provides an additional layer of security that helps ensure that the accounts of your users can't -be easily compromised by malicious actors. - -Nowadays, many of the passwords in use can be easily compromised because: - -- They are re-used across multiple websites and applications. -- They were leaked to the web and sold to malicious actors. -- They are considered "weak" because they are short, have obvious, derivable patterns, or contain easy-to-guess character strings. - -By enabling two-factor authentication in your project, you introduce an additional verification step that can protect user login -or self-service actions, such as updating account information or credentials, from malicious actors. For example, you might decide -to require a user to log in with two factors right at the start of the session. Alternatively, you could allow the user to start -the session by logging in with the first factor and only require the second factor at the point where the user is about to perform -a security-sensitive operation. Read more about dynamic MFA in the -[step-up authentication](../../kratos/mfa/step-up-authentication) document. - -## Available methods - -Ory offers multiple second-factor authentication methods: - -### Time-based one-time password (TOTP) - -Time-based one time passwords (TOTP) are a flexible 2FA authentication method based on a shared secret, and can be used both with -browser-based apps and native apps. Read [Time-based one-time passwords (TOTP)](./15_totp.mdx) to learn more. - -### WebAuthn - -This method uses the [Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API), also known -as WebAuthn, which allows servers to register and authenticate users using public-key cryptography. Read -[WebAuthn and FIDO2 (YubiKey)](./20_webauthn-fido-yubikey.mdx) to learn more. - -### Lookup Secrets - -Lookup Secrets, also known as Backup Codes or Recovery Codes, are a 2FA fail-safe mechanism, rather than a standalone two-factor -authentication method. They can be used to complete the second factor when users lose access to their selected 2FA method. Read -[Lookup Secrets (Recovery Codes)](./25_lookup-secrets.mdx) to learn more. - -### SMS - -SMS for MFA sends a one-time password to the user's registered mobile phone number via text message. Read the -[Code via SMS](../../../docs/kratos/mfa/mfa-via-sms) documentation to learn more. - -### Device binding - -Passwordless authentication where the private key is hardware-resident on the user's device. Read the -[Device binding](../passwordless/08_deviceauthn.mdx) documentation to learn more. - -### Email - -Email for MFA sends a one-time code to the user's registered email address. Read the -[Code via Email](../../../docs/kratos/mfa/mfa-via-sms) documentation to learn more. - -## Terminology - -Learn more about the terms and concepts used when talking about 2FA in Ory. - -### Authentication Method Reference (AMR) - -The Authentication Method Reference (AMR) is an array of authentication methods used over the lifetime of an Ory Session. - -The following methods can be present in a session: - -- `password` - When the user authenticated with their password. -- `code` - When the user authenticated by code sent via email address. -- `oidc`- When the user authenticated by signing in with a social sign-in provider. -- `totp`- When the user authenticated by entering a time-based one-time password. -- `webauthn` - When the user authenticated through a WebAuthn channel, such as OS-level biometric authentication or a hardware - token. -- `lookup_secret` - When the user entered a valid one-time recovery code. - -This is how the information is presented in the Ory Session when you fetch the session from the Ory Identities API: - -```json5 title="Sample Ory Session JSON payload" -{ - id: "6b51a3f2-6a2c-4557-90a8-4e23de7072aa", - active: true, - // ... - authenticator_assurance_level: "aal2", - authentication_methods: [ - { - method: "password", - completed_at: "2021-10-14T09:37:53.872104Z", - }, - { - method: "totp", - completed_at: "2021-10-14T09:41:16.771859Z", - }, - ], - // ... -} -``` - -If a user authenticates multiple times over the lifetime of the same session with the same method, every successful attempt will -be present in the session: - -```json5 title="Sample Ory Session JSON Payload" -{ - id: "6b51a3f2-6a2c-4557-90a8-4e23de7072aa", - active: true, - // ... - authenticator_assurance_level: "aal2", - authentication_methods: [ - { - method: "password", - completed_at: "2021-10-14T09:37:53.872104Z", - }, - { - method: "lookup_secret", - completed_at: "2021-10-14T09:41:16.771859Z", - }, - { - method: "password", - completed_at: "2021-10-14T12:00:00.134567Z", - }, - ], - // ... -} -``` - -### Authenticator Assurance Level (AAL) - -The Authenticator Assurance Level (AAL) indicates how many authentication factors the identity has completed. - -Authentication methods are classified into factors: - -| Authentication method | Factor | -| :-------------------- | :----------- | -| `password` | first | -| `oidc` | first | -| `code` | first/second | -| `totp` | second | -| `webauthn` | second | -| `lookup_secret` | second | - -:::info - -You can use `code` as first or second factor but not both at the same time. - -When you enable [passwordless authentication with WebAuthn or Passkeys](../passwordless/05_passkeys.mdx), it isn't considered as a -second authentication factor. - -::: - -The AAL parameter can take one of two values: - -- `aal1`: The user completed only the first authentication factor(s). -- `aal2`: The user completed the first and the second authentication factor(s). - -:::danger - -Completing two first authentication factors doesn't give the user `aal2`. For example, logging in with a `password` and `oidc` is -still `aal1`. - -::: diff --git a/docs/kratos/passwordless/00_overview.mdx b/docs/kratos/passwordless/00_overview.mdx deleted file mode 100644 index 7a8f6acbe5..0000000000 --- a/docs/kratos/passwordless/00_overview.mdx +++ /dev/null @@ -1,195 +0,0 @@ ---- -id: passwordless -title: Use passwordless WebAuthN to protect against phishing attacks -sidebar_label: Passwordless ---- - -Read this document if: - -- You want to learn more about passwordless authentication before deciding whether to use it in your application or starting to - code. -- You've heard about passwordless authentication as a potential solution to protect your system against phishing attacks and would - like to learn more about how Ory supports this solution. -- You'd like to avoid using a traditional password-based solution since phishing attacks have been a threat for your users in the - past. - -Passwordless authentication is intended to replace traditional password-based authentication, enabling users to verify their -identity using authenticators bound to the device they are using such as biometrics or hardware tokens. Passkeys and passwordless -authentication via WebAuthn is a technology based on the specifications published by the -[FIDO Alliance](https://fidoalliance.org/), sponsored by software companies with an interest in security technology and standards. - -## How does Ory support passwordless authentication? - -Ory's self-service flows support passwordless authentication for browser-based apps by integrating with the -[W3C Web Authentication (WebAuthn) API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) for browsers. -After enabling it in Ory, the Ory Account Experience automatically presents passwordless as an option in the registration and -login flows. When developing your own authentication UI for a browser-based app, the steps for integrating your application with -the passwordless registration and login flows are described -[in the documentation](../bring-your-own-ui/10_custom-ui-advanced-integration.mdx). - -There are two different classes of authenticators that can be used with passwordless: - -- **On-device authenticator:** an authenticator available directly on the device you are using, for example fingerprint or facial - recognition on a mobile phone. -- **External authenticator:** an authenticator provided by an external device, such as a Yubikey or a NFC device. - -The user experiences the passwordless login flow as follows. - -```mdx-code-block -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - -1. Ory's self-service login flow presents an option to log in using passwordless (below the option for signing in with a password). - ![Ory Account Experience login](./_static/ax-login-options.png) -2. To sign in with passwordless, the user enters their ID and clicks the **Sign in with security key** button. -3. The Ory Account Experience displays the sign-in preparation dialog, which gives the user time to prepare the physical device for passwordless login. The user clicks **Continue** to proceed to the next step. -4. The platform verifies the user's identity using the chosen method. -5. Login completes automatically. - - - - -1. Ory's self-service login flow presents an option to log in using passwordless. -2. To sign in with passwordless, the user enters their ID and clicks the **Sign in with security key** button. -3. The Ory Account Experience displays the sign-in preparation dialog, which gives the user time to prepare the physical device for passwordless login. The user clicks **Continue** to proceed to the next step. -4. The user chooses the external authenticator to use for sign-in (for example, a USB security key). - ![Choose external authenticator device](./_static/external-device-choose.png) -4. The platform verifies the user's identity using the chosen method. - ![Verify identity with USB security key](./_static/external-device-verify-identity.png) -5. Login completes automatically. - - - -``` - -### Authenticator options for passwordless - -Authenticators for passwordless are designed to be easy to use. For example, biometric authenticators are a popular option. - -Here are some of the current authenticator options for passwordless: - -- **On-device authenticators** - - Fingerprint (Apple TouchID, Windows Hello) - - Facial recognition (Apple FaceID, Windows Hello) - - Iris scan (Windows Hello) - - Voice recognition - - Handwriting recognition - - Device unlock -- **External authenticators** - - USB key (YubiKey) - - NFC devices - - Bluetooth Low Energy (BLE) devices - -### Resistance to phishing - -The core idea of a phishing attack is to trick a user somehow into giving up their password to the attacker, typically by luring -the user to a fake website where they are persuaded to log in, enabling the attacker to steal the password from the login -credentials. - -Passwordless authentication via WebAuthn is resistant to phishing attacks because it eliminates shared secrets during login, -verifies the domain, and prevents password reuse. - -- No shared secrets during login: WebAuthn leverages Public Key Infrastructure (PKI) to establish a unique keypair for each web - application where the public key is held by the web app and the private key is stored in a user-controlled device. - -- Domain verification: The server domain is used by the client to request the authenticator to sign the login request, ensuring - that the credential provided by the authenticator is only valid for the specific site visited. - -- No password reuse: WebAuthn prevents the vulnerability of "same password everywhere" commonly exploited in phishing attacks and - prevents impact on other web apps in case of a breach by using a unique public key for each app. - -## How does passwordless work? - -Passwordless authentication via WebAuthN achieves ease of use without compromising security too much by building on the following -insights: - -- The device you are using such as a mobile phone or PC already has built-in capabilities for verifying your identity. There is no - need to duplicate the procedure for identity verification when the device already has this capability. -- Symmetric key authentication is an existing and proven technology, which has better security characteristics than password-based - authentication. The FIDO alliance set itself the goal of automating symmetric key technology, making it more user friendly. - -Consider the following diagram, which illustrates the passwordless WebAuthN login flow. - -![Passwordless login flow](./_static/passwordless-login-flow.png) - -The main steps in the passwordless login flow are, as follows: - -1. In the frontend app, a user enters their ID and clicks the **Sign in with security key** button, which initiates the - passwordless login flow on Ory Identities. -2. Ory Identities sends a cryptographic challenge consisting of unique, random data - also known as a _nonce_ - to the frontend - app. -3. The frontend app requests verification of the user's identity by calling the WebAuthn API. WebAuthn automatically opens a - dialog in the browser, asking the user to choose an authenticator. -4. WebAuthn delegates identity verification to the browser, passing the challenge and the choice of authenticator to the browser. - The browser invokes the chosen authenticator to verify the user's identity. - - - **On-device authenticator:** If the user authenticates successfully, the platform selects the key pair that matches this app - and uses the private key to sign the challenge. - - **External authenticator:** Identity verification is delegated to the external device, which holds the private key that is - used to sign the challenge. - -5. The browser returns the cryptographic response - the signed challenge - to the frontend app, which forwards it on to Ory - Identities. Ory Identities uses the public key from the user account to verify the cryptographic response. The public key gets - stored in Ory Identities when the user signs up. - -:::note - -Neither the public key nor the private key are exposed to the app during this authentication flow. The only time the public key is -sent over the network is during the registration flow, at which point the server stores the public key in the database entry for -the user's account. The corresponding passkey (private key) never leaves the keychain on the user's device. - -::: - -## How passkeys and passwordless are related - -Passkey-based authentication and passwordless authentication are often talked about together. But if you are new to passwordless, -it's not always clear how these concepts are related. At some level, passkeys are always involved in the passwordless -authentication process, in one of the following ways: - -- **Implicit use of passkeys** - for example, when a user authenticates using fingerprint recognition or face recognition, the - platform implicitly creates a symmetric key pair, but this detail is hidden from the user. -- **Explicit use of passkeys** - for example, when a user authenticates using a USB key, which has a private key embedded in the - physical USB key. - -## Logging in with a passkey across multiple devices - -If you need to log in with a passkey across multiple devices, the following options are supported by passwordless: - -- One-off authentication using an external device -- Secure transfer of the passkey to the new device -- Platform-specific passkey sharing between devices - -### One-off authentication using an external device - -Passkeys can be used to perform login across devices. WebAuthn defines a protocol for performing passkey authentication remotely -over a secured BLE connection. - -For example, consider the case where the passkey for a particular application is stored in the Android OS on your mobile phone. If -you need to log into the application from a PC, you can use the passkey on your mobile phone to verify your identity. In this -case, you select a BLE (Bluetooth Low Energy) device as the external authenticator on the PC and, after pairing your phone with -the PC, you are prompted to verify your identity on the mobile phone. This authentication step is a one-off and the passkey is not -transferred to the PC. - -Using this remote authentication protocol, you can use your mobile phone as an external authenticator for any device that supports -WebAuthn, without leaving any trace of your credentials on that device. - -### Secure transfer of the passkey to a new device - -On the other hand, if you want to transfer passkey credentials from your mobile phone to your PC, this is also supported by the -FIDO standard. Support for this feature is not available on all platforms, however, as it is a recent addition to the standard. - -For example, consider the case where a passkey for a particular application is stored on your mobile phone, but you also want to -have this passkey available on your personal laptop, so that you don't need to take out your phone every time you log in from your -laptop. If your platform has support for this, you see an option to securely transfer the passkey to your laptop, while performing -remote authentication over BLE. If you choose to transfer the passkey, it will be stored permanently (and securely) on your -laptop's OS and in future you will be able to log in to the application directly from your laptop. - -### Platform-specific passkey sharing between devices - -If all of your devices belong to the same platform ecosystem such as Android, macOS, or Windows, you might find there is a -platform-specific mechanism available for sharing passkeys securely between devices. For example, the Apple iCloud Keychain is -capable of sharing passkeys for passwordless login across multiple Apple devices assuming these devices have access to the same -Apple iCloud account. diff --git a/docs/kratos/self-service/flows/user-login.mdx b/docs/kratos/self-service/flows/user-login.mdx index e819c21882..96e62d35ae 100644 --- a/docs/kratos/self-service/flows/user-login.mdx +++ b/docs/kratos/self-service/flows/user-login.mdx @@ -58,10 +58,12 @@ Supported login methods are - `password` for signing in with an email / username and password; - `oidc` for signing in using a social sign in provider such as Google or Facebook. Visit the [Social Sign In guide](../../social-signin/overview). -- `passkey` for signing in with a Passkey. Visit the [Passkey guide](../../passwordless/05_passkeys.mdx). -- `code` for signing in with a code via Email or SMS. Visit the [Code via Email / SMS guide](../../passwordless/07_code.mdx). +- `passkey` for signing in with a Passkey. Visit the Passkey + guide. +- `code` for signing in with a code via Email or SMS. Visit the Code + via Email / SMS guide. - `webauthn` (legacy) for signing in with Webauthn. This method is supported for backwards compatibility, use - [Passkey](../../passwordless/05_passkeys.mdx) instead. + Passkey instead. TOTP +- FIDO2/WebAuthn ::: diff --git a/docs/kratos/social-signin/93_upstream-mfa.mdx b/docs/kratos/social-signin/93_upstream-mfa.mdx index 64bb806321..d427423f6f 100644 --- a/docs/kratos/social-signin/93_upstream-mfa.mdx +++ b/docs/kratos/social-signin/93_upstream-mfa.mdx @@ -6,10 +6,10 @@ sidebar_label: Upstream MFA carry-over # Upstream MFA carry-over -When a user signs in through a social sign-in provider that already enforces multi-factor authentication (MFA), Ory can trust that -second factor instead of asking for another one. This avoids redundant prompts when your project enforces AAL2 through -[step-up authentication](../mfa/05_step-up-authentication.mdx) and the upstream identity provider has already verified the user -with a strong factor. +Your project can enforce AAL2 through step-up +authentication. When a user signs in through a social sign-in provider that already enforces multi-factor +authentication (MFA), Ory can trust that second factor instead of asking for another one. This avoids redundant prompts when the +upstream identity provider has already verified the user with a strong factor. ## How it works diff --git a/docs/network/kratos/mfa/05_step-up-authentication.mdx b/docs/network/kratos/mfa/05_step-up-authentication.mdx new file mode 100644 index 0000000000..c59e67e887 --- /dev/null +++ b/docs/network/kratos/mfa/05_step-up-authentication.mdx @@ -0,0 +1,15 @@ +--- +id: step-up-authentication +title: Use dynamic multi-factor (step-up) authentication to protect high-risk operations +sidebar_label: Dynamic Multi-Factor Authentication +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/05_step-up-authentication.mdx" + + +``` diff --git a/docs/network/kratos/mfa/15_totp.mdx b/docs/network/kratos/mfa/15_totp.mdx new file mode 100644 index 0000000000..762209e012 --- /dev/null +++ b/docs/network/kratos/mfa/15_totp.mdx @@ -0,0 +1,15 @@ +--- +id: totp +title: Multi-factor authentication with TOTP (Google Authenticator) +sidebar_label: TOTP (Google Authenticator) +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/15_totp.mdx" + + +``` diff --git a/docs/network/kratos/mfa/20_webauthn-fido-yubikey.mdx b/docs/network/kratos/mfa/20_webauthn-fido-yubikey.mdx new file mode 100644 index 0000000000..72d482f178 --- /dev/null +++ b/docs/network/kratos/mfa/20_webauthn-fido-yubikey.mdx @@ -0,0 +1,15 @@ +--- +id: webauthn-fido-yubikey +title: Multi-factor authentication with WebAuthn +sidebar_label: WebAuthn and FIDO2 (YubiKey) +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/20_webauthn-fido-yubikey.mdx" + + +``` diff --git a/docs/network/kratos/mfa/25_lookup-secrets.mdx b/docs/network/kratos/mfa/25_lookup-secrets.mdx new file mode 100644 index 0000000000..55e9ffa4cd --- /dev/null +++ b/docs/network/kratos/mfa/25_lookup-secrets.mdx @@ -0,0 +1,15 @@ +--- +id: lookup-secrets +title: Lookup Secrets - a MFA fail-safe +sidebar_label: Lookup Secrets (Recovery Codes) +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/25_lookup-secrets.mdx" + + +``` diff --git a/docs/network/kratos/mfa/30_sms.mdx b/docs/network/kratos/mfa/30_sms.mdx new file mode 100644 index 0000000000..119ad120d1 --- /dev/null +++ b/docs/network/kratos/mfa/30_sms.mdx @@ -0,0 +1,15 @@ +--- +id: mfa-via-sms +title: SMS and Email 2FA +sidebar_label: SMS and Email +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/30_sms.mdx" + + +``` diff --git a/docs/network/kratos/passwordless/00_overview.mdx b/docs/network/kratos/passwordless/00_overview.mdx new file mode 100644 index 0000000000..3a29a6dc11 --- /dev/null +++ b/docs/network/kratos/passwordless/00_overview.mdx @@ -0,0 +1,15 @@ +--- +id: passwordless +title: Use passwordless WebAuthN to protect against phishing attacks +sidebar_label: Passwordless +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/passwordless/00_overview.mdx" + + +``` diff --git a/docs/network/kratos/passwordless/05_passkeys.mdx b/docs/network/kratos/passwordless/05_passkeys.mdx new file mode 100644 index 0000000000..9f2f34a374 --- /dev/null +++ b/docs/network/kratos/passwordless/05_passkeys.mdx @@ -0,0 +1,15 @@ +--- +id: passkeys +title: Passwordless sign-in and sign-up with passkeys +sidebar_label: Passkeys & WebAuthN +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/passwordless/05_passkeys.mdx" + + +``` diff --git a/docs/network/kratos/passwordless/06_passkeys-mobile.mdx b/docs/network/kratos/passwordless/06_passkeys-mobile.mdx new file mode 100644 index 0000000000..d3a735e4d6 --- /dev/null +++ b/docs/network/kratos/passwordless/06_passkeys-mobile.mdx @@ -0,0 +1,15 @@ +--- +id: passkeys-mobile +title: Implement passkey authentication in web and mobile applications +sidebar_label: Passkeys for mobile +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/passwordless/06_passkeys-mobile.mdx" + + +``` diff --git a/docs/network/kratos/passwordless/07_code.mdx b/docs/network/kratos/passwordless/07_code.mdx new file mode 100644 index 0000000000..6c2c8196b6 --- /dev/null +++ b/docs/network/kratos/passwordless/07_code.mdx @@ -0,0 +1,15 @@ +--- +id: one-time-code +title: Passwordless authentication with email and SMS one-time code +sidebar_label: Passwordless email & SMS +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/passwordless/07_code.mdx" + + +``` diff --git a/docs/oel/kratos/debug/csrf.mdx b/docs/oel/kratos/debug/csrf.mdx new file mode 100644 index 0000000000..41d987c5d0 --- /dev/null +++ b/docs/oel/kratos/debug/csrf.mdx @@ -0,0 +1,14 @@ +--- +id: csrf +title: CSRF troubleshooting +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/debug/csrf.mdx" + + +``` diff --git a/docs/oel/kratos/debug/debug-docker-delve-ory-kratos.mdx b/docs/oel/kratos/debug/debug-docker-delve-ory-kratos.mdx new file mode 100644 index 0000000000..08f24c7622 --- /dev/null +++ b/docs/oel/kratos/debug/debug-docker-delve-ory-kratos.mdx @@ -0,0 +1,14 @@ +--- +id: debug-docker-delve-ory-kratos +title: Debugging Ory Kratos in Docker with Delve +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/debug/debug-docker-delve-ory-kratos.mdx" + + +``` diff --git a/docs/oel/kratos/debug/performance-out-of-memory-password-hashing-argon2.mdx b/docs/oel/kratos/debug/performance-out-of-memory-password-hashing-argon2.mdx new file mode 100644 index 0000000000..c2c6834200 --- /dev/null +++ b/docs/oel/kratos/debug/performance-out-of-memory-password-hashing-argon2.mdx @@ -0,0 +1,14 @@ +--- +id: performance-out-of-memory-password-hashing-argon2 +title: Performance problems and out of memory panics caused by password hashing +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/debug/performance-out-of-memory-password-hashing-argon2.md" + + +``` diff --git a/docs/oel/kratos/debug/troubleshooting.mdx b/docs/oel/kratos/debug/troubleshooting.mdx new file mode 100644 index 0000000000..d1e63b25a6 --- /dev/null +++ b/docs/oel/kratos/debug/troubleshooting.mdx @@ -0,0 +1,14 @@ +--- +id: troubleshooting +title: General troubleshooting +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/debug/troubleshooting.md" + + +``` diff --git a/docs/oel/kratos/mfa/05_step-up-authentication.mdx b/docs/oel/kratos/mfa/05_step-up-authentication.mdx new file mode 100644 index 0000000000..c59e67e887 --- /dev/null +++ b/docs/oel/kratos/mfa/05_step-up-authentication.mdx @@ -0,0 +1,15 @@ +--- +id: step-up-authentication +title: Use dynamic multi-factor (step-up) authentication to protect high-risk operations +sidebar_label: Dynamic Multi-Factor Authentication +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/05_step-up-authentication.mdx" + + +``` diff --git a/docs/oel/kratos/mfa/15_totp.mdx b/docs/oel/kratos/mfa/15_totp.mdx new file mode 100644 index 0000000000..762209e012 --- /dev/null +++ b/docs/oel/kratos/mfa/15_totp.mdx @@ -0,0 +1,15 @@ +--- +id: totp +title: Multi-factor authentication with TOTP (Google Authenticator) +sidebar_label: TOTP (Google Authenticator) +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/15_totp.mdx" + + +``` diff --git a/docs/oel/kratos/mfa/20_webauthn-fido-yubikey.mdx b/docs/oel/kratos/mfa/20_webauthn-fido-yubikey.mdx new file mode 100644 index 0000000000..72d482f178 --- /dev/null +++ b/docs/oel/kratos/mfa/20_webauthn-fido-yubikey.mdx @@ -0,0 +1,15 @@ +--- +id: webauthn-fido-yubikey +title: Multi-factor authentication with WebAuthn +sidebar_label: WebAuthn and FIDO2 (YubiKey) +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/20_webauthn-fido-yubikey.mdx" + + +``` diff --git a/docs/oel/kratos/mfa/25_lookup-secrets.mdx b/docs/oel/kratos/mfa/25_lookup-secrets.mdx new file mode 100644 index 0000000000..55e9ffa4cd --- /dev/null +++ b/docs/oel/kratos/mfa/25_lookup-secrets.mdx @@ -0,0 +1,15 @@ +--- +id: lookup-secrets +title: Lookup Secrets - a MFA fail-safe +sidebar_label: Lookup Secrets (Recovery Codes) +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/25_lookup-secrets.mdx" + + +``` diff --git a/docs/oel/kratos/mfa/30_sms.mdx b/docs/oel/kratos/mfa/30_sms.mdx new file mode 100644 index 0000000000..119ad120d1 --- /dev/null +++ b/docs/oel/kratos/mfa/30_sms.mdx @@ -0,0 +1,15 @@ +--- +id: mfa-via-sms +title: SMS and Email 2FA +sidebar_label: SMS and Email +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/mfa/30_sms.mdx" + + +``` diff --git a/docs/oel/kratos/passwordless/00_overview.mdx b/docs/oel/kratos/passwordless/00_overview.mdx new file mode 100644 index 0000000000..3a29a6dc11 --- /dev/null +++ b/docs/oel/kratos/passwordless/00_overview.mdx @@ -0,0 +1,15 @@ +--- +id: passwordless +title: Use passwordless WebAuthN to protect against phishing attacks +sidebar_label: Passwordless +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/passwordless/00_overview.mdx" + + +``` diff --git a/docs/oel/kratos/passwordless/05_passkeys.mdx b/docs/oel/kratos/passwordless/05_passkeys.mdx new file mode 100644 index 0000000000..9f2f34a374 --- /dev/null +++ b/docs/oel/kratos/passwordless/05_passkeys.mdx @@ -0,0 +1,15 @@ +--- +id: passkeys +title: Passwordless sign-in and sign-up with passkeys +sidebar_label: Passkeys & WebAuthN +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/passwordless/05_passkeys.mdx" + + +``` diff --git a/docs/oel/kratos/passwordless/06_passkeys-mobile.mdx b/docs/oel/kratos/passwordless/06_passkeys-mobile.mdx new file mode 100644 index 0000000000..d3a735e4d6 --- /dev/null +++ b/docs/oel/kratos/passwordless/06_passkeys-mobile.mdx @@ -0,0 +1,15 @@ +--- +id: passkeys-mobile +title: Implement passkey authentication in web and mobile applications +sidebar_label: Passkeys for mobile +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/passwordless/06_passkeys-mobile.mdx" + + +``` diff --git a/docs/oel/kratos/passwordless/07_code.mdx b/docs/oel/kratos/passwordless/07_code.mdx new file mode 100644 index 0000000000..6c2c8196b6 --- /dev/null +++ b/docs/oel/kratos/passwordless/07_code.mdx @@ -0,0 +1,15 @@ +--- +id: one-time-code +title: Passwordless authentication with email and SMS one-time code +sidebar_label: Passwordless email & SMS +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/passwordless/07_code.mdx" + + +``` diff --git a/docs/oss/kratos/debug/csrf.mdx b/docs/oss/kratos/debug/csrf.mdx new file mode 100644 index 0000000000..41d987c5d0 --- /dev/null +++ b/docs/oss/kratos/debug/csrf.mdx @@ -0,0 +1,14 @@ +--- +id: csrf +title: CSRF troubleshooting +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/debug/csrf.mdx" + + +``` diff --git a/docs/oss/kratos/debug/debug-docker-delve-ory-kratos.mdx b/docs/oss/kratos/debug/debug-docker-delve-ory-kratos.mdx new file mode 100644 index 0000000000..08f24c7622 --- /dev/null +++ b/docs/oss/kratos/debug/debug-docker-delve-ory-kratos.mdx @@ -0,0 +1,14 @@ +--- +id: debug-docker-delve-ory-kratos +title: Debugging Ory Kratos in Docker with Delve +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/debug/debug-docker-delve-ory-kratos.mdx" + + +``` diff --git a/docs/oss/kratos/debug/performance-out-of-memory-password-hashing-argon2.mdx b/docs/oss/kratos/debug/performance-out-of-memory-password-hashing-argon2.mdx new file mode 100644 index 0000000000..c2c6834200 --- /dev/null +++ b/docs/oss/kratos/debug/performance-out-of-memory-password-hashing-argon2.mdx @@ -0,0 +1,14 @@ +--- +id: performance-out-of-memory-password-hashing-argon2 +title: Performance problems and out of memory panics caused by password hashing +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/debug/performance-out-of-memory-password-hashing-argon2.md" + + +``` diff --git a/docs/oss/kratos/debug/troubleshooting.mdx b/docs/oss/kratos/debug/troubleshooting.mdx new file mode 100644 index 0000000000..d1e63b25a6 --- /dev/null +++ b/docs/oss/kratos/debug/troubleshooting.mdx @@ -0,0 +1,14 @@ +--- +id: troubleshooting +title: General troubleshooting +--- + + + + + +```mdx-code-block +import MyPartial from "@site/src/components/Shared/kratos/debug/troubleshooting.md" + + +``` diff --git a/docs/troubleshooting/10_crsf.mdx b/docs/troubleshooting/10_crsf.mdx index fc7bbd3e5b..4061e92429 100644 --- a/docs/troubleshooting/10_crsf.mdx +++ b/docs/troubleshooting/10_crsf.mdx @@ -132,5 +132,5 @@ accessed using a normal browser request by clicking a link or redirecting the en ## Further reading -Read [this document](../kratos/debug/csrf.mdx) for CRSF troubleshooting specific to self-hosted Ory Kratos Identity Server -instances. +Read this document for CRSF +troubleshooting specific to self-hosted Ory Kratos Identity Server instances. diff --git a/sidebars-network.ts b/sidebars-network.ts index 180cda8fc3..c173e4410e 100644 --- a/sidebars-network.ts +++ b/sidebars-network.ts @@ -198,10 +198,10 @@ const networkSidebar = [ items: [ "kratos/concepts/credentials", "kratos/concepts/credentials/username-email-password", - "kratos/passwordless/passwordless", - "kratos/passwordless/one-time-code", - "kratos/passwordless/passkeys", - "kratos/passwordless/passkeys-mobile", + "network/kratos/passwordless/passwordless", + "network/kratos/passwordless/one-time-code", + "network/kratos/passwordless/passkeys", + "network/kratos/passwordless/passkeys-mobile", "kratos/passwordless/deviceauthn", "kratos/organizations/organizations", "kratos/emails-sms/custom-email-templates", @@ -308,11 +308,11 @@ const networkSidebar = [ id: "network/kratos/mfa-overview", }, items: [ - "kratos/mfa/lookup-secrets", - "kratos/mfa/totp", - "kratos/mfa/webauthn-fido-yubikey", - "kratos/mfa/mfa-via-sms", - "kratos/mfa/step-up-authentication", + "network/kratos/mfa/lookup-secrets", + "network/kratos/mfa/totp", + "network/kratos/mfa/webauthn-fido-yubikey", + "network/kratos/mfa/mfa-via-sms", + "network/kratos/mfa/step-up-authentication", "identities/get-started/mfa", ], }, diff --git a/sidebars-oel.ts b/sidebars-oel.ts index 914904c89c..54cb4338b9 100644 --- a/sidebars-oel.ts +++ b/sidebars-oel.ts @@ -72,6 +72,31 @@ const oelSidebar = [ "kratos/reference/configuration-editor", ], }, + { + type: "category", + label: "Authentication", + items: [ + "oel/kratos/passwordless/passwordless", + "oel/kratos/passwordless/one-time-code", + "oel/kratos/passwordless/passkeys", + "oel/kratos/passwordless/passkeys-mobile", + { + type: "category", + label: "Multi-factor authentication", + link: { + type: "doc", + id: "oel/kratos/mfa-overview", + }, + items: [ + "oel/kratos/mfa/lookup-secrets", + "oel/kratos/mfa/totp", + "oel/kratos/mfa/webauthn-fido-yubikey", + "oel/kratos/mfa/mfa-via-sms", + "oel/kratos/mfa/step-up-authentication", + ], + }, + ], + }, { type: "category", label: "Guides", @@ -94,7 +119,7 @@ const oelSidebar = [ items: [ { type: "autogenerated", - dirName: "kratos/debug", + dirName: "oel/kratos/debug", }, ], }, diff --git a/sidebars-oss.ts b/sidebars-oss.ts index 1091962b4f..ce1f9e7f32 100644 --- a/sidebars-oss.ts +++ b/sidebars-oss.ts @@ -102,7 +102,7 @@ const ossSidebar = [ items: [ { type: "autogenerated", - dirName: "kratos/debug", + dirName: "oss/kratos/debug", }, ], }, diff --git a/src/components/Shared/kratos/01_mfa-overview.mdx b/src/components/Shared/kratos/01_mfa-overview.mdx index 4b3ccb79ca..a6e70a8808 100644 --- a/src/components/Shared/kratos/01_mfa-overview.mdx +++ b/src/components/Shared/kratos/01_mfa-overview.mdx @@ -12,14 +12,15 @@ Nowadays, many of the passwords in use can be easily compromised because: By enabling two-factor authentication in your project, you introduce an additional verification step that can protect user login or self-service actions, such as updating account information or credentials, from malicious -actors. -For example, you might decide to require a user to log in with two factors right -at the start of the session. Alternatively, you could allow the user to start -the session by logging in with the first factor and only require the second -factor at the point where the user is about to perform a security-sensitive -operation. Read more about dynamic MFA in the -[step-up authentication](../../../../docs/kratos/mfa/step-up-authentication) -document. +actors. For example, you might decide to require a user to log in with two +factors right at the start of the session. Alternatively, you could allow the +user to start the session by logging in with the first factor and only require +the second factor at the point where the user is about to perform a +security-sensitive operation. + +Read the +step-up +authentication guide to learn more about dynamic MFA. ## Available methods @@ -29,34 +30,57 @@ Ory offers multiple second-factor authentication methods: Time-based one time passwords (TOTP) are a flexible 2FA authentication method based on a shared secret, and can be used both with browser-based apps and -native apps. Read -[Time-based one-time passwords (TOTP)](../../../../docs/kratos/mfa/totp) to -learn more. +native apps. + +Read +Time-based +one-time passwords (TOTP) to learn more. ### WebAuthn This method uses the [Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API), also known as WebAuthn, which allows servers to register and authenticate users -using public-key cryptography. Read -[WebAuthn and FIDO2 (YubiKey)](../../../../docs/kratos/mfa/webauthn-fido-yubikey) -to learn more. +using public-key cryptography. + +Read +WebAuthn +and FIDO2 (YubiKey) to learn more. ### Lookup Secrets Lookup Secrets, also known as Backup Codes or Recovery Codes, are a 2FA fail-safe mechanism, rather than a standalone two-factor authentication method. They can be used to complete the second factor when users lose access to their -selected 2FA method. Read -[Lookup Secrets (Recovery Codes)](../../../../docs/kratos/mfa/lookup-secrets) to -learn more. +selected 2FA method. + +Read +Lookup +Secrets (Recovery Codes) to learn more. ### SMS SMS for MFA sends a one-time password to the user's registered mobile phone -number via text message. Read the -[Code via SMS](../../../../docs/kratos/mfa/mfa-via-sms) documentation to learn -more. +number via text message. + +Read the +Code +via SMS documentation to learn more. + +### Device authentication + +Passwordless authentication where the private key is hardware-resident on the +user's device. Read the +[Device authentication](/docs/kratos/passwordless/deviceauthn) documentation to +learn more. + +### Email + +Email for MFA sends a one-time code to the user's registered email address. + +Read the +Code +via Email documentation to learn more. ## Terminology @@ -70,6 +94,7 @@ used over the lifetime of an Ory Session. The following methods can be present in a session: - `password` - When the user authenticated with their password. +- `code` - When the user authenticated by code sent via email address. - `oidc`- When the user authenticated by signing in with a social sign-in provider. - `totp`- When the user authenticated by entering a time-based one-time @@ -135,19 +160,23 @@ factors the identity has completed. Authentication methods are classified into factors: -| Authentication method | Factor | -| :-------------------- | :----- | -| `password` | first | -| `oidc` | first | -| `totp` | second | -| `webauthn` | second | -| `lookup_secret` | second | +| Authentication method | Factor | +| :-------------------- | :----------- | +| `password` | first | +| `oidc` | first | +| `code` | first/second | +| `totp` | second | +| `webauthn` | second | +| `lookup_secret` | second | :::info -When you enable -[passwordless authentication with WebAuthn or Passkeys](../../../../docs/kratos/passwordless/passkeys), -it isn't considered as a second authentication factor. +You can use `code` as first or second factor but not both at the same time. + +Enabling +passwordless +authentication with WebAuthn or Passkeys isn't considered a +second authentication factor. ::: diff --git a/src/components/Shared/kratos/debug/csrf.mdx b/src/components/Shared/kratos/debug/csrf.mdx new file mode 100644 index 0000000000..8a66e50fea --- /dev/null +++ b/src/components/Shared/kratos/debug/csrf.mdx @@ -0,0 +1,57 @@ +import useBaseUrl from "@docusaurus/useBaseUrl" +import CodeFromRemote from "@site/src/theme/CodeFromRemote" + +For general CRSF troubleshooting visit the +[CSRF troubleshooting](/docs/troubleshooting/csrf). + +This document contains troubleshooting advice regarding CRSF and cookie errors +specific to self-hosted Ory Identities Kratos. + +## Common issues + +### SameSite attribute + +If you run Ory Kratos in `--dev` mode, it disables `SameSite=Lax` as Google +Chrome rejects all cookies that have `SameSite=Lax` but have `secure` set to +`false`. If you require `SameSite=Lax`, you need to run Ory Kratos with HTTPS +and not use the `--dev` flag. + +### Running over HTTP without `--dev` mode + +Ory Kratos' cookies have the `Secure` flag enabled by default. This means that +the browser won't send the cookie unless the URL is a HTTPS URL. If you want Ory +Kratos to work with HTTP (for example on localhost) you can add the `--dev` +flag: `kratos serve --dev`. + +**Don't do this in production!** + +### Running on separate (sub)domains + +Cookies work best on the same domain. While it's possible to get cookies running +on subdomains it isn't possible to do that across Top Level Domains (TLDs). + +Make sure that your application (for example the Quickstart self service app ) +and Ory Kratos Public API are available on the same domain - preferably without +subdomains. Hosting both systems and routing paths with a Reverse Proxy such as +Nginx or Envoy or AWS API Gateway is the best solution. For example, routing +`https://my-website/kratos/...` to Ory Kratos and `https://my-website/dashboard` +to the SecureApp's Dashboard. Alternatively you can use piping in your app as we +do in the Quickstart guide. + +We don't recommend running them on separate subdomains, such as +`https://kratos.my-website/` and `https://secureapp.my-website/`. + +To allow cookies to work across subdomains, make sure to set the domain name in +the Kratos config file under +[`session.cookie.domain`](https://www.ory.com/kratos/docs/next/guides/configuring-cookies/#session-cookies). + +Running the apps on different domains won't work at all, such as +`https://kratos-my-website/` and `https://secureapp-my-website/`. + +Running the services on different ports is ok, if the domain stays the same. + +### Mixing up 127.0.0.1 and localhost + +Make sure that the domain stays the same. This is also true for `127.0.0.1` and +`localhost` which are both separate domains. Make sure that you use `127.0.0.1` +or `localhost` consistently across your configuration! diff --git a/docs/kratos/debug/debug-docker-delve-ory-kratos.mdx b/src/components/Shared/kratos/debug/debug-docker-delve-ory-kratos.mdx similarity index 62% rename from docs/kratos/debug/debug-docker-delve-ory-kratos.mdx rename to src/components/Shared/kratos/debug/debug-docker-delve-ory-kratos.mdx index 2921f62934..db3251ffe6 100644 --- a/docs/kratos/debug/debug-docker-delve-ory-kratos.mdx +++ b/src/components/Shared/kratos/debug/debug-docker-delve-ory-kratos.mdx @@ -1,19 +1,18 @@ ---- -id: debug-docker-delve-ory-kratos -title: Debugging Ory Kratos in Docker with Delve ---- - -Very often, there is a need to debug Kratos being deployed as a Docker image. To support this, Kratos ships with a couple of -files: +Very often, there is a need to debug Kratos being deployed as a Docker image. To +support this, Kratos ships with a couple of files: - The `Dockerfile-debug` file, which you can find in the `.docker` directory. -- The `docker-compose.template.dbg` file, which you can find in the same directory. This file defines a template for a service, - one would like to debug in Docker -- and a supplementary `debug-entrypoint.sh` skript, located in the `script` directory. - -Actually, these files don't include any Kratos specifica and thus can be used for any Golang based project. As you already could -infer, this support is meant to be used in a docker-compose setup as described below. You can however run it as a standalone -Docker container as well. You can find some information on how to achieve this at the end of this document. +- The `docker-compose.template.dbg` file, which you can find in the same + directory. This file defines a template for a service, one would like to debug + in Docker +- and a supplementary `debug-entrypoint.sh` skript, located in the `script` + directory. + +Actually, these files don't include any Kratos specifica and thus can be used +for any Golang based project. As you already could infer, this support is meant +to be used in a docker-compose setup as described below. You can however run it +as a standalone Docker container as well. You can find some information on how +to achieve this at the end of this document. ## As part of a docker-compose setup @@ -86,8 +85,8 @@ services: - file-containing-all-required-configuration.env ``` -To enable debugging of Kratos without changing the above docker-compose file, you can do the following (from the docker-compose -directory): +To enable debugging of Kratos without changing the above docker-compose file, +you can do the following (from the docker-compose directory): ```bash SERVICE_NAME=kratos SERVICE_ROOT=../kratos REMOTE_DEBUGGING_PORT=9999 envsubst < ../kratos/.docker/docker-compose.template.dbg \ @@ -95,34 +94,43 @@ SERVICE_NAME=kratos SERVICE_ROOT=../kratos REMOTE_DEBUGGING_PORT=9999 envsubst < docker-compose -f docker-compose.yaml -f docker-compose.kratos.tmp up --build -d kratos ``` -The first line will create an overwrite docker-compose file to have a debug configuration for the kratos service. The second line -will start a debug container by +The first line will create an overwrite docker-compose file to have a debug +configuration for the kratos service. The second line will start a debug +container by - mounting your `kratos` directory into the resulting Docker container, - downloading Delve, - building Kratos inside the container, -- starting it in Delve with the arguments, you've defined in your regular docker-compose file - in the example above, this would - be `serve -c /etc/config/kratos/kratos.yml --watch-courier --dev` - and +- starting it in Delve with the arguments, you've defined in your regular + docker-compose file - in the example above, this would be + `serve -c /etc/config/kratos/kratos.yml --watch-courier --dev` - and - watching for changes on any go file within the mounted code base. -Each time you change a .go file, the Delve process will be stopped, Kratos will be recompiled and Delve will be started again. -With other words, you'll have to re-connect with your debugger again after each change. +Each time you change a .go file, the Delve process will be stopped, Kratos will +be recompiled and Delve will be started again. With other words, you'll have to +re-connect with your debugger again after each change. -As you can see from the above usage, the `docker-compose.template.dbg` template expects the following variables to be defined: +As you can see from the above usage, the `docker-compose.template.dbg` template +expects the following variables to be defined: -- `SERVICE_ROOT` - the root directory of the service to be started in the debug mode. +- `SERVICE_ROOT` - the root directory of the service to be started in the debug + mode. - `SERVICE_NAME` - the name of the service from the docker-compose file. -- `REMOTE_DEBUGGING_PORT` - the host port, the Delve listening port should be exposed as. This is the port you should connect your - remote debugger to. +- `REMOTE_DEBUGGING_PORT` - the host port, the Delve listening port should be + exposed as. This is the port you should connect your remote debugger to. -If you run docker-compose this way, the container run with debugging enabled will wait until the debugger connects. If your IDE -supports remote debugging, set host to `localhost` and port to the value, you've used for `REMOTE_DEBUGGING_PORT` in your remote -debugging configuration. +If you run docker-compose this way, the container run with debugging enabled +will wait until the debugger connects. If your IDE supports remote debugging, +set host to `localhost` and port to the value, you've used for +`REMOTE_DEBUGGING_PORT` in your remote debugging configuration. ## As a standalone Docker container -If you just would like to start Kratos in a container in debug mode, you can just use the `Dockerfile-debug` file instead of the -regular `Dockerfile`. Make however sure your build context in the root directory of Kratos and not the `.docker` directory. In -your IDE the debug configuration has to reference that file. In addition, you'll have to expose the Delve service port 40000 under -the port 8000, as well as the actual port of the service, you'll like to access from your host, configure the bind mounts and set -the run options to `--security-opt="apparmor=unconfined" --cap-add=SYS_PTRACE`. +If you just would like to start Kratos in a container in debug mode, you can +just use the `Dockerfile-debug` file instead of the regular `Dockerfile`. Make +however sure your build context in the root directory of Kratos and not the +`.docker` directory. In your IDE the debug configuration has to reference that +file. In addition, you'll have to expose the Delve service port 40000 under the +port 8000, as well as the actual port of the service, you'll like to access from +your host, configure the bind mounts and set the run options to +`--security-opt="apparmor=unconfined" --cap-add=SYS_PTRACE`. diff --git a/src/components/Shared/kratos/debug/performance-out-of-memory-password-hashing-argon2.md b/src/components/Shared/kratos/debug/performance-out-of-memory-password-hashing-argon2.md new file mode 100644 index 0000000000..4245be2b40 --- /dev/null +++ b/src/components/Shared/kratos/debug/performance-out-of-memory-password-hashing-argon2.md @@ -0,0 +1,29 @@ +:::info + +This document only applies if you use Argon2 hashing. + +::: + +To securely check if passwords match, Ory Kratos stores the Argon2 hash of every +password. This algorithm has to be tuned to match the desired security level as +well as responsiveness. Because it isn't easy to determine the exact values +without trying them out, Ory Kratos comes with a +[CLI](/docs/kratos/cli/kratos-hashers-argon2-calibrate) that automatically +calibrates the values, following best practices. You can read more about these +best practices in our +[blog post](https://www.ory.com/choose-recommended-argon2-parameters-password-hashing). + +## Common errors + +There are some errors that indicate your Argon2 parameters need adjustment: + +1. Very slow login and registration requests, might cause network timeouts; +2. Ory Kratos fails with `fatal error: runtime: out of memory`; +3. The host environment on Minikube, Docker, or Kubernetes crashes or becomes + unresponsive; + +In any of these cases, try reducing the resources used by Argon2 or increasing +the resources available to Kratos. Use the +[Argon2 calibrate CLI](/docs/kratos/cli/kratos-hashers-argon2-calibrate) to +detect the best practice values for your server. Note that the calibration has +to be done under the exact same conditions that the server runs at. diff --git a/src/components/Shared/kratos/debug/troubleshooting.md b/src/components/Shared/kratos/debug/troubleshooting.md new file mode 100644 index 0000000000..46719a3eb4 --- /dev/null +++ b/src/components/Shared/kratos/debug/troubleshooting.md @@ -0,0 +1,80 @@ +:::info + +Please add your troubleshooting tricks and other tips to this document, You can +either open a [discussion](https://github.com/ory/kratos/discussions) or +[edit the page directly](https://github.com/ory/docs/edit/master/src/components/Shared/kratos/debug/troubleshooting.md). + +::: + +### `permission denied` / `EPERM` reading a config, schema, template, or certificate + +If `kratos serve` logs `permission denied` opening a path that is owned by the +right user and has the right Unix permissions, the +[Landlock filesystem sandbox](/docs/security-compliance/landlock-sandbox) on Ory +Network and OEL binaries is most likely denying the access. Check the startup +logs for the `Landlock filesystem sandbox is active` line and the preceding +`roPaths` / `rwDirs` lists, then either add the missing path to +`security.landlock.allowed_paths` or temporarily set +`security.landlock.disabled: true` to confirm. The sandbox page has the full +troubleshooting walkthrough, including how to read kernel audit records and use +`strace`. + +### `400: Bad Request` on self-service flows + +Make sure you are starting and finishing the request in one browser. +Self-service browser flows need to be executed in the same browser from start to +finish! Starting the flow in Safari and completing it in Chrome won't work. API +Clients like Electron, Postman or Insomnia are browsers themselves, which can +cause requests to fail. For testing purposes [cURL](https://curl.se/) is a good +choice. + +### How can I separate customers/employee data, but have them use the same login dialog + +> We want to separate our customers and employees, so we store them in different +> databases. But we would like to have them use the same login dialog for our +> portal. + +You can deploy Ory Kratos two times, and use the same login UI pointing to two +different Kratos login endpoints - `/login/customer` or `/login/employee`, +either by having two different login routes, or by adding some logic to your +login UI that reroutes customers to `/login/customer` and employees to +`/login/employee`. So you define the same login or registration UI URLs in both +of the Kratos configurations. You may need to tell your login/registration UI +which Kratos it's supposed to talk to. The instances are cheap to deploy and the +databases are isolated from each other. For example something like +`/login/customer` and `/login/employee`. + +### Automatic user migration from legacy system + +> For example configure a callback to the legacy system when you can't find the +> corresponding user, and store the identity on successful legacy system +> response. + +An alternative to callback and custom code is fronting the legacy system with +Ory OAuth2 & OpenID Connect (Ory Hydra) and then using that as an upstream in +Ory Identities (Ory Kratos). + +### Safari ITP limits cookies to 7 days + +Safari's Intelligent Tracking Prevention (ITP) limits cookies to 7 days. If you +set a cookie with a longer lifespan, Safari ignores the configured duration and +expires the cookie after 7 days. This behavior can affect Ory Identities, +because the cookies used for authentication and session management may expire +sooner than expected. + +This happens when an AJAX request is made from a URL that does not match the +custom domain you configured for Ory. + +For example, if your login UI runs on `ui.example.com`, Ory is available at +`ory.example.com` via a CNAME, and you use AJAX to submit the login form, Safari +ITP will limit the cookie lifespan to 7 days. + +To resolve this issue, you can either: + +1. Use Cloudflare for the domain that makes the AJAX request to Ory. This makes + Ory and your domain appear as the same party to Safari. +2. Change the form submission from AJAX to a normal form submission. Safari does + not apply ITP restrictions to top-level navigations. + +Read more about CNAME cloaking: +https://www.cookiestatus.com/safari/#cname-cloaking diff --git a/docs/kratos/mfa/05_step-up-authentication.mdx b/src/components/Shared/kratos/mfa/05_step-up-authentication.mdx similarity index 61% rename from docs/kratos/mfa/05_step-up-authentication.mdx rename to src/components/Shared/kratos/mfa/05_step-up-authentication.mdx index e6c907ba83..72de3d8547 100644 --- a/docs/kratos/mfa/05_step-up-authentication.mdx +++ b/src/components/Shared/kratos/mfa/05_step-up-authentication.mdx @@ -1,11 +1,3 @@ ---- -id: step-up-authentication -title: Use dynamic multi-factor (step-up) authentication to protect high-risk operations -sidebar_label: Dynamic Multi-Factor Authentication ---- - -# Step-up authentication - ```mdx-code-block import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -14,11 +6,14 @@ import BrowserWindow from "@site/src/theme/BrowserWindow" You can set up multi-factor authentication to work in one of two models: -- **Strict**, where secured operations always require the highest Authenticator Assurance Level (AAL). -- **Lax**, where the secured operations require only the `aal1` Authenticator Assurance Level (AAL). +- **Strict**, where secured operations always require the highest Authenticator + Assurance Level (AAL). +- **Lax**, where the secured operations require only the `aal1` Authenticator + Assurance Level (AAL). -In Ory Network, the default multi-factor authentication enforcement model is **Strict**. This means that high-risk operations via -self-service endpoints, such as updating user settings, require step-up authentication by default. +In Ory Network, the default multi-factor authentication enforcement model is +**Strict**. This means that high-risk operations via self-service endpoints, +such as updating user settings, require step-up authentication by default. You can set the required authentication model for these operations/endpoints: @@ -32,14 +27,15 @@ You can set the required authentication model for these operations/endpoints: ``` -To change the multi-factor authentication enforcement to Lax and allow users to sign in or access user settings without -authenticating with the second factor, go to and use the switches in the **General Settings** -section. +To change the multi-factor authentication enforcement to Lax and allow users to +sign in or access user settings without authenticating with the second factor, +go to and use the switches in the **General +Settings** section. ```mdx-code-block -![Step-up authentication settings in Ory Console](../_static/mfa/10.png) +![Step-up authentication settings in Ory Console](./_static/10.png) ``` @@ -81,8 +77,8 @@ Follow these steps to adjust the settings in the Ory Network using the Ory CLI: :::tip - Use `aal1` for the Lax model and `highest_available` for the Strict model. The default value in Ory Network is - `highest_available`. + Use `aal1` for the Lax model and `highest_available` for the Strict model. + The default value in Ory Network is `highest_available`. ::: @@ -99,12 +95,13 @@ Follow these steps to adjust the settings in the Ory Network using the Ory CLI: ## Trigger Dynamic Multi-Factor authentication -To protect your application's sensitive functions - like accessing payment details, an order history, or private content - you can -make users complete a second authentication factor in their current session by initiating a new login flow using one of these -endpoints with the `aal` parameter set to `aal2`: +To protect your application's sensitive functions - like accessing payment +details, an order history, or private content - you can make users complete a +second authentication factor in their current session by initiating a new login +flow using one of these endpoints with the `aal` parameter set to `aal2`: -- [`/self-service/login/browser`](../../reference/api.mdx#operation/initializeSelfServiceLoginFlowForBrowsers) -- [`/self-service/login/api`](../../reference/api.mdx#operation/initializeSelfServiceLoginFlowWithoutBrowser) +- [`/self-service/login/browser`](/docs/reference/api#operation/initializeSelfServiceLoginFlowForBrowsers) +- [`/self-service/login/api`](/docs/reference/api#operation/initializeSelfServiceLoginFlowWithoutBrowser) For example: @@ -115,8 +112,8 @@ For example: :::note -If the Ory Session has `aal2` already, this will error. In that case, you can request to refresh the session using the second -factor: +If the Ory Session has `aal2` already, this will error. In that case, you can +request to refresh the session using the second factor: ```shell /self-service/login/browser?refresh=true&aal=aal2 @@ -129,11 +126,14 @@ When the user successfully provides their configured second factor: - The method, for example `totp`, is added to the Ory Session. - Ory Session Authenticator Assurance Level (AAL) is set to `aal2`. -- The `authenticated_at` time is set to the time when the user provides the second factor. +- The `authenticated_at` time is set to the time when the user provides the + second factor. ## Trust upstream MFA from a social sign-in provider -If your project uses social sign-in and the upstream identity provider already enforces MFA, Ory can trust the upstream factor -instead of asking the user to complete a second factor again. Configure `aal2_acr_values` and `aal2_amr_values` on the social -sign-in provider to allowlist the upstream `acr` and `amr` claim values that should mark the resulting Ory session as AAL2. See -[Upstream MFA carry-over](../social-signin/93_upstream-mfa.mdx) for details. +If your project uses social sign-in and the upstream identity provider already +enforces MFA, Ory can trust the upstream factor instead of asking the user to +complete a second factor again. Configure `aal2_acr_values` and +`aal2_amr_values` on the social sign-in provider to allowlist the upstream `acr` +and `amr` claim values that should mark the resulting Ory session as AAL2. See +[Upstream MFA carry-over](/docs/kratos/social-signin/upstream-mfa) for details. diff --git a/docs/kratos/mfa/15_totp.mdx b/src/components/Shared/kratos/mfa/15_totp.mdx similarity index 67% rename from docs/kratos/mfa/15_totp.mdx rename to src/components/Shared/kratos/mfa/15_totp.mdx index e43d4f37fe..1e4a10845f 100644 --- a/docs/kratos/mfa/15_totp.mdx +++ b/src/components/Shared/kratos/mfa/15_totp.mdx @@ -1,26 +1,23 @@ ---- -id: totp -title: Multi-factor authentication with TOTP (Google Authenticator) -sidebar_label: TOTP (Google Authenticator) ---- - -# Time-based one-time passwords (TOTP) - ```mdx-code-block import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import BrowserWindow from "@site/src/theme/BrowserWindow" ``` -Time-based one-time passwords are codes made up of digits, that are valid for a short amount of time, usually 30 seconds or less. -Users generate these passwords with companion apps such as [Google Authenticator](https://g.co/kgs/YgRFR5) or -[FreeOTP](https://freeotp.github.io/) and enter them when asked to provide their second authentication factor. +Time-based one-time passwords are codes made up of digits, that are valid for a +short amount of time, usually 30 seconds or less. Users generate these passwords +with companion apps such as [Google Authenticator](https://g.co/kgs/YgRFR5) or +[FreeOTP](https://freeotp.github.io/) and enter them when asked to provide their +second authentication factor. -When accessing resources protected with the second-factor requirement, the paired application generates a one-time password that -expires after a certain time. Users must input this password before it expires to authenticate and perform the protected actions. +When accessing resources protected with the second-factor requirement, the +paired application generates a one-time password that expires after a certain +time. Users must input this password before it expires to authenticate and +perform the protected actions. -You can enable Time-Based One-Time Password (TOTP) authentication in Ory Identities (Kratos) to allow users to perform 2FA with -TOTP apps such as Google Authenticator, LastPass, or [FreeOTP](https://freeotp.github.io/). +You can enable Time-Based One-Time Password (TOTP) authentication in Ory +Identities (Kratos) to allow users to perform 2FA with TOTP apps such as Google +Authenticator, LastPass, or [FreeOTP](https://freeotp.github.io/). When enabled, users can pair a TOTP app to their account: @@ -33,25 +30,27 @@ The example screenshot is captured using the Ory Account Experience. ```mdx-code-block - ![TOTP linking in Ory Account Experience](../_static/mfa/1.png) + ![TOTP linking in Ory Account Experience](./_static/1.png) ``` -When attempting to perform actions while having 2FA enabled, users are asked to enter the short code in the Ory Identities UI. -This proves that they have access to their chosen second factor. +When attempting to perform actions while having 2FA enabled, users are asked to +enter the short code in the Ory Identities UI. This proves that they have access +to their chosen second factor. ```mdx-code-block -![2FA with Google Authenticator](../_static/mfa/2.png) +![2FA with Google Authenticator](./_static/2.png) ``` :::info -In this example, the user identifier (email - `alice@example.com`) is used. To learn how to enable this behavior, read +In this example, the user identifier (email - `alice@example.com`) is used. To +learn how to enable this behavior, read [Distinguishing identities requesting TOTP](#distinguishing-identities-requesting-totp). ::: @@ -65,25 +64,27 @@ In this example, the user identifier (email - `alice@example.com`) is used. To l 1. Go to . 2. In the **TOTP Authenticator App** section, use the switch to enable TOTP. -3. Define the name of the requesting party in the **Display Name**. The users see this name in the TOTP application when getting a - one-time password. +3. Define the name of the requesting party in the **Display Name**. The users + see this name in the TOTP application when getting a one-time password. 4. Click **Save**. ```mdx-code-block - ![TOTP setup in Ory Console](../_static/mfa/3.png) + ![TOTP setup in Ory Console](./_static/3.png) ``` -5. After TOTP has been enabled for the Ory Network project, each user is responsible for enabling TOTP in their own account by - pairing their account with a TOTP app. +5. After TOTP has been enabled for the Ory Network project, each user is + responsible for enabling TOTP in their own account by pairing their account + with a TOTP app. :::note - In the Ory Account Experience, users are not automatically prompted to enable TOTP for their accounts. To enable TOTP, users - must sign in to their accounts and go to the **Authenticator App** section of the **Account Settings** page. + In the Ory Account Experience, users are not automatically prompted to enable + TOTP for their accounts. To enable TOTP, users must sign in to their accounts + and go to the **Authenticator App** section of the **Account Settings** page. ::: @@ -105,7 +106,8 @@ In this example, the user identifier (email - `alice@example.com`) is used. To l ory get identity-config --project --workspace --format yaml > identity-config.yaml ``` -2. Find `totp` in `selfservice/methods`, set `enabled` to `true`, and define the `issuer`: +2. Find `totp` in `selfservice/methods`, set `enabled` to `true`, and define the + `issuer`: ```yaml title="identity-config.yaml" selfservice: @@ -125,13 +127,15 @@ In this example, the user identifier (email - `alice@example.com`) is used. To l ory update identity-config --project --workspace --file identity-config.yaml ``` -4. After TOTP has been enabled for the Ory Network project, each user is responsible for enabling TOTP in their own account by - pairing their account with a TOTP app. +4. After TOTP has been enabled for the Ory Network project, each user is + responsible for enabling TOTP in their own account by pairing their account + with a TOTP app. :::note - In the Ory Account Experience, users are not automatically prompted to enable TOTP for their accounts. To enable TOTP, users - must sign in to their accounts and go to the **Authenticator App** section of the **Account Settings** page. + In the Ory Account Experience, users are not automatically prompted to enable + TOTP for their accounts. To enable TOTP, users must sign in to their accounts + and go to the **Authenticator App** section of the **Account Settings** page. ::: @@ -142,14 +146,16 @@ In this example, the user identifier (email - `alice@example.com`) is used. To l ## Custom identity schema -By default, the identity schema is preconfigured to display the user's email address when requesting the TOTP short code. If you -are working with a custom identity schema, however, you must ensure that the identity schema is properly configured to work with -TOTP. +By default, the identity schema is preconfigured to display the user's email +address when requesting the TOTP short code. If you are working with a custom +identity schema, however, you must ensure that the identity schema is properly +configured to work with TOTP. ### Distinguishing identities requesting TOTP -To help users distinguish which identity the registered TOTP code belongs to, add a `totp` section to the identity schema section -of the trait you want to show up in the TOTP app. +To help users distinguish which identity the registered TOTP code belongs to, +add a `totp` section to the identity schema section of the trait you want to +show up in the TOTP app. For example, to select the user's email address as the identifier for TOTP: @@ -195,7 +201,8 @@ When writing end-to-end (E2E) tests for TOTP implementation in your app, ## Identity credentials -When the user enables TOTP, Ory adds the following entries to the `credentials` object of the associated Identity: +When the user enables TOTP, Ory adds the following entries to the `credentials` +object of the associated Identity: ```yaml credentials: diff --git a/docs/kratos/mfa/20_webauthn-fido-yubikey.mdx b/src/components/Shared/kratos/mfa/20_webauthn-fido-yubikey.mdx similarity index 73% rename from docs/kratos/mfa/20_webauthn-fido-yubikey.mdx rename to src/components/Shared/kratos/mfa/20_webauthn-fido-yubikey.mdx index c70f5f8005..c3cefb1e2b 100644 --- a/docs/kratos/mfa/20_webauthn-fido-yubikey.mdx +++ b/src/components/Shared/kratos/mfa/20_webauthn-fido-yubikey.mdx @@ -1,31 +1,30 @@ ---- -id: webauthn-fido-yubikey -title: Multi-factor authentication with WebAuthn -sidebar_label: WebAuthn and FIDO2 (YubiKey) ---- - -# WebAuthn and FIDO2 (YubiKey) - ```mdx-code-block import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; ``` -WebAuthn uses the [Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) of the -browser, which allows servers to register and authenticate users using public-key cryptography. +WebAuthn uses the +[Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) +of the browser, which allows servers to register and authenticate users using +public-key cryptography. There are two main categories of authenticators you can use with WebAuthn: -- **On-device authenticators**: platform-based biometric authentication protocols, such as TouchID, FaceID, Windows Hello, or - Android Biometric Authentication -- **External authenticators**: NFC devices, USB keys, or Bluetooth Low Energy (BLE) devices, for example a +- **On-device authenticators**: platform-based biometric authentication + protocols, such as TouchID, FaceID, Windows Hello, or Android Biometric + Authentication +- **External authenticators**: NFC devices, USB keys, or Bluetooth Low Energy + (BLE) devices, for example a [YubiKey](https://www.yubico.com/why-yubico/how-the-yubikey-works/). -When accessing resources protected with the second-factor requirement, the browser presents the user with a prompt asking to -confirm their identity with their configured authentication method, for example, by touching the fingerprint reader. +When accessing resources protected with the second-factor requirement, the +browser presents the user with a prompt asking to confirm their identity with +their configured authentication method, for example, by touching the fingerprint +reader. -You can enable WebAuthn in the Ory Identities (Kratos) to allow users to perform 2FA with physical devices such as USB keys or -OS-level biometric authentication protocols, such as TouchID. +You can enable WebAuthn in the Ory Identities (Kratos) to allow users to perform +2FA with physical devices such as USB keys or OS-level biometric authentication +protocols, such as TouchID. When users trigger the WebAuthn process, the web browser displays a prompt: @@ -34,22 +33,26 @@ import BrowserWindow from "@site/src/theme/BrowserWindow" -![WebAuthn prompt in Google Chrome](../_static/mfa/4.png) +![WebAuthn prompt in Google Chrome](./_static/4.png) ``` -The look of the prompt depends on the web browser. The screenshot shows a Google Chrome prompt. +The look of the prompt depends on the web browser. The screenshot shows a Google +Chrome prompt. ## Limitations - WebAuthn is a browser-only standard. It doesn't work with native mobile apps. -- WebAuthn is limited to one domain and does not work in a local environment when using CNAME / Ory Tunnel. WebAuthn uses an - `https://origin` URL as part of the client-server challenge/response mechanism. This mechanism allows a single URL as the - origin. To learn more, read this [WebAuthn discussion and on GitHub](https://github.com/w3c/webauthn/issues/1372). +- WebAuthn is limited to one domain and does not work in a local environment + when using CNAME / Ory Tunnel. WebAuthn uses an `https://origin` URL as part + of the client-server challenge/response mechanism. This mechanism allows a + single URL as the origin. To learn more, read this + [WebAuthn discussion and on GitHub](https://github.com/w3c/webauthn/issues/1372). - Implementing WebAuthn in your own UI can be challenging. Check out the - [reference implementations](../bring-your-own-ui/20_configure-ory-to-use-your-ui.mdx#reference-implementations-and-examples) to - see how you can approach implementation for different app types (web app, SPA). + [reference implementations](/docs/kratos/bring-your-own-ui/configure-ory-to-use-your-ui#reference-implementations-and-examples) + to see how you can approach implementation for different app types (web app, + SPA). ## Configuration @@ -64,7 +67,8 @@ Follow these steps to enable WebAuthn as the second authentication factor: 1. Go to . 2. In the **WebAuthn** section, use the switch to enable WebAuthn. -3. Define the hostname of your login page. You must set this to your top-level domain. +3. Define the hostname of your login page. You must set this to your top-level + domain. :::note @@ -72,8 +76,8 @@ If you are using the Ory Account Experience, skip the 4. step ::: -4. Define the origin of your login page. Set it to the exact URL of the page that prompts the user to use WebAuthn. The relevant - items are: +4. Define the origin of your login page. Set it to the exact URL of the page + that prompts the user to use WebAuthn. The relevant items are: - scheme (`http` or `https`) - host (`auth.example.com`) @@ -84,7 +88,7 @@ If you are using the Ory Account Experience, skip the 4. step ```mdx-code-block -![WebAuthn settings in Ory Console](../_static/mfa/5.png) +![WebAuthn settings in Ory Console](./_static/5.png) ``` @@ -107,8 +111,8 @@ If you are using the Ory Account Experience, skip the 4. step ory get identity-config --project --workspace --format yaml > identity-config.yaml ``` -2. Find `webauthn` in `selfservice/methods`, set `enabled` to `true`, and define the `id` (hostname) and `origin` of the login - page users interact with: +2. Find `webauthn` in `selfservice/methods`, set `enabled` to `true`, and define + the `id` (hostname) and `origin` of the login page users interact with: ```yaml title="identity-config.yaml" webauthn: @@ -144,8 +148,9 @@ If you are using the Ory Account Experience, skip the 4. step ### Distinguish identities requesting WebAuthn -To help users distinguish which identity requests for WebAuthn authentication, add a `webauthn` object to the trait which -represents the WebAuthn account name. This trait's value will show up in the WebAuthn prompt of the browser. +To help users distinguish which identity requests for WebAuthn authentication, +add a `webauthn` object to the trait which represents the WebAuthn account name. +This trait's value will show up in the WebAuthn prompt of the browser. In this example, the user's email address is the identifier: @@ -190,19 +195,22 @@ This configuration is the default for the Ory Network. ## Writing E2E tests -When writing end-to-end (E2E) tests for WebAuthn implementation in your app, you can reference the +When writing end-to-end (E2E) tests for WebAuthn implementation in your app, you +can reference the [Cypress E2E tests used in Ory Identities (Kratos)](https://github.com/ory/kratos/blob/fc2cecfbeab811aa1a851f953b6bc2a4c119c412/test/e2e/cypress/integration/profiles/mfa/webauthn.spec.ts). :::tip To learn more about the approach used in Cypress, read -[this](https://github.com/cypress-io/cypress/issues/6991#issuecomment-612888645) GitHub issue. +[this](https://github.com/cypress-io/cypress/issues/6991#issuecomment-612888645) +GitHub issue. ::: ## Identity credentials -When the user enables WebAuthn, Ory adds the following entries to the `credentials` object of the associated identity: +When the user enables WebAuthn, Ory adds the following entries to the +`credentials` object of the associated identity: ```yaml credentials: diff --git a/docs/kratos/mfa/25_lookup-secrets.mdx b/src/components/Shared/kratos/mfa/25_lookup-secrets.mdx similarity index 68% rename from docs/kratos/mfa/25_lookup-secrets.mdx rename to src/components/Shared/kratos/mfa/25_lookup-secrets.mdx index 02d39b3fd5..763769c144 100644 --- a/docs/kratos/mfa/25_lookup-secrets.mdx +++ b/src/components/Shared/kratos/mfa/25_lookup-secrets.mdx @@ -1,32 +1,31 @@ ---- -id: lookup-secrets -title: Lookup Secrets - a MFA fail-safe -sidebar_label: Lookup Secrets (Recovery Codes) ---- - ```mdx-code-block import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import BrowserWindow from "@site/src/theme/BrowserWindow" ``` -Lookup Secrets, also known as Backup Codes or Recovery Codes, are a 2FA fail-safe mechanism, rather than a standalone two-factor -authentication method. They can be used to complete the second factor when users lose access to their selected 2FA method. +Lookup Secrets, also known as Backup Codes or Recovery Codes, are a 2FA +fail-safe mechanism, rather than a standalone two-factor authentication method. +They can be used to complete the second factor when users lose access to their +selected 2FA method. -If you enable Lookup Secrets, users can download a server-generated set of one-time codes. The user should store these codes in a -secure place and use them when they cannot use their selected 2FA method. +If you enable Lookup Secrets, users can download a server-generated set of +one-time codes. The user should store these codes in a secure place and use them +when they cannot use their selected 2FA method. -Each code is valid for single use only. The codes don't expire after a set amount of time. When the user generates a new set of -codes, previously generated codes become invalid. +Each code is valid for single use only. The codes don't expire after a set +amount of time. When the user generates a new set of codes, previously generated +codes become invalid. :::tip -To ensure maximum security, these codes should be periodically re-generated by the user. +To ensure maximum security, these codes should be periodically re-generated by +the user. ::: -If you enable Lookup Secrets, users can get a list of codes that they must store securely for future use. This is how it looks in -the UI: +If you enable Lookup Secrets, users can get a list of codes that they must store +securely for future use. This is how it looks in the UI: :::note @@ -37,7 +36,7 @@ The screenshots are captured using the Ory Account Experience. ```mdx-code-block -![Recovery Codes generation in Ory Account Experience](../_static/mfa/6.png) +![Recovery Codes generation in Ory Account Experience](./_static/6.png) ``` @@ -45,18 +44,20 @@ The screenshots are captured using the Ory Account Experience. ```mdx-code-block -![Recovery Codes in Ory Account Experience](../_static/mfa/7.png) +![Recovery Codes in Ory Account Experience](./_static/7.png) ``` -After the server generates the codes, the user must confirm that they received them. To confirm, the user must have a privileged -Session. If the privileged session expired, the user is prompted to authenticate. +After the server generates the codes, the user must confirm that they received +them. To confirm, the user must have a privileged Session. If the privileged +session expired, the user is prompted to authenticate. :::danger -The codes are valid only when the user confirms they received the codes. It is the user's responsibility to generate new secretes -before they use all the available secrets. +The codes are valid only when the user confirms they received the codes. It is +the user's responsibility to generate new secrets before they use all the +available secrets. ::: @@ -74,7 +75,7 @@ before they use all the available secrets. ```mdx-code-block -![Lookup Secrets settings in Ory Console](../_static/mfa/9.png) +![Lookup Secrets settings in Ory Console](./_static/9.png) ``` @@ -117,8 +118,8 @@ before they use all the available secrets. ## Identity credentials -When the user generates and/or uses Lookup Secrets, Ory adds the following entries to the `credentials` object of the associated -identity: +When the user generates and/or uses Lookup Secrets, Ory adds the following +entries to the `credentials` object of the associated identity: ```yaml credentials: diff --git a/docs/kratos/mfa/30_sms.mdx b/src/components/Shared/kratos/mfa/30_sms.mdx similarity index 77% rename from docs/kratos/mfa/30_sms.mdx rename to src/components/Shared/kratos/mfa/30_sms.mdx index 7e4e090883..6f363f2883 100644 --- a/docs/kratos/mfa/30_sms.mdx +++ b/src/components/Shared/kratos/mfa/30_sms.mdx @@ -1,32 +1,30 @@ ---- -id: mfa-via-sms -title: SMS and Email 2FA -sidebar_label: SMS and Email ---- - ```mdx-code-block import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import BrowserWindow from "@site/src/theme/BrowserWindow" ``` -SMS and email can be used to deliver one-time codes to users. Ory will deliver a 6-digit code to an SMS / email gateway of your -choice, such as Twilio, Amazon SNS, SMTP, or your own application. These codes are valid for a short amount of time, usually 15 -minutes or less. Once the user completes the challenge, by entering the code, the AAL of the session is upgraded to AAL2. +SMS and email can be used to deliver one-time codes to users. Ory will deliver a +6-digit code to an SMS / email gateway of your choice, such as Twilio, Amazon +SNS, SMTP, or your own application. These codes are valid for a short amount of +time, usually 15 minutes or less. Once the user completes the challenge, by +entering the code, the AAL of the session is upgraded to AAL2. -If MFA via code to sms / email is enabled, this method can not be used for passwordless login. +If MFA via code to SMS / email is enabled, this method cannot be used for +passwordless login. ```mdx-code-block -![Recovery Codes generation in Ory Account Experience](../_static/mfa/11.png) +![Recovery Codes generation in Ory Account Experience](./_static/11.png) ``` ## Configuration -To enable MFA via SMS, you need to configure an SMS channel in the Ory configuration: +To enable MFA via SMS, you need to configure an SMS channel in the Ory +configuration: ```mdx-code-block @@ -73,7 +71,8 @@ To enable MFA via SMS, you need to configure an SMS channel in the Ory configura ``` -4. Ensure your Identity Schema correctly marks one of the traits as the identifier for `code` method. +4. Ensure your Identity Schema correctly marks one of the traits as the + identifier for `code` method. ```json title="identity.schema.json" {25-28,45-48} { @@ -136,15 +135,19 @@ To enable MFA via SMS, you need to configure an SMS channel in the Ory configura } ``` -5. To configure the SMS or email gateway, please head over to [Sending emails](../emails-sms/01_sending-emails-smtp.mdx) & - [SMS](../emails-sms/10_sending-sms.mdx) +5. To configure the SMS or email gateway, please head over to + [Sending emails](/docs/kratos/emails-sms/sending-emails-smtp) & + [SMS](/docs/kratos/emails-sms/sending-sms) ## Integration -To be able to send codes via SMS, you need to provide a custom SMS sender. Ory simply sends the code, the phone number and other -metadata to a webhook of your choice. Please read the [SMS documentation](../emails-sms/10_sending-sms.mdx). +To be able to send codes via SMS, you need to provide a custom SMS sender. Ory +simply sends the code, the phone number and other metadata to a webhook of your +choice. Please read the +[SMS documentation](/docs/kratos/emails-sms/sending-sms). -To start a new MFA flow, for an already existing session, create a new login flow with the `aal` parameter set to `aal2`: +To start a new MFA flow, for an already existing session, create a new login +flow with the `aal` parameter set to `aal2`: ``` https://$PROJECT_SLUG.projects.oryapis.com/self-service/login/browser?aal=aal2 diff --git a/docs/kratos/_static/mfa/1.png b/src/components/Shared/kratos/mfa/_static/1.png similarity index 100% rename from docs/kratos/_static/mfa/1.png rename to src/components/Shared/kratos/mfa/_static/1.png diff --git a/docs/kratos/_static/mfa/10.png b/src/components/Shared/kratos/mfa/_static/10.png similarity index 100% rename from docs/kratos/_static/mfa/10.png rename to src/components/Shared/kratos/mfa/_static/10.png diff --git a/docs/kratos/_static/mfa/11.png b/src/components/Shared/kratos/mfa/_static/11.png similarity index 100% rename from docs/kratos/_static/mfa/11.png rename to src/components/Shared/kratos/mfa/_static/11.png diff --git a/docs/kratos/_static/mfa/2.png b/src/components/Shared/kratos/mfa/_static/2.png similarity index 100% rename from docs/kratos/_static/mfa/2.png rename to src/components/Shared/kratos/mfa/_static/2.png diff --git a/docs/kratos/_static/mfa/3.png b/src/components/Shared/kratos/mfa/_static/3.png similarity index 100% rename from docs/kratos/_static/mfa/3.png rename to src/components/Shared/kratos/mfa/_static/3.png diff --git a/docs/kratos/_static/mfa/4.png b/src/components/Shared/kratos/mfa/_static/4.png similarity index 100% rename from docs/kratos/_static/mfa/4.png rename to src/components/Shared/kratos/mfa/_static/4.png diff --git a/docs/kratos/_static/mfa/5.png b/src/components/Shared/kratos/mfa/_static/5.png similarity index 100% rename from docs/kratos/_static/mfa/5.png rename to src/components/Shared/kratos/mfa/_static/5.png diff --git a/docs/kratos/_static/mfa/6.png b/src/components/Shared/kratos/mfa/_static/6.png similarity index 100% rename from docs/kratos/_static/mfa/6.png rename to src/components/Shared/kratos/mfa/_static/6.png diff --git a/docs/kratos/_static/mfa/7.png b/src/components/Shared/kratos/mfa/_static/7.png similarity index 100% rename from docs/kratos/_static/mfa/7.png rename to src/components/Shared/kratos/mfa/_static/7.png diff --git a/docs/kratos/_static/mfa/8.png b/src/components/Shared/kratos/mfa/_static/8.png similarity index 100% rename from docs/kratos/_static/mfa/8.png rename to src/components/Shared/kratos/mfa/_static/8.png diff --git a/docs/kratos/_static/mfa/9.png b/src/components/Shared/kratos/mfa/_static/9.png similarity index 100% rename from docs/kratos/_static/mfa/9.png rename to src/components/Shared/kratos/mfa/_static/9.png diff --git a/src/components/Shared/kratos/passwordless/00_overview.mdx b/src/components/Shared/kratos/passwordless/00_overview.mdx new file mode 100644 index 0000000000..ff869592f8 --- /dev/null +++ b/src/components/Shared/kratos/passwordless/00_overview.mdx @@ -0,0 +1,233 @@ +Read this document if: + +- You want to learn more about passwordless authentication before deciding + whether to use it in your application or starting to code. +- You've heard about passwordless authentication as a potential solution to + protect your system against phishing attacks and would like to learn more + about how Ory supports this solution. +- You'd like to avoid using a traditional password-based solution since phishing + attacks have been a threat for your users in the past. + +Passwordless authentication is intended to replace traditional password-based +authentication, enabling users to verify their identity using authenticators +bound to the device they are using such as biometrics or hardware tokens. +Passkeys and passwordless authentication via WebAuthn is a technology based on +the specifications published by the [FIDO Alliance](https://fidoalliance.org/), +sponsored by software companies with an interest in security technology and +standards. + +## How does Ory support passwordless authentication? + +Ory's self-service flows support passwordless authentication for browser-based +apps by integrating with the +[W3C Web Authentication (WebAuthn) API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) +for browsers. After enabling it in Ory, the Ory Account Experience automatically +presents passwordless as an option in the registration and login flows. When +developing your own authentication UI for a browser-based app, the steps for +integrating your application with the passwordless registration and login flows +are described +[in the documentation](/docs/kratos/bring-your-own-ui/custom-ui-advanced-integration). + +There are two different classes of authenticators that can be used with +passwordless: + +- **On-device authenticator:** an authenticator available directly on the device + you are using, for example fingerprint or facial recognition on a mobile + phone. +- **External authenticator:** an authenticator provided by an external device, + such as a Yubikey or a NFC device. + +The user experiences the passwordless login flow as follows. + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +1. Ory's self-service login flow presents an option to log in using passwordless (below the option for signing in with a password). + ![Ory Account Experience login](./_static/ax-login-options.png) +2. To sign in with passwordless, the user enters their ID and clicks the **Sign in with security key** button. +3. The Ory Account Experience displays the sign-in preparation dialog, which gives the user time to prepare the physical device for passwordless login. The user clicks **Continue** to proceed to the next step. +4. The platform verifies the user's identity using the chosen method. +5. Login completes automatically. + + + + +1. Ory's self-service login flow presents an option to log in using passwordless. +2. To sign in with passwordless, the user enters their ID and clicks the **Sign in with security key** button. +3. The Ory Account Experience displays the sign-in preparation dialog, which gives the user time to prepare the physical device for passwordless login. The user clicks **Continue** to proceed to the next step. +4. The user chooses the external authenticator to use for sign-in (for example, a USB security key). + ![Choose external authenticator device](./_static/external-device-choose.png) +4. The platform verifies the user's identity using the chosen method. + ![Verify identity with USB security key](./_static/external-device-verify-identity.png) +5. Login completes automatically. + + + +``` + +### Authenticator options for passwordless + +Authenticators for passwordless are designed to be easy to use. For example, +biometric authenticators are a popular option. + +Here are some of the current authenticator options for passwordless: + +- **On-device authenticators** + - Fingerprint (Apple TouchID, Windows Hello) + - Facial recognition (Apple FaceID, Windows Hello) + - Iris scan (Windows Hello) + - Voice recognition + - Handwriting recognition + - Device unlock +- **External authenticators** + - USB key (YubiKey) + - NFC devices + - Bluetooth Low Energy (BLE) devices + +### Resistance to phishing + +The core idea of a phishing attack is to trick a user somehow into giving up +their password to the attacker, typically by luring the user to a fake website +where they are persuaded to log in, enabling the attacker to steal the password +from the login credentials. + +Passwordless authentication via WebAuthn is resistant to phishing attacks +because it eliminates shared secrets during login, verifies the domain, and +prevents password reuse. + +- No shared secrets during login: WebAuthn leverages Public Key Infrastructure + (PKI) to establish a unique keypair for each web application where the public + key is held by the web app and the private key is stored in a user-controlled + device. + +- Domain verification: The server domain is used by the client to request the + authenticator to sign the login request, ensuring that the credential provided + by the authenticator is only valid for the specific site visited. + +- No password reuse: WebAuthn prevents the vulnerability of "same password + everywhere" commonly exploited in phishing attacks and prevents impact on + other web apps in case of a breach by using a unique public key for each app. + +## How does passwordless work? + +Passwordless authentication via WebAuthN achieves ease of use without +compromising security too much by building on the following insights: + +- The device you are using such as a mobile phone or PC already has built-in + capabilities for verifying your identity. There is no need to duplicate the + procedure for identity verification when the device already has this + capability. +- Symmetric key authentication is an existing and proven technology, which has + better security characteristics than password-based authentication. The FIDO + alliance set itself the goal of automating symmetric key technology, making it + more user friendly. + +Consider the following diagram, which illustrates the passwordless WebAuthN +login flow. + +![Passwordless login flow](./_static/passwordless-login-flow.png) + +The main steps in the passwordless login flow are, as follows: + +1. In the frontend app, a user enters their ID and clicks the **Sign in with + security key** button, which initiates the passwordless login flow on Ory + Identities. +2. Ory Identities sends a cryptographic challenge consisting of unique, random + data - also known as a _nonce_ - to the frontend app. +3. The frontend app requests verification of the user's identity by calling the + WebAuthn API. WebAuthn automatically opens a dialog in the browser, asking + the user to choose an authenticator. +4. WebAuthn delegates identity verification to the browser, passing the + challenge and the choice of authenticator to the browser. The browser invokes + the chosen authenticator to verify the user's identity. + + - **On-device authenticator:** If the user authenticates successfully, the + platform selects the key pair that matches this app and uses the private + key to sign the challenge. + - **External authenticator:** Identity verification is delegated to the + external device, which holds the private key that is used to sign the + challenge. + +5. The browser returns the cryptographic response - the signed challenge - to + the frontend app, which forwards it on to Ory Identities. Ory Identities uses + the public key from the user account to verify the cryptographic response. + The public key gets stored in Ory Identities when the user signs up. + +:::note + +Neither the public key nor the private key are exposed to the app during this +authentication flow. The only time the public key is sent over the network is +during the registration flow, at which point the server stores the public key in +the database entry for the user's account. The corresponding passkey (private +key) never leaves the keychain on the user's device. + +::: + +## How passkeys and passwordless are related + +Passkey-based authentication and passwordless authentication are often talked +about together. But if you are new to passwordless, it's not always clear how +these concepts are related. At some level, passkeys are always involved in the +passwordless authentication process, in one of the following ways: + +- **Implicit use of passkeys** - for example, when a user authenticates using + fingerprint recognition or face recognition, the platform implicitly creates a + symmetric key pair, but this detail is hidden from the user. +- **Explicit use of passkeys** - for example, when a user authenticates using a + USB key, which has a private key embedded in the physical USB key. + +## Logging in with a passkey across multiple devices + +If you need to log in with a passkey across multiple devices, the following +options are supported by passwordless: + +- One-off authentication using an external device +- Secure transfer of the passkey to the new device +- Platform-specific passkey sharing between devices + +### One-off authentication using an external device + +Passkeys can be used to perform login across devices. WebAuthn defines a +protocol for performing passkey authentication remotely over a secured BLE +connection. + +For example, consider the case where the passkey for a particular application is +stored in the Android OS on your mobile phone. If you need to log into the +application from a PC, you can use the passkey on your mobile phone to verify +your identity. In this case, you select a BLE (Bluetooth Low Energy) device as +the external authenticator on the PC and, after pairing your phone with the PC, +you are prompted to verify your identity on the mobile phone. This +authentication step is a one-off and the passkey is not transferred to the PC. + +Using this remote authentication protocol, you can use your mobile phone as an +external authenticator for any device that supports WebAuthn, without leaving +any trace of your credentials on that device. + +### Secure transfer of the passkey to a new device + +On the other hand, if you want to transfer passkey credentials from your mobile +phone to your PC, this is also supported by the FIDO standard. Support for this +feature is not available on all platforms, however, as it is a recent addition +to the standard. + +For example, consider the case where a passkey for a particular application is +stored on your mobile phone, but you also want to have this passkey available on +your personal laptop, so that you don't need to take out your phone every time +you log in from your laptop. If your platform has support for this, you see an +option to securely transfer the passkey to your laptop, while performing remote +authentication over BLE. If you choose to transfer the passkey, it will be +stored permanently (and securely) on your laptop's OS and in future you will be +able to log in to the application directly from your laptop. + +### Platform-specific passkey sharing between devices + +If all of your devices belong to the same platform ecosystem such as Android, +macOS, or Windows, you might find there is a platform-specific mechanism +available for sharing passkeys securely between devices. For example, the Apple +iCloud Keychain is capable of sharing passkeys for passwordless login across +multiple Apple devices assuming these devices have access to the same Apple +iCloud account. diff --git a/docs/kratos/passwordless/05_passkeys.mdx b/src/components/Shared/kratos/passwordless/05_passkeys.mdx similarity index 68% rename from docs/kratos/passwordless/05_passkeys.mdx rename to src/components/Shared/kratos/passwordless/05_passkeys.mdx index 305b7f8769..4ccd64bed4 100644 --- a/docs/kratos/passwordless/05_passkeys.mdx +++ b/src/components/Shared/kratos/passwordless/05_passkeys.mdx @@ -1,34 +1,32 @@ ---- -id: passkeys -title: Passwordless sign-in and sign-up with passkeys -sidebar_label: Passkeys & WebAuthN ---- - import CodeBlock from "@theme/CodeBlock" import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" -# Passkeys & WebAuthN - -The [Web Authentication Browser API (WebAuthn)](https://w3c.github.io/webauthn/) is a specification written by -[W3C](https://www.w3.org/) and [FIDO](https://fidoalliance.org/). The WebAuthn API allows servers to register and authenticate -users using public key cryptography instead of passwords. +The [Web Authentication Browser API (WebAuthn)](https://w3c.github.io/webauthn/) +is a specification written by [W3C](https://www.w3.org/) and +[FIDO](https://fidoalliance.org/). The WebAuthn API allows servers to register +and authenticate users using public key cryptography instead of passwords. -Passkeys use the WebAuthn standard to generate and manage cryptographic key pairs for users. -[Passkeys](https://fidoalliance.org/passkeys/) are, as described by the [FIDO Alliance](https://fidoalliance.org/), "a password -replacement that provides faster, easier, and more secure sign-ins to websites and apps across a user's devices." +Passkeys use the WebAuthn standard to generate and manage cryptographic key +pairs for users. [Passkeys](https://fidoalliance.org/passkeys/) are, as +described by the [FIDO Alliance](https://fidoalliance.org/), "a password +replacement that provides faster, easier, and more secure sign-ins to websites +and apps across a user's devices." :::info -WebAuthn is the underlying technology that allows passwordless authentication using public key cryptography. +WebAuthn is the underlying technology that allows passwordless authentication +using public key cryptography. Passkeys are a more user-friendly implementation of WebAuthn. ::: ## Passkeys -Passkeys are a method for registering and signing in users without passwords. Passkeys are an industry-accepted and adopted -standard, which means that all of your users will be able to use this feature, no matter the hardware they work with. +Passkeys are a method for registering and signing in users without passwords. +Passkeys are an industry-accepted and adopted standard, which means that all of +your users will be able to use this feature, no matter the hardware they work +with. Notable adopters of passkeys include: @@ -37,22 +35,31 @@ Notable adopters of passkeys include: - [Microsoft](https://www.microsoft.com/en-us/security/blog/2022/05/05/this-world-password-day-consider-ditching-passwords-altogether/) - [Meta](https://www.threads.net/@wcathcart/post/Cyd27d7pex8) -While companies can add proprietary features to passkeys, such as iCloud synchronization in Apple Passkeys or Google Password -Manager synchronization for Android devices, all of them use the same FIDO standard. This means that enabling passkeys is a -simple, one-time operation in Ory. +While companies can add proprietary features to passkeys, such as iCloud +synchronization in Apple Passkeys or Google Password Manager synchronization for +Android devices, all of them use the same FIDO standard. This means that +enabling passkeys is a simple, one-time operation in Ory. :::tip -To learn more about passkeys and see sample flows for different platforms, watch this FIDO Alliance video: +To learn more about passkeys and see sample flows for different platforms, watch +this FIDO Alliance video: -