From c120031ec144002f3f2188085363978fecc73190 Mon Sep 17 00:00:00 2001 From: Vincent Date: Mon, 10 Jan 2022 12:04:50 +0100 Subject: [PATCH] fix: faq (#2101) This patch - moves the FAQ to the Debug & Help section - renames it to Tips & Troubleshooting - moves many of the questions to documents where they fit better, reformatted and with added information where needed. - also some other spelling/format fixes See also https://github.com/ory/docusaurus-template/pull/87 --- docs/docs/concepts/email-sms.md | 5 +- docs/docs/concepts/identity-schema.mdx | 27 +- docs/docs/debug/troubleshooting.md | 43 +++ docs/docs/faq.mdx | 255 ------------------ ...n-with-github-google-facebook-linkedin.mdx | 104 +++++-- docs/faq.yaml | 138 ---------- docs/sidebar.json | 4 +- 7 files changed, 155 insertions(+), 421 deletions(-) create mode 100644 docs/docs/debug/troubleshooting.md delete mode 100644 docs/docs/faq.mdx delete mode 100644 docs/faq.yaml diff --git a/docs/docs/concepts/email-sms.md b/docs/docs/concepts/email-sms.md index 64174f3f3c75..264f571bccb9 100644 --- a/docs/docs/concepts/email-sms.md +++ b/docs/docs/concepts/email-sms.md @@ -102,7 +102,10 @@ indicate where your custom templates are located. This will become the `email.subject.gotmpl`, `email.body.gotmpl` and `email.body.plaintext.gotmpl` are common template file names expected in the sub directories of the root directory, corresponding to the respective methods for filling e-mail subject -and body. +and body. Both plain text and HTML templates are required. The courier uses them +as +[alternatives](https://github.com/ory/kratos/blob/master/courier/courier.go#L205) +for fallback. > Templates use the golang template engine in the `text/template` package for > rendering the `email.subject.gotmpl` and `email.body.plaintext.gotmpl` diff --git a/docs/docs/concepts/identity-schema.mdx b/docs/docs/concepts/identity-schema.mdx index 2268c13015bc..4438e941b049 100644 --- a/docs/docs/concepts/identity-schema.mdx +++ b/docs/docs/concepts/identity-schema.mdx @@ -172,16 +172,22 @@ switch (session.Identity.SchemaID) { } ``` +### Sensitive Data in Identity Schema + :::warning -Please keep in mind that the Identity Schema is not a place to store sensitive -information that should not be visible to the end-user! Users can see traits and -other data - except credentials - using the `sessions/whoami` endpoint. The -Identity Schema is not the right place to store data that should be obfuscated -from the user! +The Identity Schema is not a place to store sensitive information that should +not be visible to the end-user! ::: +The Identity Schema is not the right place to store data that should be +obfuscated from the user! Users can see traits and other data - except +credentials - using the `sessions/whoami` endpoint. Users are also able to edit +identity traits. Visit [this issue](https://github.com/ory/kratos/issues/47) for +information on a feature that can be configured to prevent the end-user from +viewing/editing identity traits. + ## Identity Schema Vocabulary Extensions Because Ory Kratos does not know that a particular field has a system-relevant @@ -319,3 +325,14 @@ contains more information and examples. There are currently no other extensions supported for Identity Traits. Further fields will be added in future releases! + +### Sanitize Usernames/Traits + +To make sure usernames (or traits) satisfy a specific regex (for example only +alphanumeric characters), they can be sanitized. To sanitize usernames add +[Regular Expressions](https://json-schema.org/understanding-json-schema/reference/string.html#regular-expressions) +to the Ory Kratos Identity Schema. To sanitize usernames coming from third-party +OIDC providers like +[Google or GitHub](https://www.ory.sh/kratos/docs/next/guides/sign-in-with-github-google-facebook-linkedin) +write [Jsonnet](https://jsonnet.org). Learn more about +[Data Mapping with Jsonnet](../reference/jsonnet/). diff --git a/docs/docs/debug/troubleshooting.md b/docs/docs/debug/troubleshooting.md new file mode 100644 index 000000000000..9a1693f54779 --- /dev/null +++ b/docs/docs/debug/troubleshooting.md @@ -0,0 +1,43 @@ +--- +id: troubleshooting +title: Tips & 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) and ping +`@ory/documenters` or +[edit the page directly](https://github.com/ory/kratos/edit/master/docs/docs/debug/troubleshooting.md). + +::: + +### 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 is supposed to talk to. The instances are cheap to deploy and +the databases are completely isolated from each other. For example something +like `/login/customer` and `/login/employee`. + +### How can I verify in advance if a username is available during registration? + +You can not right now. It would allow account enumeration attacks. See also the +[section in the documentation](https://www.ory.sh/kratos/docs/concepts/security/#account-enumeration). + +### Do have plans to support automatic user migration scenarios? + +> E.g. configure a callback to the legacy system when you cannot 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 Hydra (OAuth2/OIDC Server) and then using that as an upstream in Ory Kratos. diff --git a/docs/docs/faq.mdx b/docs/docs/faq.mdx deleted file mode 100644 index 5240a2215253..000000000000 --- a/docs/docs/faq.mdx +++ /dev/null @@ -1,255 +0,0 @@ ---- -id: faq -title: Frequently Asked Questions (FAQ) ---- - - - -import { Question, FaqTags } from '@theme/Faq' - - -
-
- - - #kratos #secrets #config -

- Q: Is it possible to pass multiple system.secret values - through the ENV, or do you have to use a config file for that? -

-

- A: Yes, you can set them as environmental variable, you - just have to separate them using a ,. More info on these - conventions in the documentation:{' '} - - Setting configuration values via environmental variables - - . -

- - -
- - #kratos #database -

- Q: We want to seperate 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. How can I achieve that with Ory Kratos? -

-

- A: 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 is supposed to talk to. The instances - are cheap to deploy and the databases are completely isolated from each - other. For example something like /login/customer and{' '} - /login/employee. -

- - -
- - #kratos #ecosystem -

- Q: Is the code audited by an independent entity and is - there a bug bounty program? -

-

- A: We will do that when the APIs and core are stable. A bug - bounty program is in the making but not done yet. If you are a security - researcher and interested in working on Kratos, please reach out to{' '} - security@ory.sh. -

- - -
- - #kratos #user #validation #traits -

- Q: What is the correct flow to sanitize the username and - make sure it satisfies a specific regex (e.g. only alphanumeric characters)? -

-

- A: In the Identity Schema using{' '} - - Regular Expressions - - . To sanitize usernames coming from third-party OIDC providers like Google or - GitHub you write jsonnet code. -

- - -
- - #kratos #registration #cors -

- Q: I am currently trying to get the Kratos registration - flow working on a react app that I am creating. I am having CORS issues with - the completeSelfServiceRegistrationFlowWithPasswordMethod call when using - the @oryd/kratos-client JS package. -

-

- A: You are using AJAX to submit the form. This is not - supported right now. You need to submit a regular HTML form. Do not use - AJAX. Do not use fetch. Let the user click the submit button and do not do - anything. AJAX will be better supported starting Kratos v0.6. -

- - -
- - #kratos #traits #feature -

- Q: Is the ability to freeze certain identity fields after - registration anywhere on the roadmap? Also I want read-only or hidden - user-specific data. Can I use traits for that? Example: Some of our identity - trait fields may be the subject to identity validation ( - - know your customer - - ). Once they are validated we do not allow the identity to be edited by the end-user. -

-

- A: Currently traits are visible to the user and also - editable by them. It makes sense to have read-only and/or hidden traits for - users, but we can not give an exact timing when this will be available. - There is an open issue for this feature: - Issue. -

- - -
- - #kratos #hooks #feature -

- Q: Are there plans to provide hooks on - registration/login/logouts/identity updates? -

-

- A: Yes! See these issues for more information on the - current progress:{' '} - - Feature Request: Webhooks - {' '} - and{' '} - - Implement RPC After Hook - - . -

- - -
- - #kratos #registration #traits -

- Q: How can I verify beforehand if a username is available - during registration? -

-

- A: You can not right now. It would allow account - enumeration attacks. See also the{' '} - - section in the documentation - - . -

- - -
- - #kratos #database #migration #feature -

- Q: Do have plans to support user migration scenarios - similar to auth0 automatic migrations? E.g. configure a callback to the - legacy system when you cannot find the corresponding user, and store the - identity on successful legacy system response. -

-

- A: No plans yet, but migration is an important piece of the - puzzle. We will focus on importing existing users first. An alternative to - callback and custom code is fronting the legacy system with Ory Hydra - (OAuth2/OIDC Server) and then using that as an upstream in Ory Kratos. -

- - -
- - #kratos #security -

- Q: Do you have protection or plans for brute force attacks - i.e. repetitive login attempts? Leaked database scans? -

-

- A: See the following document:{' '} - - Ory Kratos Security Measures - -

- - -
- - #kratos #oidc #traits -

- Q: How do I append a random suffix e.g. a number to OIDC - usernames if the username returned by a provider is already taken. -

-

- A: You can use the md5 function built in the{' '} - jsonnet standart library. - See the following issue as well:{' '} - - Add random function to the jsonnet library - - . -

- - -
- - #kratos #spa -

- Q: I want to implement a single-page-app (SPA). Is this - possible with Ory Kratos? -

-

- A: Yes, definitely. We do not have an example-app (yet). - Also, you might not get around some page-reloads as you definitely should, - as it is not possible to use the API flows in the browser. This is important - to prevent{' '} - - CSRF attacks - - . So hopefully you are not too strict with your SPA. A sample app is being worked - on here: - Implement React SPA sample app - . -

- - -
diff --git a/docs/docs/guides/sign-in-with-github-google-facebook-linkedin.mdx b/docs/docs/guides/sign-in-with-github-google-facebook-linkedin.mdx index cc5491ef1eca..b19072ba9c19 100644 --- a/docs/docs/guides/sign-in-with-github-google-facebook-linkedin.mdx +++ b/docs/docs/guides/sign-in-with-github-google-facebook-linkedin.mdx @@ -3,7 +3,7 @@ id: sign-in-with-github-google-facebook-linkedin title: Sign in with GitHub, GitLab, Google, Facebook, LinkedIn, Microsoft ... --- -In this document we will take a look at setting up "Social Sign In" with +In this document, we will take a look at setting up "Social Sign In" with different providers using Ory Kratos. Run the [Quickstart](../quickstart.mdx) with Docker Compose: @@ -18,9 +18,9 @@ $ make quickstart :::info -It is very important to add the "session" hook to the after oidc registration -hooks. Otherwise your users need to use the login flow again to be able to get a -session. +It is very important to add the "session" hook to the after OIDC registration +hooks. Otherwise, your users need to use the login flow again to be able to get +a session. ```yaml title="path/to/my/kratos/config.yml" # $ kratos -c path/to/my/kratos/config.yml serve @@ -158,7 +158,7 @@ that data to `std.extVar('claims')`. However, not all fields are supported. Check the list of supported fields [in Kratos' source code](https://github.com/ory/kratos/blob/master/selfservice/strategy/oidc/provider_slack.go). -The `identity.basic` scope will add following fields: +The `identity.basic` scope will add the following fields: ```text iss # always https://slack.com/oauth/ @@ -265,7 +265,7 @@ to and adds that data to `std.extVar('claims')`. Check out what data is available at [GitHub's Scope Docs](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). -Not all GitHub fields are supported however. Check the list of supported fields +However, not all GitHub fields are supported. Check the list of supported fields [in Kratos' source code](https://github.com/ory/kratos/blob/v0.2.1-alpha.1/selfservice/strategy/oidc/provider_github.go#L72-L98). Only for `Github Oauth2` as `GitHub App` does not have scope. See the @@ -419,9 +419,9 @@ GitLab is now an option to log in via Kratos. To set up "Sign in with Auth0" you must create an [Auth0 Application for your Auth0 Tenant](https://auth0.com/docs/applications). -Note that the endpoint for the application starts with your Tenant name. e.g. +Note that the endpoint for the application starts with your Tenant's name. e.g. `myAuth0Tenant.auth0.com`. This will be the `IssuerURL` you will use when -configuring the the OIDC connection. +configuring the OIDC connection. Set the "Redirect URI" to: @@ -471,9 +471,9 @@ Now, enable the Auth0 provider in the Ory Kratos config located at `/contrib/quickstart/kratos/email-password/kratos.yml`. Note that the `issuer_url` needs to be the top-level domain for your Auth0 application. This can be found by going to the Auth0 application page and -choosing `Settings` then `Advanced Settings` then `Endpoints`. In general though -the endpoint is of the form `myAuth0Tenant.auth0.com` (where `myAuth0Tenant` is -the name of your tenant). +choosing `Settings` then `Advanced Settings` then `Endpoints`. In general, the +endpoint is of the form `myAuth0Tenant.auth0.com` (where `myAuth0Tenant` is the +name of your tenant). ```yaml title="contrib/quickstart/kratos/email-password/kratos.yml" # $ kratos -c path/to/my/kratos/config.yml serve @@ -566,15 +566,15 @@ selfservice: - email ``` -Azure AD is now an option to log in to kratos. +Azure AD is now an option to log in to Ory Kratos. ##### Choosing Tenant There are two ways to use the `microsoft` provider for authentication: -1. For authenticating users in a single Azure AD Directory (organisation), set +1. For authenticating users in a single Azure AD Directory (organization), set the `tenant` value to either the `Directory ID` from the "App Registration" - page, or the organisation domain. E.g. `8eaef023-2b34-4da1-9baa-8bc8c9d6a490` + page, or the organization domain. E.g. `8eaef023-2b34-4da1-9baa-8bc8c9d6a490` or `contoso.onmicrosoft.com`. 2. For authenticating any user in the Microsoft identity platform, set the `tenant` value to either: @@ -818,10 +818,10 @@ selfservice: hd: null # If you want the G Suite domain ``` -**Google specific claims** +**Google-specific claims** - `hd`: The hosted G Suite domain of the user. Provided only if the user belongs - to a hosted domain. For a given email account with custom domain + to a hosted domain. For a given email account with a custom domain `example.com` - `user1@example.com` would produce `example.com` in the `hd` claim. @@ -1004,7 +1004,7 @@ Login option! ## Apple To set up "Sign in with Apple" you must -[create an app, a service and a private key](https://developer.okta.com/blog/2019/06/04/what-the-heck-is-sign-in-with-apple#create-an-app-id). +[create an app, a service, and a private key](https://developer.okta.com/blog/2019/06/04/what-the-heck-is-sign-in-with-apple#create-an-app-id). Set the "Redirect URI" to: @@ -1068,7 +1068,7 @@ selfservice: private_key_id: .... # Replace this with the private key identifier generated by Apple private_key: | -----BEGIN PRIVATE KEY----- - .... # Replace this by the content of the private key downloaded from Apple + .... # Replace this with the content of the private key downloaded from Apple -----END PRIVATE KEY----- mapper_url: file:///etc/config/kratos/oidc.apple.jsonnet scope: @@ -1099,8 +1099,8 @@ http(s)://:/self-service/methods/oidc/callbac While Spotify [provides an OIDC discovery URL](https://accounts.spotify.com/.well-known/openid-configuration), -Spotify does not actually support the `openid` claim and only returns an access -token. Therefore, Ory Kratos makes a request to +Spotify does not support the `openid` claim and only returns an access token. +Therefore, Ory Kratos makes a request to [Spotify's /me API](https://developer.spotify.com/documentation/web-api/reference/#/operations/get-current-users-profile) and adds the user info to `std.extVar('claims')`. @@ -1147,3 +1147,67 @@ Spotify is now an option to log in via Kratos. Connecting with other Social Sign In providers will be very similar to the GitHub flow. If you've managed to do it, add to this document by writing it down and making a PR! :) + +## How to prevent `username already taken` + +Sometimes the username returned by a provider is already taken in your +application. To prevent this you can add a random suffix (e.g. a number) to the +OIDC username. You can use the md5 function built in the +[jsonnet standard library](https://jsonnet.org/ref/stdlib.html). See the +following issue as well: +[Add random function to the jsonnet library](https://github.com/ory/kratos/issues/988). + +## How to skip Social Login Link-Up + +If multiple +[registration methods](../docs/self-service/flows/user-registration.mdx) are +configured, users may be redirected to a social login provider to link the +accounts after the email verification. To skip this link-up add the session hook +after the registration method (e.g. `password`): + +``` + after: + password: + hooks: + - hook: session +``` + +## How Ory Kratos handles OIDC token + +The OIDC token is not being saved in the Ory Kratos database, Ory Kratos +exchanges it for a session. For example: + +- Ory Kratos starts the OIDC flow with Google. +- Google sends back the OIDC `id_token` (if successfully authenticated). +- Ory Kratos gets the user information from the `id_token` (specified in claims, + default email, or username). +- Ory Kratos checks the database if the identity exists; + +--> if yes, Ory Kratos returns a session token to the user; + +-->if no, the identity is created and it returns a session token. + +- The `id_token` from Google is discarded upon completion of the flow. + +## Log in through social providers if the identifiers match + +A user creates an account with the identifier `user@example.com`. When the same +user has an account at e.g. ACME using the same identifier `user@example.com`, +some providers offer the option to have the user login through ACME, even though +the user has not created the account using `Login with ACME`. + +> Right now there's an explicit extra step to link them as default +> configuration. There is no way to login through them without linking if e.g. +> emails match. + +:::warning + +We strongly discourage this practice, consider the following scenario: + +::: + +- You have signed up using `user@example.com` to acme.com. +- The hacker knows this. +- The hacker creates a social login account (e.g. Google) with the email + `user@example.com` and signs in on acme.com. +- Now the hacker is in your account. diff --git a/docs/faq.yaml b/docs/faq.yaml deleted file mode 100644 index ec351f7057d5..000000000000 --- a/docs/faq.yaml +++ /dev/null @@ -1,138 +0,0 @@ -- tags: - - kratos - - secrets - - config - q: | - Is it possible to pass multiple system.secret values through the ENV, or do you - have to use a config file for that? - a: | - Yes, you can set them as environmental variable, you just have to separate them - using a `,`. More info on these conventions in the documentation: [Setting configuration - values via environmental variables](https://www.ory.sh/docs/ecosystem/configuring/#stringnumeric-arrays). -- tags: - - kratos - - database - q: | - We want to seperate 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. - How can I achieve that with Ory Kratos? - a: | - 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 is supposed to - talk to. The instances are cheap to deploy and the databases are completely isolated - from each other. For example something like `/login/customer` and `/login/employee`. -- tags: - - kratos - - ecosystem - q: | - Is the code audited by an independent entity and is there a bug bounty program? - a: | - We will do that when the APIs and core are stable. A bug bounty program is in - the making but not done yet. If you are a security researcher and interested in - working on Kratos, please reach out to [security@ory.sh](mailto:security@ory.sh). -- tags: - - kratos - - user - - validation - - traits - q: | - What is the correct flow to sanitize the username and make sure it satisfies - a specific regex (e.g. only alphanumeric characters)? - a: | - In the Identity Schema using [Regular Expressions](https://json-schema.org/understanding-json-schema/reference/string.html#regular-expressions). - To sanitize usernames coming from third-party OIDC providers like Google or GitHub - you write [jsonnet code](https://jsonnet.org). -- tags: - - kratos - - registration - - cors - q: | - I am currently trying to get the Kratos registration flow working - on a react app that I am creating. I am having CORS issues with the completeSelfServiceRegistrationFlowWithPasswordMethod - call when using the @oryd/kratos-client JS package. - a: | - You are using AJAX to submit the form. This is not supported right now. You need - to submit a regular HTML form. Do not use AJAX. Do not use fetch. Let the user - click the submit button and do not do anything. AJAX will be better supported - starting Kratos v0.6. -- tags: - - kratos - - traits - - feature - q: | - Is the ability to freeze certain identity fields after registration anywhere - on the roadmap? Also I want read-only or hidden user-specific data. Can I use - traits for that? Example: Some of our identity trait fields may be the subject - to identity validation ([know your customer](https://en.wikipedia.org/wiki/Know_your_customer)). - Once they are validated we do not allow the identity to be edited by the end-user. - a: | - Currently traits are visible to the user and also editable by them. It makes - sense to have read-only and/or hidden traits for users, but we can not give an - exact timing when this will be available. There is an open issue for this feature: - [Issue](https://github.com/ory/kratos/issues/47). -- tags: - - kratos - - hooks - - feature - q: | - Are there plans to provide hooks on registration/login/logouts/identity updates? - a: | - Yes! See these issues for more information on the current progress: [Feature - Request: Webhooks](https://github.com/ory/kratos/issues/271) and [Implement RPC - After Hook](https://github.com/ory/kratos/issues/30). -- tags: - - kratos - - registration - - traits - q: | - How can I verify beforehand if a username is available during registration? - a: | - You can not right now. It would allow account enumeration attacks. See also the [section - in the documentation](https://www.ory.sh/kratos/docs/concepts/security/#account-enumeration). -- tags: - - kratos - - database - - migration - - feature - q: | - Do have plans to support user migration scenarios similar to auth0 automatic - migrations? E.g. configure a callback to the legacy system when you cannot find - the corresponding user, and store the identity on successful legacy system response. - a: | - No plans yet, but migration is an important piece of the puzzle. We will focus - on importing existing users first. An alternative to callback and custom code - is fronting the legacy system with Ory Hydra (OAuth2/OIDC Server) and then using - that as an upstream in Ory Kratos. -- tags: - - kratos - - security - q: | - Do you have protection or plans for brute force attacks i.e. repetitive login - attempts? Leaked database scans? - a: | - See the following document: [Ory Kratos Security Measures](https://www.ory.sh/kratos/docs/concepts/security#passwords) -- tags: - - kratos - - oidc - - traits - q: | - How do I append a random suffix e.g. a number to OIDC usernames if the username - returned by a provider is already taken. - a: | - You can use the md5 function built in the [jsonnet standart library](https://jsonnet.org/ref/stdlib.html). - See the following issue as well: [Add random function to the jsonnet library](https://github.com/ory/kratos/issues/988). -- tags: - - kratos - - spa - q: | - I want to implement a single-page-app (SPA). Is this possible with Ory Kratos? - a: | - Yes, definitely. We do not have an example-app (yet). Also, you might not get - around some page-reloads as you definitely should, as it is not possible to use - the API flows in the browser. This is important to prevent [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery). - So hopefully you are not too strict with your SPA. A sample app is being worked - on here: [Implement React SPA sample app](https://github.com/ory/kratos/issues/668). diff --git a/docs/sidebar.json b/docs/sidebar.json index 78ebde8ee5d6..8bca6dfa9299 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -5,8 +5,7 @@ "quickstart", "install", "configuring", - "contributing", - "faq" + "contributing" ] }, { @@ -117,6 +116,7 @@ }, { "Debug & Help": [ + "debug/troubleshooting", "debug/csrf", "debug/performance-out-of-memory-password-hashing-argon2", "debug/debug-docker-delve-ory-kratos"