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/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/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/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-oel.ts b/sidebars-oel.ts index c72f9e2e52..54cb4338b9 100644 --- a/sidebars-oel.ts +++ b/sidebars-oel.ts @@ -119,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/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/vercel.json b/vercel.json index 0ed9c2a3df..2f68f38ad1 100644 --- a/vercel.json +++ b/vercel.json @@ -1966,6 +1966,26 @@ "source": "/docs/kratos/mfa/mfa-via-sms", "destination": "/docs/network/kratos/mfa/mfa-via-sms", "permanent": true + }, + { + "source": "/docs/kratos/debug/csrf", + "destination": "/docs/oel/kratos/debug/csrf", + "permanent": true + }, + { + "source": "/docs/kratos/debug/debug-docker-delve-ory-kratos", + "destination": "/docs/oel/kratos/debug/debug-docker-delve-ory-kratos", + "permanent": true + }, + { + "source": "/docs/kratos/debug/performance-out-of-memory-password-hashing-argon2", + "destination": "/docs/oel/kratos/debug/performance-out-of-memory-password-hashing-argon2", + "permanent": true + }, + { + "source": "/docs/kratos/debug/troubleshooting", + "destination": "/docs/oel/kratos/debug/troubleshooting", + "permanent": true } ], "headers": [