diff --git a/docs/docs/admin/managing-users-identities.mdx b/docs/docs/admin/managing-users-identities.mdx index 19ad5204364..d4da2de1bb9 100644 --- a/docs/docs/admin/managing-users-identities.mdx +++ b/docs/docs/admin/managing-users-identities.mdx @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem' This document walks you through the administrative identity management in ORY Kratos. You should already be familiar with the -[Identity Data Model](../concepts/identity-data-model) before reading this +[Identity Data Model](../concepts/identity-data-model.md) before reading this guide. ## Creating an Identity diff --git a/docs/docs/concepts/credentials/openid-connect-oidc-oauth2.mdx b/docs/docs/concepts/credentials/openid-connect-oidc-oauth2.mdx index 54cc7a547c3..fe957b7c3f2 100644 --- a/docs/docs/concepts/credentials/openid-connect-oidc-oauth2.mdx +++ b/docs/docs/concepts/credentials/openid-connect-oidc-oauth2.mdx @@ -12,7 +12,7 @@ provider (for example [ORY Hydra](https://www.ory.sh/hydra)). "Social Sign In" or "Sign in with ..." are common aliases for this flow. This strategy expects that you've set up your -[Default Identity JSON Schema](../identity-user-model). +[Default Identity JSON Schema](../identity-data-model.md). ## Configuration @@ -289,4 +289,4 @@ until the identity's traits are valid against the defined JSON Schema. For more information on this flow (network flow, examples, UI, ...) head over to the -[OpenID Connect and OAuth2 Self-Service Method Documentation](../../self-service/flows/user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx). +[OpenID Connect and OAuth2 Self-Service Method Documentation](../../self-service/flows/user-registration.mdx). diff --git a/docs/docs/concepts/credentials/username-email-password.mdx b/docs/docs/concepts/credentials/username-email-password.mdx index 97e724869e6..188737da8d5 100644 --- a/docs/docs/concepts/credentials/username-email-password.mdx +++ b/docs/docs/concepts/credentials/username-email-password.mdx @@ -9,8 +9,8 @@ during registration and login. ORY Kratos hashes the password after registration, password reset, and password change using the [Argon2 Hashing Algorithm](../../concepts/security#Argon2), the -winner of the (https://github.com/P-H-C/phc-winner-argon2)[Password Hashing -Competition (PHC)]. +winner of the [Password Hashing +Competition (PHC)](https://github.com/P-H-C/phc-winner-argon2). ## Configuration diff --git a/docs/docs/concepts/identity-data-model.md b/docs/docs/concepts/identity-data-model.md index f0013e81b3f..91d68afb6cf 100644 --- a/docs/docs/concepts/identity-data-model.md +++ b/docs/docs/concepts/identity-data-model.md @@ -14,7 +14,9 @@ In ORY Kratos' terminology we call all of them "identities", and it is always exposed as `identity` in the API endpoints, requests, and response payloads. In the documentation however, we mix these words as "account recovery" or "account activation" is a widely accepted and understood terminology and user flow, while -"identity recovery" or "identity activation" is not. ::: +"identity recovery" or "identity activation" is not. + +::: The following examples use YAML for improved readability. However, the API payload is usually in JSON format. An `identity` has the following properties: @@ -75,7 +77,7 @@ Identities are [#596](https://github.com/ory/kratos/issues/596)). The identity state is therefore `active` or `disabled` (not yet implemented see -[#598](https://github.com/ory/kratos/issues/598): +[#598](https://github.com/ory/kratos/issues/598)) Active: create Active --> Active: update Active --> Disabled: disable Disabled --> [*]: delete Disabled --> Active: enable`} @@ -168,27 +170,27 @@ meaning you have to specify these in the schema. This includes for example: ORY Kratos' JSON Schema Vocabulary Extension can be used within a property: -```json5 +```json { - $id: 'http://mydomain.com/schemas/v2/customer.schema.json', - $schema: 'http://json-schema.org/draft-07/schema#', - title: 'A customer (v2)', - type: 'object', - properties: { - traits: { - type: 'object', - properties: { - email: { - title: 'E-Mail', - type: 'string', - format: 'email', + "$id": "http://mydomain.com/schemas/v2/customer.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "A customer (v2)", + "type": "object", + "properties": { + "traits": { + "type": "object", + "properties": { + "email": { + "title": "E-Mail", + "type": "string", + "format": "email", // This tells ORY Kratos that the field should be used as the "username" for the username+password flow. // It is an extension to the regular JSON Schema vocabulary. - 'ory.sh/kratos': { - credentials: { - password: { - identifier: true + "ory.sh/kratos": { + "credentials": { + "password": { + "identifier": true } } } @@ -207,12 +209,12 @@ You can configure ORY Kratos to use specific fields as the _identifier_ e.g. username, email, phone number, etc., in the Username and Password Registration and Login Flow: -```json5 +```json { - 'ory.sh/kratos': { - credentials: { - password: { - identifier: true + "ory.sh/kratos": { + "credentials": { + "password": { + "identifier": true } } } @@ -235,50 +237,50 @@ traits: and using a JSON Schema that uses the `email` field as the identifier for the password flow -```json5 +```json { - $id: 'http://mydomain.com/schemas/v2/customer.schema.json', - $schema: 'http://json-schema.org/draft-07/schema#', - title: 'A customer (v2)', - type: 'object', - properties: { - traits: { - type: 'object', - properties: { - email: { - title: 'E-Mail', - type: 'string', - format: 'email', + "$id": "http://mydomain.com/schemas/v2/customer.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "A customer (v2)", + "type": "object", + "properties": { + "traits": { + "type": "object", + "properties": { + "email": { + "title": "E-Mail", + "type": "string", + "format": "email", // This tells ORY Kratos that the field should be used as the "username" for the Username and Password Flow. - 'ory.sh/kratos': { - credentials: { - password: { - identifier: true + "ory.sh/kratos": { + "credentials": { + "password": { + "identifier": true } } } }, - name: { - type: 'object', - properties: { - first: { - type: 'string' + "name": { + "type": "object", + "properties": { + "first": { + "type": "string" }, - last: { - type: 'string' + "last": { + "type": "string" } } }, - favorite_animal: { - type: 'string' + "favorite_animal": { + "type": "string" }, - accepted_tos: { - type: 'string' + "accepted_tos": { + "type": "string" } }, - required: ['email'], - additionalProperties: false + "required": ["email"], + "additionalProperties": false } } } @@ -288,7 +290,7 @@ In this example, ORY Kratos understands that traits:email: `office@ory.sh` is the identity's identifier. The system expects `office@ory.sh` plus a password to sign in. -[Username and Password Credentials](credentials.md#username-and-password) +[Username and Password Credentials](credentials/username-email-password.mdx) contains more information and examples. There are currently no other extensions supported for Identity Traits. Further diff --git a/docs/docs/concepts/index.md b/docs/docs/concepts/index.md index 1c9325f6caa..0c51bb09087 100644 --- a/docs/docs/concepts/index.md +++ b/docs/docs/concepts/index.md @@ -230,7 +230,7 @@ ORY has numerous products that support the protocols OAuth2 or OpenID Connect in ### Software Architecture ORY's -[Software Architecture and Philosophy](../../ecosystem/software-architecture-philosophy) +[Software Architecture and Philosophy](https://www.ory.sh/docs/ecosystem/software-architecture-philosophy) document, explains the architectural beliefs and framework behind the ORY Products in particular: @@ -258,7 +258,7 @@ very easy to get started there is a reference implementation [github.com/ory/kratos-selfservice-ui-node](https://github.com/ory/kratos-selfservice-ui-node). For more details about each individual flow, consult the -[Self-Service Flows Chapter](../self-service/flows/index). +[Self-Service Flows Chapter](../self-service.mdx). ### Bring your own Identity Model(s) diff --git a/docs/static/img/docs/mailslurper-quickstart.png b/docs/docs/images/quickstart/mailslurper-quickstart.png similarity index 100% rename from docs/static/img/docs/mailslurper-quickstart.png rename to docs/docs/images/quickstart/mailslurper-quickstart.png diff --git a/docs/docs/images/quickstart/quickstart-recover-i.png b/docs/docs/images/quickstart/quickstart-recover-i.png new file mode 100644 index 00000000000..1ed7adb2063 Binary files /dev/null and b/docs/docs/images/quickstart/quickstart-recover-i.png differ diff --git a/docs/docs/images/quickstart/quickstart-recover-ii.png b/docs/docs/images/quickstart/quickstart-recover-ii.png new file mode 100644 index 00000000000..6cd68d3c4cb Binary files /dev/null and b/docs/docs/images/quickstart/quickstart-recover-ii.png differ diff --git a/docs/static/img/docs/quickstart-recover-iii.png b/docs/docs/images/quickstart/quickstart-recover-iii.png similarity index 100% rename from docs/static/img/docs/quickstart-recover-iii.png rename to docs/docs/images/quickstart/quickstart-recover-iii.png diff --git a/docs/docs/images/quickstart/quickstart-recover-iv.png b/docs/docs/images/quickstart/quickstart-recover-iv.png new file mode 100644 index 00000000000..b3ff4a5c8f2 Binary files /dev/null and b/docs/docs/images/quickstart/quickstart-recover-iv.png differ diff --git a/docs/static/img/docs/secureapp-dashboard.png b/docs/docs/images/quickstart/secureapp-dashboard.png similarity index 100% rename from docs/static/img/docs/secureapp-dashboard.png rename to docs/docs/images/quickstart/secureapp-dashboard.png diff --git a/docs/docs/images/quickstart/secureapp-login-ntrace.png b/docs/docs/images/quickstart/secureapp-login-ntrace.png new file mode 100644 index 00000000000..3225adb713a Binary files /dev/null and b/docs/docs/images/quickstart/secureapp-login-ntrace.png differ diff --git a/docs/docs/images/quickstart/secureapp-login.png b/docs/docs/images/quickstart/secureapp-login.png new file mode 100644 index 00000000000..2b53ab489a2 Binary files /dev/null and b/docs/docs/images/quickstart/secureapp-login.png differ diff --git a/docs/docs/images/quickstart/secureapp-registration-ntrace.png b/docs/docs/images/quickstart/secureapp-registration-ntrace.png new file mode 100644 index 00000000000..e0de38397bb Binary files /dev/null and b/docs/docs/images/quickstart/secureapp-registration-ntrace.png differ diff --git a/docs/docs/images/quickstart/secureapp-registration-pwpolicy.png b/docs/docs/images/quickstart/secureapp-registration-pwpolicy.png new file mode 100644 index 00000000000..c23407de641 Binary files /dev/null and b/docs/docs/images/quickstart/secureapp-registration-pwpolicy.png differ diff --git a/docs/docs/images/quickstart/secureapp-registration.png b/docs/docs/images/quickstart/secureapp-registration.png new file mode 100644 index 00000000000..3e79a16101d Binary files /dev/null and b/docs/docs/images/quickstart/secureapp-registration.png differ diff --git a/docs/static/img/docs/secureapp-verified-dashboard.png b/docs/docs/images/quickstart/secureapp-verified-dashboard.png similarity index 100% rename from docs/static/img/docs/secureapp-verified-dashboard.png rename to docs/docs/images/quickstart/secureapp-verified-dashboard.png diff --git a/docs/docs/quickstart.mdx b/docs/docs/quickstart.mdx index f45fd9d3a3f..1594c464a2d 100644 --- a/docs/docs/quickstart.mdx +++ b/docs/docs/quickstart.mdx @@ -3,8 +3,8 @@ id: quickstart title: Quickstart --- -import useBaseUrl from '@docusaurus/useBaseUrl' import Mermaid from '@theme/Mermaid' +import CodeFromRemote from '@theme/CodeFromRemote' ORY Kratos has several moving parts and getting everything right from the beginning can be challenging. This getting started guide will help you install @@ -54,8 +54,7 @@ needs users. Therefore, we need: and of course: -- A dashboard that shows "Hello {{ firstName }} {{ lastName }}, your birthday is - on {{ birthday }}!" which is only visible when the user is signed in. +- A dashboard that shows `Hello {{ traits.name.first }} {{ traits.name.last }}}!` which is only visible when the user is signed in. ## Setup @@ -66,32 +65,11 @@ templating engine. We will implement all the user-facing UIs like "dashboard", To ensure that no one can access the dashboard without prior authentication (login), we can use a small piece of code (here ExpressJS) to do that: -```js -// Import the ORY Kratos SDK. SDKs are available for all popular programming -// languages! We will add examples for other programming languages here soon. -import { AdminApi, PublicApi } from '@oryd/kratos-client' - -const publicEndpoint = new PublicApi('https://public.ory-kratos') -const adminEndpoint = new AdminApi('https://admin.ory-kratos') - -const needsLogin = (req, res, next) => { - new publicEndpoint.whoami(req) - .then(({ body }) => { - req.user = { session: body } - next() - }) - .catch(() => { - res.redirect('/login') - }) -} - -// You can use `needsLogin` as a middleware for Express or any other web framework: -// import express from 'express' -// const app = express() -// -// app.get("/dashboard", needsLogin, dashboard) -// -``` + :::info @@ -100,42 +78,12 @@ and more so you don't have to. ::: -Because our SecureApp and ORY Kratos need to share cookies, in order for -anti-CSRF tokens and login sessions to work, we will set up a path which -forwards requests to ORY Kratos' Public API so that both SecureApp and ORY -Kratos have the same hostname. - -If an HTTP request is made to - -``` -https://my-secureapp/.ory/kratos/public/self-service/browser/flows/login -``` - -we forward the request (like a proxy) to - -``` -https://public.ory-kratos/self-service/browser/flows/login -``` - -and pipe the response back to the initial HTTP Request: - -```js -import express from 'express' -import request from 'request' -const app = express() - -const pathPrefix = '/.ory/kratos/public' -app.use(pathPrefix + '/', (req, res) => { - const url = 'https://public.ory-kratos' + req.url.replace(pathPrefix, '') - - // Uses the `request` library to forward the request to ORY Kratos - req.pipe(request(url, { followRedirect: false })).pipe(res) -}) - -// ... -// app.get("/dashboard", needsLogin, dashboard) -// ... -``` +The SecureApp and ORY Kratos need to share cookies in order for anti-CSRF tokens and +login sessions to work. Because the quickstart runs on different ports on `127.0.0.1` +there is nothing we need to do to get this all working. In environments where you have +multiple sub-domains or reverse proxies, the set up will be a bit more sophisticated. +You can find more information about the different set up possibilities in the +[Getting Cookies to Work on Multi-Domains Guide](guides/multi-domain-cookies.mdx). ORY Kratos does not ship with an administrative user interface. You must implement that yourself or choose the ORY Cloud offering (to be announced). In @@ -215,28 +163,14 @@ Future guides will explain how to set up a production system. This demo makes use of several services: 1. [ORY Kratos](https://github.com/ory/kratos) - -- Public ("Browser") API (port 4433) -- Admin API (port 4434) - This is only made public so we can test via the CLI. - + - Public ("Browser") API (port 4433) + - Admin API (port 4434) - This is only made public so we can test via the CLI. 2. [SecureApp](http://github.com/ory/kratos-selfservice-ui-node) - -- Public (port 4455) - an example application written in NodeJS that implements - the login, registration, logout, dashboard, and other UIs. - + - Public (port 4455) - an example application written in NodeJS that implements + the login, registration, logout, dashboard, and other UIs. 3. [MailSlurper](https://github.com/mailslurper) - -- Public (port 4436) - a development SMTP server which ORY Kratos will use to - send emails. - -:::note - -ORY Kratos' Public ("Browser") and Admin APIs are exactly the same, except the -Public API will make use of extra browser-related security features. All -requests from a web browser should use ORY Kratos' Public API, while everything -else should use the Admin API. - -::: + - Public (port 4436) - a development SMTP server which ORY Kratos will use to + send emails. To better understand the application architecture, let's take a look at the network configuration. This assumes that you have at least some understanding of @@ -248,14 +182,16 @@ graph TD subgraph hn[Host Network] B[Browser] B-->|Can access URLs via 127.0.0.1:4455|OKPHN + B-->|Can access URLs via 127.0.0.1:4433|PAPI B-->|Can access UI via 127.0.0.1:4436|SMTPUI OKPHN([SecureApp exposed at :4455]) SMTPUI([MailSlurper UI exposed at :4436]) + PAPI([ORY Kratos Public API exposed at :4433]) end subgraph dn["Internal Docker Network (intranet)"] OKPHN-.->SA SMTPUI-.->SMTP - SA-->|Proxies URLs /.ory/kratos/public/* to|OK + PAPI-.->OK SA-->|Talks to and validates login sessions using|OK OK-->|Sends mail via|SMTP OK[ORY Kratos] @@ -265,10 +201,6 @@ end `} /> -In order to avoid common cross-domain issues with cookies, we're proxying -requests to ORY Kratos' Public API so that all requests come from the same -hostname. - ## Perform Registration, Login, and Logout Enough theory, it's time to get this thing going! Let's start by trying to open @@ -278,43 +210,29 @@ the dashboard - **go to You should notice that you're ending up at the login endpoint instead of the dashboard: -

- Login screen of your secured app -

+![Login screen of your secured app](images/quickstart/secureapp-login.png) Looking at the network stack, you can see two redirects happening: -

- Network trace of your secured app -

+![Network trace of your secured app](images/quickstart/secureapp-login-ntrace.png) Here's a play-by-play of what happened: 1. SecureApp used the ORY Kratos JavaScript language client to - [guard the `/dashboard`](https://github.com/ory/kratos-selfservice-ui-node/blob/v0.4.6-alpha.1/src/index.ts#L111) - route. The ORY Kratos client checked the cookies from the request and saw you - were not logged in. + guard the `/dashboard` route. The ORY Kratos client checked the cookies from the request and saw you were not logged in. 2. The route guard redirected you from `/dashboard` to `/auth/login`. ORY - Kratos' browser API requires a `request-id` in order to log you in. It looked + Kratos' browser API requires a `` in order to log you in. It looked for this ID in the URL as a query parameter but - [couldn't find it](https://github.com/ory/kratos-selfservice-ui-node/blob/2f097b519644d2663e277398213aaa1103b74cf9/src/routes/auth.ts#L26), - so it decided to generate one for you. + couldn't find it. 3. `/auth/login` redirected you to - `/.ory/kratos/public/self-service/browser/flows/login`, which is one of ORY - Kratos' APIs used for logging in browser-based applications. This route is - just forwarded from SecureApp to ORY Kratos. + `http://127.0.0.1:4433/self-service/login/browser`, which is one of ORY + Kratos' APIs used for logging in browser-based applications. 4. ORY Kratos performed some security checks, prepared form data, created a `csrf_token`, and redirected the browser to - `/auth/login?request=`. -5. SecureApp handled the `/auth/login` route, found the `request-id` in the URL + `/auth/login?flow=`. +5. SecureApp handled the `/auth/login` route, found the `` in the URL query parameter, and used it to make an HTTP request to - `http://kratos:4434/self-service/browser/flows/requests/login?request=`. + `http://kratos:4434/self-service/login/flows?id=`. Notice the URI is `kratos:4434` because SecureApp is making a server-side HTTP request via Docker's private network to ORY Kratos' Admin API. 6. ORY Kratos responded with data which SecureApp used to render the HTML login @@ -327,38 +245,26 @@ not work! ::: -Because we exposed ORY Kratos' Admin API on port `4434` of our host, we can use -`curl` to see what ORY Kratos responds with. Try visiting -`http://127.0.0.1:4455/auth/login`, copying the generated `request-id`, and +We can use `curl` to see what ORY Kratos responds with. Try visiting +`http://127.0.0.1:4455/auth/login`, copying the generated ``, and making the request yourself: ```shell script -$ curl "http://127.0.0.1:4434/self-service/browser/flows/requests/login?request=" | jq +# curl -s "http://127.0.0.1:4434/self-service/login/flows?id=ee6e1565-d3c3-4f3a-a6ff-0ba6b3a6481b" \ +$ curl -s "http://127.0.0.1:4434/self-service/login/flows?id=" \ + | jq + { - "id": "4392b0ef-647a-4cf8-8045-57917b98e406", - "expires_at": "2020-05-15T21:23:41.3220299Z", - "issued_at": "2020-05-15T21:13:41.3220454Z", - "request_url": "http://kratos:4433/self-service/browser/flows/login", + "id": "ee6e1565-d3c3-4f3a-a6ff-0ba6b3a6481b", + "type": "browser", + "expires_at": "2020-09-13T10:49:54.8295242Z", + "issued_at": "2020-09-13T10:39:54.8295242Z", + "request_url": "http://127.0.0.1:4433/self-service/login/browser", "methods": { - "oidc": { - "method": "oidc", - "config": { - "action": "http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/registration/strategies/oidc/auth/4392b0ef-647a-4cf8-8045-57917b98e406", - "method": "POST", - "fields": [ - { - "name": "csrf_token", - "type": "hidden", - "required": true, - "value": "L3SmxtBF71wd6QLOqIdHbhg9OTLRrxyXm1LVWRfPlUAdxwNKwpy9wPe/pKtJqnpqnAB8ZfZp5yJypVTk+7wRuA==" - } - ] - } - }, "password": { "method": "password", "config": { - "action": "http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/login/strategies/password?request=4392b0ef-647a-4cf8-8045-57917b98e406", + "action": "http://127.0.0.1:4433/self-service/login/methods/password?flow=ee6e1565-d3c3-4f3a-a6ff-0ba6b3a6481b", "method": "POST", "fields": [ { @@ -376,7 +282,7 @@ $ curl "http://127.0.0.1:4434/self-service/browser/flows/requests/login?request= "name": "csrf_token", "type": "hidden", "required": true, - "value": "L3SmxtBF71wd6QLOqIdHbhg9OTLRrxyXm1LVWRfPlUAdxwNKwpy9wPe/pKtJqnpqnAB8ZfZp5yJypVTk+7wRuA==" + "value": "lNrB8sW2fZY6xnnA91V7ISYrUVcJbmRCOoGHjsnsfI7MsIL5RTbuWFm5TRv1azQW+7IRCfnt2Ch6pC42/45sJQ==" } ] } @@ -393,84 +299,74 @@ etc.), head over to the [concept](concepts/index.md) chapter. Let's move on to the next flow - registration! Click on "Register new account", which initiates a flow similar to the one we just used: -

- Registration screen of your secured app -

+![Registration screen of your secured app](images/quickstart/secureapp-registration.png) The network trace should look familiar by now: -

- Registration with network trace screen of your secured app -

+![Registration with network trace screen of your secured app](images/quickstart/secureapp-registration-ntrace.png) If we try to sign up using a password like `123456`, Krato's password policy will complain: -

- Registration with network trace screen of your secured app -

+![Registration with network trace screen of your secured app](images/quickstart/secureapp-registration-pwpolicy.png) The error message is coming directly from ORY Kratos' Admin API: ```shell script -$ curl "http://127.0.0.1:4434/self-service/browser/flows/requests/registration?request=" | jq +# curl -s "http://127.0.0.1:4433/self-service/registration/flows?id=2b1f8c5d-e830-4068-97b8-35f776df9217" \ +$ curl -s "http://127.0.0.1:4433/self-service/registration/flows?id=" \ + | jq + { - "id": "53e4b68a-5f85-4e41-997f-d8d1f4113f0d", - "expires_at": "2020-05-15T21:48:38.5044374Z", - "issued_at": "2020-05-15T21:38:38.5044557Z", - "request_url": "http://kratos:4433/self-service/browser/flows/registration", + "id": "2b1f8c5d-e830-4068-97b8-35f776df9217", + "type": "browser", + "expires_at": "2020-09-13T10:53:15.1774019Z", + "issued_at": "2020-09-13T10:43:15.1774019Z", + "request_url": "http://127.0.0.1:4433/self-service/registration/browser", + "active": "password", + "messages": null, "methods": { - "oidc": { - "method": "oidc", - "config": { - "action": "http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/registration/strategies/oidc/auth/53e4b68a-5f85-4e41-997f-d8d1f4113f0d", - "method": "POST", - "fields": [ - { - "name": "csrf_token", - "type": "hidden", - "required": true, - "value": "tZUvp+2dSThQr0uklkfgWPRtPiYEyZQlBItc2RcIYdSHJoor/0QbpLr57cF3at1ccFB7cSMPb5DtfN1k+3vlLA==" - } - ] - } - }, "password": { "method": "password", "config": { - "action": "http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/registration/strategies/password?request=53e4b68a-5f85-4e41-997f-d8d1f4113f0d", + "action": "http://127.0.0.1:4433/self-service/registration/methods/password?flow=2b1f8c5d-e830-4068-97b8-35f776df9217", "method": "POST", "fields": [ { "name": "csrf_token", "type": "hidden", "required": true, - "value": "M0/Koo7AEdU6O/FqfFP5uPxTCSTeiCvI1Wms37ZKsyIB/G8unBlDSdBtVw+dfsS8eG5Mc/lO0H08ni1iWjk32g==" + "value": "1IlHWNjkAZxuYhO82WPgNTgujKsUSaW87j6og/20i2uM4wRTWGSSUg0dJ2fbXa8C5bfM9eTKGdauGwE7y9abwA==" }, { "name": "password", "type": "password", "required": true, - "errors": [ + "messages": [ { - "message": "the password does not fulfill the password policy because: the password has been found in at least 23547453 data breaches and must no longer be used." + "id": 4000005, + "text": "The password can not be used because the password has been found in at least 23597311 data breaches and must no longer be used..", + "type": "error", + "context": { + "reason": "the password has been found in at least 23597311 data breaches and must no longer be used." + } } ] }, { "name": "traits.email", "type": "text", - "required": false, - "value": "hello@ory.sh" + "value": "foo@ory.sh" + }, + { + "name": "traits.name.first", + "type": "text", + "value": "Ory" + }, + { + "name": "traits.name.last", + "type": "text", + "value": "Corp" } ] } @@ -482,12 +378,7 @@ $ curl "http://127.0.0.1:4434/self-service/browser/flows/requests/registration?r Setting a password that doesn't violate these policies, we will be immediately redirected to the dashboard: -

- SecureApp Dashboard -

+![SecureApp Dashboard](images/quickstart/secureapp-dashboard.png) By clicking the "logout" icon in the top right, you will be redirected to the login screen again where you will be able to use your credentials to log back in @@ -495,7 +386,7 @@ again. Exciting! ### Understanding How Login and Registration Works -Head over to the [Self-Service Flows Chapter](self-service/flows/index.md) for +Head over to the [Self-Service Flows Chapter](self-service.mdx) for an in-depth explanation of how each individual flow works. ### Email Verification @@ -507,12 +398,7 @@ You can retrieve the email however by opening the MailSlurper UI at You should see something like this: -

- User Email Verification -

+![User Email Verification](images/quickstart/mailslurper-quickstart.png) If not, hard refresh the tab or click on the home icon in the menu bar. @@ -520,12 +406,7 @@ Next, click the verification link. You will end up at the dashboard, with a verified email address (check the `verified` and `verified_at` field in the JSON response): -

- SecureApp Dashboard -

+![SecureApp Dashboard](images/quickstart/secureapp-verified-dashboard.png) To re-request the verification email, fill out the form at [127.0.0.1:4455/verify](http://127.0.0.1:4455/verify). @@ -538,39 +419,19 @@ To learn more about verification recovery, head over to the The quickstart has account recovery enabled. To recover an account, log out and click on "Recover account": -

- Click on 'recover account' -

+![Click on recover account](images/quickstart/quickstart-recover-i.png) The next screen shows a HTML form where you enter your email address: -

- Enter your email address -

+![Enter your email address](images/quickstart/quickstart-recover-ii.png) Hit "submit" and check the emails for the account recovery message: -

- Check your email for the password reset email -

+![Check your email for the password reset email](images/quickstart/quickstart-recover-iii.png) Click the link, and change your password: -

- Change your password -

+![Change your password](images/quickstart/quickstart-recover-iv.png) You are now able to sign in with the new password. To learn more about account recovery, head over to the @@ -647,7 +508,7 @@ UI or the Mailslurper. **Hooks** If you want to change the redirects happening after registration,login or a -settings change, take a look at this document: [Hooks](self-service/hooks). +settings change, take a look at this document: [Hooks](self-service/hooks.mdx). If you delete the `session` hook from `kratos.yml`, the user will _not_ be immediately signed in after registration. @@ -656,4 +517,4 @@ immediately signed in after registration. If you want to test ORY Kratos integration with different OIDC providers, you will find more information in this document: -[OIDC](guides/sign-in-with-github-google-facebook-linkedin) +[OIDC](guides/sign-in-with-github-google-facebook-linkedin.mdx) diff --git a/docs/docs/self-service/flows/account-recovery.mdx b/docs/docs/self-service/flows/account-recovery.mdx index edef2658d5d..53e210c40e9 100644 --- a/docs/docs/self-service/flows/account-recovery.mdx +++ b/docs/docs/self-service/flows/account-recovery.mdx @@ -202,12 +202,11 @@ browser: -To initialize the Recovery Flow, point the Browser to -[the initialization endpoint](../../self-service#initialization-and-redirect-to-ui): +To initialize the Recovery Flow, point the Browser to the initialization endpoint: @@ -218,8 +217,8 @@ parameter (see the curl example) to the URL configured here: selfservice: flows: recovery: - # becomes http://127.0.0.1:4455/auth/recovery?flow=df607aa1-d555-4b2a-b3e4-0f5a1d2fe6f3 - ui_url: http://127.0.0.1:4455/auth/recovery + # becomes http://127.0.0.1:4455/recovery?flow=df607aa1-d555-4b2a-b3e4-0f5a1d2fe6f3 + ui_url: http://127.0.0.1:4455/recovery ``` ### Recovery for API Clients @@ -234,20 +233,27 @@ The Recovery Flow for API clients does not use HTTP Redirects and can be summari interactions={['"Recover account"']} /> -To initialize the API flow ([REST API Reference](../reference/api#getSelfServiceRecoveryFlow)), the client [calls the API-flow initialization endpoint](../../self-service#initialization) +To initialize the API flow, the client calls the API-flow initialization endpoint ([REST API Reference](../../reference/api.mdx#initialize-recovery-flow-for-api-clients)) which returns a JSON response: ## Recovery Flow Payloads -Fetching the Recovery Flow ([REST API Reference](../reference/api#get-recovery-flow)) is usually only required for browser clients but also works +Fetching the Recovery Flow ([REST API Reference](../../reference/api.mdx#get-recovery-flow)) is usually only required for browser clients but also works for Recovery Flows initializied by API clients. All you need is a valid flow ID: ### Send Recovery Link to Email +:::note + +The `link` recovery mode will always open a link in the browser, even if it was initiated by an API client. +This is because the user clicks the link in his/her email client, which opens the browser. + +::: + When the `link` method is enabled, it will be part of the `methods` payload in the Recovery Flow: ```shell script diff --git a/docs/docs/self-service/flows/code/login/samples/get.curl.txt b/docs/docs/self-service/flows/code/login/samples/get.curl.txt index e6ac11eca7d..25a8748ce80 100644 --- a/docs/docs/self-service/flows/code/login/samples/get.curl.txt +++ b/docs/docs/self-service/flows/code/login/samples/get.curl.txt @@ -1,5 +1,5 @@ $ curl -H "Accept: application/json" -s - 'http://127.0.0.1:4434/self-service/login/flows?id=7c4260f5-55ad-470a-b1d4-e72dd011e4fe' | jq + 'http://127.0.0.1:4434/self-service/login/flows?id=7c4260f5-55ad-470a-b1d4-e72dd011e4fe' | jq { "id": "7c4260f5-55ad-470a-b1d4-e72dd011e4fe", diff --git a/docs/docs/self-service/flows/code/login/samples/oidc.missing.txt b/docs/docs/self-service/flows/code/login/samples/oidc.missing.txt index 8e43e02c4ff..f70981f13b6 100644 --- a/docs/docs/self-service/flows/code/login/samples/oidc.missing.txt +++ b/docs/docs/self-service/flows/code/login/samples/oidc.missing.txt @@ -1,5 +1,5 @@ $ curl -s -H "Accept: application/json" \ - 'http://127.0.0.1:4433/self-service/registration/flows?id=2e87577f-1209-407c-b523-4727d7bbdbd4' \ + 'http://127.0.0.1:4433/self-service/login/flows?id=2e87577f-1209-407c-b523-4727d7bbdbd4' \ | jq -r 'methods.oidc.config' { diff --git a/docs/docs/self-service/flows/code/login/samples/password.missing.txt b/docs/docs/self-service/flows/code/login/samples/password.missing.txt index 5ecba27fc46..a47cd091859 100644 --- a/docs/docs/self-service/flows/code/login/samples/password.missing.txt +++ b/docs/docs/self-service/flows/code/login/samples/password.missing.txt @@ -1,6 +1,6 @@ $ curl -H "Accept: application/json" -s \ - 'http://127.0.0.1:4433/self-service/login/flows?id=2e41015e-3b05-4e6a-8bc5-cdecf808d52e' \ - | jq -r '.methods.password.config' + 'http://127.0.0.1:4433/self-service/login/flows?id=2e41015e-3b05-4e6a-8bc5-cdecf808d52e' \ + | jq -r '.methods.password.config' { "action": "http://127.0.0.1:4433/self-service/login/methods/password?flow=2e41015e-3b05-4e6a-8bc5-cdecf808d52e", diff --git a/docs/docs/self-service/flows/code/login/samples/password.wrong.txt b/docs/docs/self-service/flows/code/login/samples/password.wrong.txt index 01c3b050e85..d140535a1e7 100644 --- a/docs/docs/self-service/flows/code/login/samples/password.wrong.txt +++ b/docs/docs/self-service/flows/code/login/samples/password.wrong.txt @@ -1,46 +1,35 @@ $ curl -H "Accept: application/json" -s \ - 'http://127.0.0.1:4433/self-service/registration/flows?id=cb264cfa-31d4-40cf-bb74-1c61abd7d298' \ - | jq -r '.methods.password.config' + 'http://127.0.0.1:4433/self-service/login/flows?id=4d1c07e0-4062-4609-a9fe-51b67bb0229c' \ + | jq -r '.methods.password.config' { - "action": "http://127.0.0.1:4433/self-service/registration/methods/password?flow=cb264cfa-31d4-40cf-bb74-1c61abd7d298", + "action": "http://127.0.0.1:4433/self-service/login/methods/password?flow=4d1c07e0-4062-4609-a9fe-51b67bb0229c", "method": "POST", "fields": [ { - "name": "csrf_token", - "type": "hidden", + "name": "identifier", + "type": "text", "required": true, - "value": "SRJdmk6+47L79ydSXNQyMIvfFChL51uZ16nTYw2WntUPNu5IWKzyJt9VmOTFPe6S3e/HqcVD/98dZorkreFGRg==" + "value": "idonotexist@ory.sh" }, { "name": "password", "type": "password", - "required": true, - "messages": [ - { - "id": 4000005, - "text": "The password can not be used because the password has been found in at least 23597311 data breaches and must no longer be used..", - "type": "error", - "context": { - "reason": "the password has been found in at least 23597311 data breaches and must no longer be used." - } - } - ] - }, - { - "name": "traits.email", - "type": "text", - "value": "foo@ory.sh" + "required": true }, { - "name": "traits.name.first", - "type": "text", - "value": "" - }, + "name": "csrf_token", + "type": "hidden", + "required": true, + "value": "+PvwKv2leJuBleZXkHwZHCgwybgu8eTazjCAV0OezmPCMtk5XjAk5vAyOdNn1ZHavl/2ksGDFN0/oD7D6KUdfg==" + } + ], + "messages": [ { - "name": "traits.name.last", - "type": "text", - "value": "" + "id": 4000006, + "text": "The provided credentials are invalid, check for spelling mistakes in your password or username, email address, or phone number.", + "type": "error", + "context": {} } ] } diff --git a/docs/docs/self-service/flows/code/registration/samples/browser/init.curl.txt b/docs/docs/self-service/flows/code/registration/samples/browser/init.curl.txt index 0135047ab7c..0773938f3f0 100644 --- a/docs/docs/self-service/flows/code/registration/samples/browser/init.curl.txt +++ b/docs/docs/self-service/flows/code/registration/samples/browser/init.curl.txt @@ -1,4 +1,5 @@ -curl -s -v -X GET \ +# Simulates a browser request +$ curl -s -v -X GET \ -H "Accept: text/html" \ http://127.0.0.1:4433/self-service/registration/browser diff --git a/docs/docs/self-service/flows/code/registration/samples/browser/init.html.txt b/docs/docs/self-service/flows/code/registration/samples/browser/init.html.txt index 4f33fe212eb..80ddaeb403e 100644 --- a/docs/docs/self-service/flows/code/registration/samples/browser/init.html.txt +++ b/docs/docs/self-service/flows/code/registration/samples/browser/init.html.txt @@ -1,4 +1,4 @@ -sign up +Sign up diff --git a/docs/docs/self-service/flows/code/registration/samples/get.curl.txt b/docs/docs/self-service/flows/code/registration/samples/get.curl.txt index 6dcf36f18b1..82d4c422111 100644 --- a/docs/docs/self-service/flows/code/registration/samples/get.curl.txt +++ b/docs/docs/self-service/flows/code/registration/samples/get.curl.txt @@ -1,5 +1,5 @@ $ curl -H "Accept: application/json" -s - 'http://127.0.0.1:4434/self-service/registration/flows?id=7c4260f5-55ad-470a-b1d4-e72dd011e4fe' | jq + 'http://127.0.0.1:4434/self-service/registration/flows?id=7c4260f5-55ad-470a-b1d4-e72dd011e4fe' | jq { "id": "7c4260f5-55ad-470a-b1d4-e72dd011e4fe", diff --git a/docs/docs/self-service/flows/code/registration/samples/oidc.invalid.txt b/docs/docs/self-service/flows/code/registration/samples/oidc.invalid.txt index 49ab54f73d7..11869708c18 100644 --- a/docs/docs/self-service/flows/code/registration/samples/oidc.invalid.txt +++ b/docs/docs/self-service/flows/code/registration/samples/oidc.invalid.txt @@ -1,6 +1,6 @@ -curl -H "Accept: application/json" -s \ - 'http://127.0.0.1:4433/self-service/registration/flows?id=f71b24aa-92d4-49a7-957b-72eea1c4c39d' \ - | jq -r '.methods.oidc.config' +$ curl -H "Accept: application/json" -s \ + 'http://127.0.0.1:4433/self-service/registration/flows?id=f71b24aa-92d4-49a7-957b-72eea1c4c39d' \ + | jq -r '.methods.oidc.config' { "action": "http://127.0.0.1:4433/self-service/methods/oidc/auth/f71b24aa-92d4-49a7-957b-72eea1c4c39d", diff --git a/docs/docs/self-service/flows/code/registration/samples/password.missing.txt b/docs/docs/self-service/flows/code/registration/samples/password.missing.txt index 6a5e202fc3a..0dc3115a66c 100644 --- a/docs/docs/self-service/flows/code/registration/samples/password.missing.txt +++ b/docs/docs/self-service/flows/code/registration/samples/password.missing.txt @@ -1,16 +1,16 @@ $ curl -H "Accept: application/json" -s \ - 'http://127.0.0.1:4433/self-service/registration/flows?id=e7fd5f9d-4ac4-40ba-bf39-8743f85360c5' \ - | jq -r '.methods.password.config' + 'http://127.0.0.1:4433/self-service/registration/flows?id=4187c805-3635-4a52-90ac-2e6a5ea3eaf5' \ + | jq -r '.methods.password.config' { - "action": "http://127.0.0.1:4433/self-service/registration/methods/password?flow=e7fd5f9d-4ac4-40ba-bf39-8743f85360c5", + "action": "http://127.0.0.1:4433/self-service/registration/methods/password?flow=4187c805-3635-4a52-90ac-2e6a5ea3eaf5", "method": "POST", "fields": [ { - "name": "identifier", - "type": "text", + "name": "csrf_token", + "type": "hidden", "required": true, - "value": "foo@ory.sh" + "value": "6PFc2kc+7Z7kAdpMrTe8TDrO9k1GyCb0sxsW3B29a5Ou1e8IUSz8CsCjZfo03mDubP4lzMhsgrJ51E9bvcqzAA==" }, { "name": "password", @@ -18,18 +18,41 @@ $ curl -H "Accept: application/json" -s \ "required": true }, { - "name": "csrf_token", - "type": "hidden", - "required": true, - "value": "G8J8PTctGsu7jx4zwed6CGefexw14Xyqi+IBeXNLPlap+0ywodiN1WsKZMTBrB670X4rK/mZPOiokmmOQYUUBw==" - } - ], - "messages": [ + "name": "traits.email", + "type": "text", + "value": "", + "messages": [ + { + "id": 4000001, + "text": "validation failed", + "type": "error" + }, + { + "id": 4000001, + "text": "\"\" is not valid \"email\"", + "type": "error" + }, + { + "id": 4000001, + "text": "length must be >= 3, but got 0", + "type": "error" + }, + { + "id": 4000001, + "text": "\"\" is not valid \"email\"", + "type": "error" + } + ] + }, + { + "name": "traits.name.first", + "type": "text", + "value": "ORY" + }, { - "id": 4000006, - "text": "The provided credentials are invalid, check for spelling mistakes in your password or username, email address, or phone number.", - "type": "error", - "context": {} + "name": "traits.name.last", + "type": "text", + "value": "GitHub" } ] } diff --git a/docs/docs/self-service/flows/code/registration/samples/password.policy.txt b/docs/docs/self-service/flows/code/registration/samples/password.policy.txt index 80df5ac974c..0fa7af1bf57 100644 --- a/docs/docs/self-service/flows/code/registration/samples/password.policy.txt +++ b/docs/docs/self-service/flows/code/registration/samples/password.policy.txt @@ -1,58 +1,46 @@ $ curl -H "Accept: application/json" -s \ - 'http://127.0.0.1:4433/self-service/registration/flows?id=4187c805-3635-4a52-90ac-2e6a5ea3eaf5' \ - | jq -r '.methods.password.config' + 'http://127.0.0.1:4433/self-service/registration/flows?id=6bc2f8f9-2898-41dd-836a-6f7d3915ffa7' \ + | jq -r '.methods.password.config' { - "action": "http://127.0.0.1:4433/self-service/registration/methods/password?flow=4187c805-3635-4a52-90ac-2e6a5ea3eaf5", + "action": "http://127.0.0.1:4433/self-service/registration/methods/password?flow=6bc2f8f9-2898-41dd-836a-6f7d3915ffa7", "method": "POST", "fields": [ { "name": "csrf_token", "type": "hidden", "required": true, - "value": "6PFc2kc+7Z7kAdpMrTe8TDrO9k1GyCb0sxsW3B29a5Ou1e8IUSz8CsCjZfo03mDubP4lzMhsgrJ51E9bvcqzAA==" + "value": "l8hejwA1NtpRWGq28lw7WjotmGiZg6YedrZ2WOcCp8KtAXeco6BqpyD/tTIF9bOcrEKnQnbxVhmHJsjMTDl03w==" }, { "name": "password", "type": "password", - "required": true - }, - { - "name": "traits.email", - "type": "text", - "value": "", + "required": true, "messages": [ { - "id": 4000001, - "text": "validation failed", - "type": "error" - }, - { - "id": 4000001, - "text": "\"\" is not valid \"email\"", - "type": "error" - }, - { - "id": 4000001, - "text": "length must be >= 3, but got 0", - "type": "error" - }, - { - "id": 4000001, - "text": "\"\" is not valid \"email\"", - "type": "error" + "id": 4000005, + "text": "The password can not be used because the password has been found in at least 23597311 data breaches and must no longer be used..", + "type": "error", + "context": { + "reason": "the password has been found in at least 23597311 data breaches and must no longer be used." + } } ] }, + { + "name": "traits.email", + "type": "text", + "value": "foo@ory.sh" + }, { "name": "traits.name.first", "type": "text", - "value": "ORY" + "value": "" }, { "name": "traits.name.last", "type": "text", - "value": "GitHub" + "value": "" } ] } diff --git a/docs/docs/self-service/flows/code/settings/index.js b/docs/docs/self-service/flows/code/settings/index.js index 9e8beb75495..41a9534811f 100644 --- a/docs/docs/self-service/flows/code/settings/index.js +++ b/docs/docs/self-service/flows/code/settings/index.js @@ -90,7 +90,7 @@ export const getFlowMethodPasswordWithErrors = { alt: 'User Registration HTML Form with validation errors' }, missing: { - label: 'Missing Email', + label: 'Missing Password', language: 'shell', code: require('raw-loader!./samples/password.missing.txt').default }, diff --git a/docs/docs/self-service/flows/code/settings/samples/api/init-unauth.curl.txt b/docs/docs/self-service/flows/code/settings/samples/api/init-unauth.curl.txt index 30bed1c6855..54bedc1c99e 100644 --- a/docs/docs/self-service/flows/code/settings/samples/api/init-unauth.curl.txt +++ b/docs/docs/self-service/flows/code/settings/samples/api/init-unauth.curl.txt @@ -1,3 +1,5 @@ +# Using the ORY Kratos Public API (:4433) without a session token +# returns an HTTP 403 error. $ curl -s -X GET \ -H "Accept: application/json" \ http://127.0.0.1:4433/self-service/settings/api | jq diff --git a/docs/docs/self-service/flows/code/settings/samples/browser/init.html.txt b/docs/docs/self-service/flows/code/settings/samples/browser/init.html.txt index 51511e5e1c4..9d1e61b4eff 100644 --- a/docs/docs/self-service/flows/code/settings/samples/browser/init.html.txt +++ b/docs/docs/self-service/flows/code/settings/samples/browser/init.html.txt @@ -1,4 +1,4 @@ -Log in +Update Profile diff --git a/docs/docs/self-service/flows/code/settings/samples/get.go.txt b/docs/docs/self-service/flows/code/settings/samples/get.go.txt index 0727236339c..69bb977ce73 100644 --- a/docs/docs/self-service/flows/code/settings/samples/get.go.txt +++ b/docs/docs/self-service/flows/code/settings/samples/get.go.txt @@ -11,7 +11,8 @@ import ( func main() { c := client.NewHTTPClientWithConfig(nil, - &client.TransportConfig{Host: "127.0.0.1:4433", BasePath: "/", Schemes: []string{"http"}}) + // We are using the ORY Kratos Admin API (:4434) to avoid having to set the session cookie / session token: + &client.TransportConfig{Host: "127.0.0.1:4434", BasePath: "/", Schemes: []string{"http"}}) flowID := "" // Usually something like: res.Request.URL.Query().Get("flow") diff --git a/docs/docs/self-service/flows/code/settings/samples/get.js.txt b/docs/docs/self-service/flows/code/settings/samples/get.js.txt index 0863b1ce659..77e0bdcde93 100644 --- a/docs/docs/self-service/flows/code/settings/samples/get.js.txt +++ b/docs/docs/self-service/flows/code/settings/samples/get.js.txt @@ -1,6 +1,7 @@ import {CommonApi} from '@oryd/kratos-client' -const kratos = new CommonApi('http://127.0.0.1:4433/') +// We are using the ORY Kratos Admin API (:4434) to avoid having to set the session cookie / session token: +const kratos = new CommonApi('http://127.0.0.1:4434/') const flowId = '' // usually something like: req.query.flow diff --git a/docs/docs/self-service/flows/code/verification/images/browser-challenge-completed.png b/docs/docs/self-service/flows/code/verification/images/browser-challenge-completed.png new file mode 100644 index 00000000000..44a2677c87c Binary files /dev/null and b/docs/docs/self-service/flows/code/verification/images/browser-challenge-completed.png differ diff --git a/docs/docs/self-service/flows/code/verification/index.js b/docs/docs/self-service/flows/code/verification/index.js index 4316cc398f9..d2aca4f05e5 100644 --- a/docs/docs/self-service/flows/code/verification/index.js +++ b/docs/docs/self-service/flows/code/verification/index.js @@ -65,8 +65,8 @@ export const initApiFlow = { export const getFlowMethodLinkWithErrors = { browser: { label: 'Browser UI', - image: require('./images/browser-email-missing.png').default, - alt: 'Account Recovery HTML Form with validation errors' + image: require('./images/browser-missing.png').default, + alt: 'Email Verification and Account Activation HTML Form with validation errors' }, missing: { label: 'Missing Email', @@ -79,7 +79,7 @@ export const getFlowMethodLinkSuccess = { browser: { label: 'Browser UI', image: require('./images/browser-success.png').default, - alt: 'Account Recovery HTML Form with success message' + alt: 'Email Verification and Account Activation HTML Form with success message' }, missing: { label: 'Email Sent', @@ -92,7 +92,7 @@ export const getFlowMethodLinkInvalidChallenge = { browser: { label: 'Browser UI', image: require('./images/browser-invalid-challenge.png').default, - alt: 'Account Recovery HTML Form with an invalid challenge' + alt: 'Email Verification and Account Activation HTML Form with an invalid challenge' }, missing: { label: 'Invalid Challenge', @@ -104,12 +104,12 @@ export const getFlowMethodLinkInvalidChallenge = { export const getFlowMethodLinkChallengeDone = { browser: { label: 'Browser UI', - image: require('./images/browser-settings-success.png').default, - alt: 'Account Recovery HTML Form with an invalid challenge' + image: require('./images/browser-challenge-completed.png').default, + alt: 'Email Verification and Account Activation HTML Form with an invalid challenge' }, missing: { - label: 'Update Credentials', + label: 'Success State', language: 'shell', - code: require('raw-loader!./samples/settings.success.txt').default + code: require('raw-loader!./samples/link.passed.txt').default } } diff --git a/docs/docs/self-service/flows/code/verification/samples/link.missing.txt b/docs/docs/self-service/flows/code/verification/samples/link.missing.txt index db9593ff9ed..3dcad2dd5a8 100644 --- a/docs/docs/self-service/flows/code/verification/samples/link.missing.txt +++ b/docs/docs/self-service/flows/code/verification/samples/link.missing.txt @@ -1,8 +1,8 @@ $ curl -H "Accept: application/json" -s \ - 'http://127.0.0.1:4433/self-service/recovery/flows?id=73fcb010-da5c-4eb9-b329-3ed677a6897b' | jq -r '.methods.link.config' + 'http://127.0.0.1:4433/self-service/verification/flows?id=73fcb010-da5c-4eb9-b329-3ed677a6897b' | jq -r '.methods.link.config' { - "action": "http://127.0.0.1:4433/self-service/recovery/methods/link?flow=73fcb010-da5c-4eb9-b329-3ed677a6897b", + "action": "http://127.0.0.1:4433/self-service/verification/methods/link?flow=73fcb010-da5c-4eb9-b329-3ed677a6897b", "method": "POST", "fields": [ { diff --git a/docs/docs/self-service/flows/code/verification/samples/link.passed.txt b/docs/docs/self-service/flows/code/verification/samples/link.passed.txt new file mode 100644 index 00000000000..3b071a38ad9 --- /dev/null +++ b/docs/docs/self-service/flows/code/verification/samples/link.passed.txt @@ -0,0 +1,5 @@ +$ curl -H "Accept: application/json" -s \ + 'http://127.0.0.1:4434/self-service/verification/flows?id=eb2aa29b-a726-4477-8635-9d5830f543fc' \ + | jq -r '.state' + +passed_challenge diff --git a/docs/docs/self-service/flows/user-login-user-registration.mdx b/docs/docs/self-service/flows/user-login-user-registration.mdx deleted file mode 100644 index b72d8fe4b95..00000000000 --- a/docs/docs/self-service/flows/user-login-user-registration.mdx +++ /dev/null @@ -1,356 +0,0 @@ ---- -id: user-login-user-registration -title: User Login And Registration -sidebar_label: Overview ---- - -import Mermaid from '@theme/Mermaid' -import Tabs from '@theme/Tabs' -import TabItem from '@theme/TabItem' - -// import InitBrowserFlow from '@theme/Code/Login/InitBrowserFlow' -import SelfServiceBrowserFlow from '@theme/SelfServiceBrowserFlow' -import SelfServiceAPIFlow from '@theme/SelfServiceAPIFlow' -import CodeFromRemote from '@theme/CodeFromRemote' - -There are two login and registration flow types supported in ORY Kratos: - -- Flows where the user sits in front of the Browser (e.g. website, single page - app, ...) -- Flows where API interaction is required (e.g. mobile app, Smart TV, ...) - -The login and registration flows documented here are the foundation for the -[password](user-login-user-registration/username-email-password.mdx) and -[social](user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx) -sign in and sign up methods. - -:::note - -Please read the [Self-Service Flows](../../self-service) overview before -continuing with this document. - -::: - - s1 : User clicks "Log in / Sign up" - s1 --> s2 - s2 --> Error : A hook fails - s2 --> s3 - s3 --> s4 : User provides valid credentials/registration data - s3 --> s5 : User provides invalid credentials/registration data - s5 --> s3 - s4 --> Error : A hook fails - s4 --> s6 - s6 --> [*] - Error --> [*] -`} -/> - -## Self-Service User Login and User Registration for Browser Applications - -Each Login and Registration Method (e.g. -[Username and Password](user-login-user-registration/username-email-password.mdx), -[Social Sign In](user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx), -Passwordless, ...) works a bit different but they all boil down to the same -abstract sequence. This sequence was already established in the -[Self-Service Browser Flow Documentation](../../self-service#browser-flows). - - - -The flow payload and the form data the browser sends depend on the concrete flow -(registration, login) and method -([Username and Password](user-login-user-registration/username-email-password.mdx), -[Social Sign In](user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx)). - -The _Flow UI_ (**your application!**) is responsible for rendering the actual -Login and Registration HTML Forms. You can of course implement one app for -rendering all the Login, Registration, ... screens, and another app (think -"Service Oriented Architecture", "Micro-Services" or "Service Mesh") is -responsible for rendering your Dashboards, Management Screens, and so on. - -### Initialization and Redirect to UI - -To initialize the Login or Registration flow, point the Browser to -[the initialization endpoint](../../self-service#initialization-and-redirect-to-ui): - - - - - - - -for login (`/self-service/login/browser`) or registration -(`/self-service/registration/browser`) and is redirected to the UI configured at - -```yaml title="path/to/config/kratos.yml" -selfservice: - flows: - login: - ui_url: http://... - registration: - ui_url: http://... -``` - -### Login and Registration Form Rendering - -The Login and Registration User Interface is a route (page / site) in your -application (both server side application or single page app) that should render -a sign in and registration form: - - - - -```html -
- - - - -
-``` - - - - -```html -
- - - - - - -
-``` - - - - -Depending on the type of login flows you want to support, you may also add a -"Sign up/in with GitHub" flow: - - - - -```html -
- - - Sign in with: - - - -
-``` - - - - -```html -
- - - Sign up with: - - - -
-``` - - - - -In stark contrast to other Identity Systems, ORY Kratos does not render this -HTML. Instead, you need to implement the HTML code in your application (e.g. -NodeJS + ExpressJS, Java, PHP, ReactJS, ...), which gives you extreme -flexibility and customizability in your user interface flows and designs. - -### Code Examples - -Because Login and Registration are so similar, we can use one common piece of -code to cover both. A functioning example of the code and approach used here can -be found on -[github.com/ory/kratos-selfservice-ui-node](https://github.com/ory/kratos-selfservice-ui-node). - - - - - - -The views can be rather simple, as ORY Kratos provides you with all the -information you need for rendering the forms. - -The following examples use Handlebars and a generic form generator to render the -Flow: - - - - - - - - - - - - - - - - - - - - - -The rest of the form partials can be found -[here](https://github.com/ory/kratos-selfservice-ui-node/tree/master/views/partials). - - - - -A react example is currently in the making. - - - - -For details on payloads consult the individual Self-Service Methods for: - -- [Username and Password Method](user-login-user-registration/username-email-password.mdx) -- [Social Sign In Method](user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx) - -## Self-Service User Login and User Registration for API Clients - -Each Login and Registration Method (e.g. -[Username and Password](user-login-user-registration/username-email-password.mdx), -[Social Sign In](user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx), -Passwordless, ...) works a bit different but they all boil down to the same -abstract sequence. This sequence was already established in the -[Self-Service API Flow Documentation](../../self-service#api-flows). - - - -The flow payload and the form data the browser sends depend on the concrete flow -(registration, login) and method -([Username and Password](user-login-user-registration/username-email-password.mdx), -[Social Sign In](user-login-user-registration/openid-connect-social-sign-in-oauth2.mdx)). - -### Initialization - -The client -[calls the API-flow initialization endpoint](../../self-service#initialization) -for login (`/self-service/login/api`) or registration -(`/self-service/login/api`). The response is a JSON payload containing -information about the flow. - -### Login and Registration Form Rendering - -The form is rendered as established in the -[API flow form rendering documentation](../../self-service#form-rendering-1). - -### Form Submission - -To submit the form, follow -[API flow form submission and payload validation](../../self-service#form-submission-and-payload-validation-1). - -### Code Examples - - - - -Code samples will follow soon - - - - -Code samples will follow soon - - - - -## Hooks - -ORY Kratos allows you to configure hooks that run before and after a Login or -Registration Request is generated. This may be helpful if you'd like to restrict -logins to IPs coming from your internal network or other logic. - -For more information about hooks please read the [Hook Documentation](../hooks). - -## Refreshing a Session - -In some cases it is required to refresh a login session. This is the case when -updating one's password. Refreshing a session updates the `authenticated_at` -time. - -:::info - -Refreshing a session will not log the user out, unless another user signs in. - -::: - -To refresh a session, append `?refresh=true` to `/self-service/login/browser`, -for example -`http://127.0.0.1:4455/.ory/kratos/public/self-service/login/browser?refresh=true`. diff --git a/docs/docs/self-service/flows/user-login.mdx b/docs/docs/self-service/flows/user-login.mdx index 916d133937e..e6787e46de6 100644 --- a/docs/docs/self-service/flows/user-login.mdx +++ b/docs/docs/self-service/flows/user-login.mdx @@ -53,7 +53,7 @@ stateDiagram Currently, two login methods are supported: - `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. +- `oidc` for signing in using a social sign in provider such as Google or Facebook (check out the [set up guide](../../guides/sign-in-with-github-google-facebook-linkedin.mdx)). Both are dis/enabled in the ORY Kratos config: @@ -83,8 +83,7 @@ browser: interactions={['"Log in"']} /> -To initialize the Login Flow, point the Browser to -[the initialization endpoint](../../self-service#initialization-and-redirect-to-ui): +To initialize the Login Flow, point the Browser to the initialization endpoint: @@ -111,14 +110,14 @@ The Login Flow for API clients does not use HTTP Redirects and can be summarized interactions={['"Log in"']} /> -To initialize the API flow ([REST API Reference](../reference/api#getSelfServiceLoginFlow)), the client [calls the API-flow initialization endpoint](../../self-service#initialization) +To initialize the API flow, the client calls the API-flow initialization endpoint ([REST API Reference](../../reference/api.mdx#initialize-login-flow-for-api-clients)) which returns a JSON response: ## Login Flow Payloads -Fetching the Login Flow ([REST API Reference](../reference/api#get-login-flow)) is usually only required for browser clients but also works +Fetching the Login Flow ([REST API Reference](../../reference/api.mdx#get-login-flow)) is usually only required for browser clients but also works for Login Flows initializied by API clients. All you need is a valid flow ID: @@ -136,48 +135,31 @@ When the `password` method is enabled, it will be part of the `methods` payload ```shell script $ curl -H "Accept: application/json" -s \ - 'http://127.0.0.1:4434/self-service/login/flows?id=2e41015e-3b05-4e6a-8bc5-cdecf808d52e' | jq + 'http://127.0.0.1:4434/self-service/login/flows?id=26ac2d66-eeb7-42f3-8ba8-5fe70925d6a3' \ + | jq -r '.methods.password.config' { - "id": "d5c78fd6-17e7-45e2-9465-0200c76bf83a", - "type": "browser", - "expires_at": "2020-08-24T11:58:06.0780652Z", - "issued_at": "2020-08-24T11:48:06.0780828Z", - "request_url": "http://127.0.0.1:4433/self-service/registration/browser", - "methods": { - "password": { - "method": "password", - "config": { - "action": "http://127.0.0.1:4433/self-service/registration/methods/password?flow=d5c78fd6-17e7-45e2-9465-0200c76bf83a", - "method": "POST", - "fields": [ - { - "name": "csrf_token", - "type": "hidden", - "required": true, - "value": "NeScRZ0rccVGilfS2dvlSjDnYk/EvhpozPKW3TBeAnpCArwCFt2La1xbxeFFnmFycdg1LngGTeA13HJ1XCccQA==" - }, - { - "name": "password", - "type": "password", - "required": true - }, - { - "name": "traits.email", - "type": "email" - }, - { - "name": "traits.name.first", - "type": "text" - }, - { - "name": "traits.name.last", - "type": "text" - } - ] - } + "action": "http://127.0.0.1:4433/self-service/login/methods/password?flow=26ac2d66-eeb7-42f3-8ba8-5fe70925d6a3", + "method": "POST", + "fields": [ + { + "name": "identifier", + "type": "text", + "required": true, + "value": "" + }, + { + "name": "password", + "type": "password", + "required": true + }, + { + "name": "csrf_token", + "type": "hidden", + "required": true, + "value": "Bo72oeXYFnjZj2B9Ple+GZBkn5oqQZDACcYvGeUi8J48R9+yRk1KBagov/nJ/jbfBgugsMUzYMf4VpGNThkjgw==" } - } + ] } ``` @@ -214,37 +196,25 @@ configured sign in providers as submit fields: ```shell script $ curl -H "Accept: application/json" -s \ - 'http://127.0.0.1:4433/self-service/registration/flows?id=7430f336-0be0-47d1-b1fc-5cc6fcc3f228' | jq + 'http://127.0.0.1:4434/self-service/login/flows?id=26ac2d66-eeb7-42f3-8ba8-5fe70925d6a3' \ + | jq -r '.methods.oidc.config' { - "id": "7430f336-0be0-47d1-b1fc-5cc6fcc3f228", - "type": "browser", - "expires_at": "2020-09-03T14:32:44.060729362Z", - "issued_at": "2020-09-03T14:22:44.060729362Z", - "request_url": "http://127.0.0.1:4433/self-service/registration/browser", - "messages": null, - "methods": { - "oidc": { - "method": "oidc", - "config": { - "action": "http://127.0.0.1:4433/self-service/methods/oidc/auth/7430f336-0be0-47d1-b1fc-5cc6fcc3f228", - "method": "POST", - "fields": [ - { - "name": "csrf_token", - "type": "hidden", - "required": true, - "value": "LJ3o59zXjukFs1004vyn3QrWDrfutW2e0Iaqo/9Ck6srYAceydRr59GEZJNFY6Walnell+r10/DlXUy/Eq6sXQ==" - }, - { - "name": "provider", - "type": "submit", - "value": "github" - } - ] - } + "action": "http://127.0.0.1:4433/self-service/methods/oidc/auth/7430f336-0be0-47d1-b1fc-5cc6fcc3f228", + "method": "POST", + "fields": [ + { + "name": "csrf_token", + "type": "hidden", + "required": true, + "value": "LJ3o59zXjukFs1004vyn3QrWDrfutW2e0Iaqo/9Ck6srYAceydRr59GEZJNFY6Walnell+r10/DlXUy/Eq6sXQ==" + }, + { + "name": "provider", + "type": "submit", + "value": "github" } - } + ] } ``` diff --git a/docs/docs/self-service/flows/user-registration.mdx b/docs/docs/self-service/flows/user-registration.mdx index 88e930f63f5..1ae59fa6c83 100644 --- a/docs/docs/self-service/flows/user-registration.mdx +++ b/docs/docs/self-service/flows/user-registration.mdx @@ -5,6 +5,7 @@ title: User Registration import Mermaid from '@theme/Mermaid' import ApiWarning from '@theme/ApiWarning' +import CodeFromRemote from '@theme/CodeFromRemote' import SelfServiceBrowserFlow from '@theme/SelfServiceBrowserFlow' import SelfServiceApiFlow from '@theme/SelfServiceApiFlow' @@ -14,8 +15,9 @@ import RenderFlow from '@theme/Code/RenderFlow' :::information -Please read the [Self-Service Flows](../../self-service) overview before -continuing with this document. +Please read the [Self-Service Flows](../../self-service.mdx) overview before +continuing with this document. It is also advised to run the [quickstart](../../quickstart.mdx) locally +as example URLs and payloads have been generated with it. ::: @@ -53,7 +55,7 @@ stateDiagram Currently, two registration methods are supported: - `password` for signing up with an email / username and password; -- `oidc` for signing up using a social sign in provider such as Google or Facebook. +- `oidc` for signing up using a social sign in provider such as Google or Facebook (check out the [set up guide](../../guides/sign-in-with-github-google-facebook-linkedin.mdx)). Both are dis/enabled in the ORY Kratos config: @@ -79,12 +81,11 @@ browser: -To initialize the Registration Flow, point the Browser to -[the initialization endpoint](../../self-service#initialization-and-redirect-to-ui): +To initialize the Registration Flow, point the Browser to the initialization endpoint: @@ -96,7 +97,7 @@ selfservice: flows: registration: # becomes http://127.0.0.1:4455/auth/registration?flow=df607aa1-d555-4b2a-b3e4-0f5a1d2fe6f3 - ui_url: http://127.0.0.1:4455/auth/registration + ui_url: http://127.0.0.1:4455/auth/registration ``` ### Registration for API Clients @@ -107,19 +108,20 @@ The Registration Flow for API clients does not use HTTP Redirects and can be sum -To initialize the API flow ([REST API Reference](../reference/api#getSelfServiceRegistrationFlow)), the client [calls the API-flow initialization endpoint](../../self-service#initialization) +To initialize the API flow, the client calls the API-flow initialization endpoint ([REST API Reference](../../reference/api.mdx#initialize-registration-flow-for-api-clients)) which returns a JSON response: ## Registration Form Payloads -Fetching the Registration Flow ([REST API Reference](../reference/api#get-registration-flow)) is usually only required for browser clients but also works -for Registration Flows initializied by API clients. All you need is a valid flow ID: +Fetching the Registration Flow ([REST API Reference](../../reference/api.mdx#get-registration-flow)) is usually only +required for browser clients but also works +for Registration Flows initializied by API clients. All you need is a valid Registration Flow ID: @@ -128,21 +130,20 @@ for Registration Flows initializied by API clients. All you need is a valid flow :::tip Before you start Please read the -[Username / Email & Password Credentials Documentation](../../concepts/credentials/username-email-password) first. +[Username / Email & Password Credentials Documentation](../../concepts/credentials/username-email-password.mdx) first. ::: When the `password` method is enabled, it will be part of the `methods` payload in the Registration Flow. - ORY Kratos uses the Identity JSON Schema defined in `identity.default_schema_url` to generate a list of form fields and add it to the Registration Flow. - Assuming we are using the Identity JSON Schema from the Quickstart the response would look as such: @@ -290,35 +291,35 @@ To complete the registration process, the end-user fills out the form which must include a field marked as the identifier (`ory.sh/kratos.credentials.password.identifier: true`) in the Identity JSON Schema, for example: -```json -{ - "$id": "https://schemas.ory.sh/presets/kratos/quickstart/email-password/identity.schema.json", - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Person", - "type": "object", - "properties": { - "traits": { - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email", - "ory.sh/kratos": { - "credentials": { - "password": { - "identifier": true - } - } - } - } - }, - "required": [ - "email" - ], - "additionalProperties": false - } - } -} +```diff + { + "$id": "https://schemas.ory.sh/presets/kratos/quickstart/email-password/identity.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Person", + "type": "object", + "properties": { + "traits": { + "type": "object", + "properties": { + "email": { + "type": "string", + "format": "email", ++ "ory.sh/kratos": { ++ "credentials": { ++ "password": { ++ "identifier": true ++ } ++ } ++ } + } + }, + "required": [ + "email" + ], + "additionalProperties": false + } + } + } ``` If the registration payload is invalid (e.g. the password does @@ -353,39 +354,39 @@ is returned to the registration screen with the form validation errors. Let's assume the ORY Kratos Identity Schema JSON requires a `website` trait -``` -{ - "$id": "https://schemas.ory.sh/presets/kratos/quickstart/email-password/identity.schema.json", - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Person", - "type": "object", - "properties": { - "traits": { - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email", - "ory.sh/kratos": { - "credentials": { - "password": { - "identifier": true - } - } - } - }, - "website": { - "type": "string" - } - }, - "required": [ - "email", - "website" - ], - "additionalProperties": false - } - } -} +```diff + { + "$id": "https://schemas.ory.sh/presets/kratos/quickstart/email-password/identity.schema.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Person", + "type": "object", + "properties": { + "traits": { + "type": "object", + "properties": { + "email": { + "type": "string", + "format": "email", + "ory.sh/kratos": { + "credentials": { + "password": { + "identifier": true + } + } + } + }, ++ "website": { ++ "type": "string" ++ } + }, + "required": [ + "email", ++ "website" + ], + "additionalProperties": false + } + } + } ``` which was not provided by the upstream identity provider. This can happen when the user refuses to accept a @@ -403,8 +404,8 @@ does not issue a ORY Kratos Login Session automatically which prevents Account E If these types of attacks are not your concern, you can add the session hook which will issue a session after successful registration: -```yaml title="path/to/my/kratos/config.yml" -# $ kratos -c path/to/my/kratos/config.yml serve +```yaml title="path/to/my/config/kratos.yml" +# $ kratos -c path/to/my/config/kratos.yml serve selfservice: flows: registration: @@ -495,8 +496,7 @@ curl -s -H "Cookie: ory_kratos_session=MTU5OTE2ODc2N3xEdi1CQkFFQ180SUFBUkFCRUFBQ ### API Clients -For API Clients, ORY Kratos responds with a JSON payload which includes the identity which -just authenticated, the session, and the ORY Kratos Session Token: +For API Clients, ORY Kratos responds with a JSON payload which includes the signed up identity: ```shell script # Inits a Registration Flow @@ -553,8 +553,8 @@ $ actionUrl=$(\ ) $ curl -s -X POST -H "Accept: application/json" -H "Content-Type: application/json" \ - -d '{"traits.email": "registration-session-api@user.org", "password": "fhAzi860a"}' \ - "$actionUrl" | jq + -d '{"traits.email": "registration-session-api@user.org", "password": "fhAzi860a"}' \ + "$actionUrl" | jq { "session_token": "9kmrgslvw8ZCyEtSZqOmxEtnfBJIvB31", @@ -623,4 +623,4 @@ $ curl -s -X POST -H "Accept: application/json" -H "Content-Type: application/j ORY Kratos allows you to configure hooks that run before and after a Registration Flow. This may be helpful if you'd like to restrict registration to IPs coming from your internal network or other logic. -For more information about hooks please read the [Hook Documentation](../hooks). +For more information about hooks please read the [Hook Documentation](../hooks.mdx). diff --git a/docs/docs/self-service/flows/user-settings.mdx b/docs/docs/self-service/flows/user-settings.mdx index 8dbfb135f4b..c3e0b7759fb 100644 --- a/docs/docs/self-service/flows/user-settings.mdx +++ b/docs/docs/self-service/flows/user-settings.mdx @@ -14,7 +14,7 @@ import RenderFlow from '@theme/Code/RenderFlow' :::information -Please read the [Self-Service Flows](../../self-service) overview before +Please read the [Self-Service Flows](../../self-service.mdx) overview before continuing with this document. ::: @@ -62,7 +62,7 @@ Currently, three settings methods are supported: - `password` for updating the password used to sign in; - `oidc` for un-/linking from social sign in providers such as Google or Facebook; - `profile` for updating an identity's traits (e.g. change the first name). The updated traits must be valid against the Identity JSON Schema defined for -its [Identity Traits](../../concepts/identity-user-model). +its [Identity Traits](../../concepts/identity-data-model.md). These methods are dis/enabled in the ORY Kratos config: @@ -85,7 +85,7 @@ Most Settings Flow Methods allow the user to update fields which are considered - The `profile` method allows updating protected fields such as - the username or email address used to sign in; - the recovery email address; -- The `oidc` method allows linking and unlinking from Google, Facebook, Github, ... which is considered a privileged action. +- The `oidc` method allows linking and unlinking from Google, Facebook, Github, ... which is considered a privileged action (check out the [set up guide](../../guides/sign-in-with-github-google-facebook-linkedin.mdx)). If any of these fields are changed, the ORY Kratos Login Session must not be older than the configured `privileged_session_max_age` value: @@ -109,14 +109,12 @@ If the ORY Kratos Login Session is older than the specified amount, the user is This end-user experience currently works only for Browser-based Settings Flows. API-based flows will simply return -a 403 Forbidden status message which require you to request a new ORY Kratos Login session using the [API-based Flow](user-login). +a 403 Forbidden status message which require you to request a new ORY Kratos Login session using the [API-based Login Flow](user-login.mdx). ## Initialize Settings Flow The first step is to initialize the settings flow. This allows pre-settings hooks to run, set up Anti-CSRF tokens, -and more. - -Each Settings Flow also has a `state` field which can either be `success` or `show_form`: +and more. Each Settings Flow also has a `state` field which can either be `success` or `show_form`: @@ -172,8 +170,8 @@ paremeter (see the curl example) to the URL configured here: selfservice: flows: settings: - # becomes http://127.0.0.1:4455/auth/settings?flow=df607aa1-d555-4b2a-b3e4-0f5a1d2fe6f3 - ui_url: http://127.0.0.1:4455/auth/settings + # becomes http://127.0.0.1:4455/settings?flow=df607aa1-d555-4b2a-b3e4-0f5a1d2fe6f3 + ui_url: http://127.0.0.1:4455/settings ``` ### Settings for API Clients @@ -184,11 +182,11 @@ The Settings Flow for API clients does not use HTTP Redirects and can be summari -To initialize the API flow ([REST API Reference](../reference/api#getSelfServiceSettingsFlow)), the client [calls the API-flow initialization endpoint](../../self-service#initialization) +To initialize the API flow, the client calls the API-flow initialization endpoint ([REST API Reference](../../reference/api.mdx#initialize-settings-flow-for-api-clients)) which returns a JSON response: @@ -381,7 +379,7 @@ Completing the settings update behaves differently for Browser and API Clients. ### Browser Clients -When the login is completed successfully, ORY Kratos responds with a HTTP 302 Redirect to the +When the profile update is completed successfully, ORY Kratos responds with a HTTP 302 Redirect to the Settings UI which now contains the success state (`state: success`) as well as the udpated identity: ```shell script @@ -486,4 +484,4 @@ $ curl -s -X POST -H "Accept: application/json" -H "Content-Type: application/js ORY Kratos allows you to configure hooks that run before and after a profile update was successful. For more information about hooks please read the -[Hook Documentation](../hooks). +[Hook Documentation](../hooks.mdx). diff --git a/docs/docs/self-service/flows/verify-email-account-activation.mdx b/docs/docs/self-service/flows/verify-email-account-activation.mdx index 780c09b0c6b..a0fe446b39f 100644 --- a/docs/docs/self-service/flows/verify-email-account-activation.mdx +++ b/docs/docs/self-service/flows/verify-email-account-activation.mdx @@ -32,7 +32,7 @@ There are two Verification Flow types supported in ORY Kratos: app, ...) - Flows where API interaction is required (e.g. mobile app, Smart TV, ...) -The Recovery Flow can be summarized as the following state machine: +The Verification Flow can be summarized as the following state machine: @@ -214,10 +213,11 @@ parameter (see the curl example) to the URL configured here: selfservice: flows: verification: - # becomes http://127.0.0.1:4455/auth/verification?flow=df607aa1-d555-4b2a-b3e4-0f5a1d2fe6f3 - ui_url: http://127.0.0.1:4455/auth/verification + # becomes http://127.0.0.1:4455/verification?flow=df607aa1-d555-4b2a-b3e4-0f5a1d2fe6f3 + ui_url: http://127.0.0.1:4455/verification ``` -### Recovery for API Clients + +### Verification for API Clients @@ -229,7 +229,7 @@ The Verification Flow for API clients does not use HTTP Redirects and can be sum interactions={['"Verify Email"']} /> -To initialize the API flow ([REST API Reference](../reference/api#getSelfServiceVerificationFlow)), the client [calls the API-flow initialization endpoint](../../self-service#initialization) +To initialize the API flow, the client calls the API-flow initialization endpoint ([REST API Reference](../../reference/api.mdx#initialize-verification-flow-for-api-clients)) which returns a JSON response: @@ -243,6 +243,13 @@ for Verification Flows initializied by API clients. All you need is a valid flow ### Send Verification Link to Email +:::note + +The `link` verification mode will always open a link in the browser, even if it was initiated by an API client. +This is because the user clicks the link in his/her email client, which opens the browser. + +::: + When the `link` method is enabled, it will be part of the `methods` payload in the Verification Flow: ```shell script @@ -336,12 +343,7 @@ Please keep in mind that this part of the flow always involves a Browser! If the verification challenge is completed (e.g. the sent verification link was clicked), the end-user's Browser is redirected to the Verification UI with a Verification Flow that has now the `state` of `passed_challenge`: -```shell script -$ curl -H "Accept: application/json" -s \ - 'http://127.0.0.1:4434/self-service/verification/flows?id=eb2aa29b-a726-4477-8635-9d5830f543fc' | jq -r '.state' - -passed_challenge -``` + You may also [configure a redirect URL](../../concepts/browser-redirect-flow-completion) instead which would send the end-user to that configured URL. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index c7c3b9de835..ec45e08d51d 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -56,6 +56,7 @@ if (fs.existsSync('./versions.json')) { } module.exports = { + onBrokenLinks: 'warn', title: config.projectName, tagline: config.projectTagLine, url: `https://www.ory.sh/`, diff --git a/docs/sidebar.json b/docs/sidebar.json index 9e99b74e78c..961f263b8f2 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -31,7 +31,6 @@ "self-service/flows/user-login", "self-service/flows/user-settings", "self-service/flows/account-recovery", - "self-service/flows/account-recovery/password-reset-recovery-link", "self-service/flows/verify-email-account-activation", "self-service/flows/user-logout", "self-service/flows/user-facing-errors", diff --git a/docs/src/theme/Code/RenderFlow.js b/docs/src/theme/Code/RenderFlow.js index bb326c17c5e..0c5ebbb5310 100644 --- a/docs/src/theme/Code/RenderFlow.js +++ b/docs/src/theme/Code/RenderFlow.js @@ -44,6 +44,7 @@ const RenderFlow = ({flow}) => { @@ -64,18 +65,21 @@ const RenderFlow = ({flow}) => { diff --git a/docs/src/theme/CodeFromRemote.js b/docs/src/theme/CodeFromRemote.js index 503fec2d0b3..42206d76215 100644 --- a/docs/src/theme/CodeFromRemote.js +++ b/docs/src/theme/CodeFromRemote.js @@ -1,8 +1,9 @@ import React, {useEffect, useState} from 'react' import fetch from 'node-fetch' import CodeBlock from '@theme/CodeBlock' +import styles from './CodeFromRemote.module.css'; -const CodeFromRemote = ({src,link}) => { +const CodeFromRemote = ({src, link, lang}) => { const [content, setContent] = useState('') useEffect(() => { @@ -10,9 +11,9 @@ const CodeFromRemote = ({src,link}) => { }, []) return ( - <> - - +
+ +
) } diff --git a/docs/src/theme/CodeFromRemote.module.css b/docs/src/theme/CodeFromRemote.module.css new file mode 100644 index 00000000000..87e8c19b4e1 --- /dev/null +++ b/docs/src/theme/CodeFromRemote.module.css @@ -0,0 +1,3 @@ +.container { + margin-bottom: var(--ifm-leading) +} diff --git a/docs/src/theme/SelfServiceApiFlow.js b/docs/src/theme/SelfServiceApiFlow.js index 3fe537ed144..d3911dbbe2a 100644 --- a/docs/src/theme/SelfServiceApiFlow.js +++ b/docs/src/theme/SelfServiceApiFlow.js @@ -20,9 +20,9 @@ sequenceDiagram B-->>B: User fills out forms, clicks e.g. ${interactions} B->>K: REST POST to e.g. /self-service/${components}/methods/<${methods.join('|')}> K-->>K: Validates and processes payload - alt Form payload is valid valid + alt Form payload is valid K->>B: ${success} - else Login data invalid + else Form payload invalid K-->>K: Update and store flow (e.g. add form validation errors) K->>B: Respond with e.g. HTTP 400 Bad Request and updated flow as payload B-->>B: Render form and validation errors using e.g. Native iOS UI Elements diff --git a/docs/src/theme/SelfServiceBrowserFlow.js b/docs/src/theme/SelfServiceBrowserFlow.js index 310dc75cb4a..a1fbe5b774e 100644 --- a/docs/src/theme/SelfServiceBrowserFlow.js +++ b/docs/src/theme/SelfServiceBrowserFlow.js @@ -24,9 +24,9 @@ sequenceDiagram B->>K: Submits form K-->>K: Validates and processes form payloads - alt Form payload is valid valid + alt Form payload is valid K->>B: ${success} - else Login data invalid + else Form payload invalid K-->>K: Update and store flow (e.g. add form validation errors) K-->>B: HTTP 302 Found ?flow= B->>A: Opens diff --git a/docs/static/img/docs/quickstart-recover-i.png b/docs/static/img/docs/quickstart-recover-i.png deleted file mode 100644 index 9acb699768d..00000000000 Binary files a/docs/static/img/docs/quickstart-recover-i.png and /dev/null differ diff --git a/docs/static/img/docs/quickstart-recover-ii.png b/docs/static/img/docs/quickstart-recover-ii.png deleted file mode 100644 index e2738886eb0..00000000000 Binary files a/docs/static/img/docs/quickstart-recover-ii.png and /dev/null differ diff --git a/docs/static/img/docs/quickstart-recover-iv.png b/docs/static/img/docs/quickstart-recover-iv.png deleted file mode 100644 index 105c07a933a..00000000000 Binary files a/docs/static/img/docs/quickstart-recover-iv.png and /dev/null differ diff --git a/docs/static/img/docs/secureapp-login-ntrace.png b/docs/static/img/docs/secureapp-login-ntrace.png deleted file mode 100644 index 87038846335..00000000000 Binary files a/docs/static/img/docs/secureapp-login-ntrace.png and /dev/null differ diff --git a/docs/static/img/docs/secureapp-login.png b/docs/static/img/docs/secureapp-login.png deleted file mode 100644 index db12d027060..00000000000 Binary files a/docs/static/img/docs/secureapp-login.png and /dev/null differ diff --git a/docs/static/img/docs/secureapp-registration-ntrace.png b/docs/static/img/docs/secureapp-registration-ntrace.png deleted file mode 100644 index 9517fb35890..00000000000 Binary files a/docs/static/img/docs/secureapp-registration-ntrace.png and /dev/null differ diff --git a/docs/static/img/docs/secureapp-registration-pwpolicy.png b/docs/static/img/docs/secureapp-registration-pwpolicy.png deleted file mode 100644 index 770482b3fa6..00000000000 Binary files a/docs/static/img/docs/secureapp-registration-pwpolicy.png and /dev/null differ diff --git a/docs/static/img/docs/secureapp-registration.png b/docs/static/img/docs/secureapp-registration.png deleted file mode 100644 index 97e2f92d614..00000000000 Binary files a/docs/static/img/docs/secureapp-registration.png and /dev/null differ