Skip to content

Commit

Permalink
styles: format code
Browse files Browse the repository at this point in the history
  • Loading branch information
aeneasr committed Sep 13, 2020
1 parent af40d93 commit c3b5ff5
Show file tree
Hide file tree
Showing 16 changed files with 586 additions and 350 deletions.
10 changes: 5 additions & 5 deletions docs/docs/concepts/browser-redirect-flow-completion.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -102,8 +102,8 @@ selfservice:
Post-settings redirection **does not use** the `urls.default_redirect_to`
configuration key. Instead the redirect ends at the same Settings UI with the
same Settings Request ID and key `state` set to `success`. If the
listed keys are set, the redirection will end up at the specified values:
same Settings Request ID and key `state` set to `success`. If the listed keys
are set, the redirection will end up at the specified values:

```yaml file="path/to/my/kratos.config.yml"
selfservice:
Expand All @@ -119,9 +119,9 @@ selfservice:
### Post-Verification Redirection

Post-verification redirection **does not use** the `urls.default_redirect_to`
configuration key. Instead the redirect ends at the same Verification UI with the
same Verification Request ID and key `state` set to `passed_challenge`. If the
listed keys are set, the redirection will end up at the specified values:
configuration key. Instead the redirect ends at the same Verification UI with
the same Verification Request ID and key `state` set to `passed_challenge`. If
the listed keys are set, the redirection will end up at the specified values:

```yaml file="path/to/my/kratos.config.yml"
selfservice:
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/concepts/credentials/username-email-password.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 [Password Hashing
Competition (PHC)](https:/P-H-C/phc-winner-argon2).
winner of the
[Password Hashing Competition (PHC)](https:/P-H-C/phc-winner-argon2).

## Configuration

Expand Down
3 changes: 2 additions & 1 deletion docs/docs/concepts/security.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,8 @@ There are three common ways an attacker can figure out if a user is signed up at
a service:

- During login: "No user with this email address was found"
- During registration or email update: "A user with this email address exists already"
- During registration or email update: "A user with this email address exists
already"
- During password reset: "No user with this email address was found"

To mitigate this attack, the following methods need to be deployed:
Expand Down
218 changes: 157 additions & 61 deletions docs/docs/milestones.md

Large diffs are not rendered by default.

45 changes: 24 additions & 21 deletions docs/docs/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,9 @@ needs users. Therefore, we need:

and of course:

- A dashboard that shows `Hello {{ traits.name.first }} {{ traits.name.last }}}!` 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

Expand All @@ -78,11 +80,12 @@ and more so you don't have to.

:::

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
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
Expand Down Expand Up @@ -164,13 +167,14 @@ This demo makes use of several services:

1. [ORY Kratos](https:/ory/kratos)
- Public ("Browser") API (port 4433)
- Admin API (port 4434) - This is only made public so we can test via the CLI.
- Admin API (port 4434) - This is only made public so we can test via the
CLI.
2. [SecureApp](http:/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:/mailslurper)
- Public (port 4436) - a development SMTP server which ORY Kratos will use to
send emails.
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
Expand Down Expand Up @@ -218,23 +222,22 @@ Looking at the network stack, you can see two redirects happening:

Here's a play-by-play of what happened:

1. SecureApp used the ORY Kratos JavaScript language client to
guard the `/dashboard` route. The ORY Kratos client checked the cookies from the request and saw you were not logged in.
1. SecureApp used the ORY Kratos JavaScript language client to 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 `<flow_id>` in order to log you in. It looked
for this ID in the URL as a query parameter but
couldn't find it.
for this ID in the URL as a query parameter but couldn't find it.
3. `/auth/login` redirected you to
`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?flow=<flow_id>`.
`csrf_token`, and redirected the browser to `/auth/login?flow=<flow_id>`.
5. SecureApp handled the `/auth/login` route, found the `<flow_id>` in the URL
query parameter, and used it to make an HTTP request to
`http://kratos:4434/self-service/login/flows?id=<flow_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.
`http://kratos:4434/self-service/login/flows?id=<flow_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
form.

Expand Down Expand Up @@ -386,8 +389,8 @@ again. Exciting!

### Understanding How Login and Registration Works

Head over to the [Self-Service Flows Chapter](self-service.mdx) for
an in-depth explanation of how each individual flow works.
Head over to the [Self-Service Flows Chapter](self-service.mdx) for an in-depth
explanation of how each individual flow works.

### Email Verification

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,5 @@ id: 2fa-mfa-multi-factor-authentication
title: MFA / 2FA
---

This feature is a work in progress and is being tracked in [issue #26](https:/ory/kratos/issues/26).
This feature is a work in progress and is being tracked in
[issue #26](https:/ory/kratos/issues/26).
86 changes: 52 additions & 34 deletions docs/docs/self-service/flows/account-recovery.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,15 @@ import SelfServiceBrowserFlow from '@theme/SelfServiceBrowserFlow'
import SelfServiceApiFlow from '@theme/SelfServiceApiFlow'

import CodeTabs from '@theme/Code/CodeTabs'
import { initBrowserFlow, initApiFlow, getFlow, getFlowMethodLinkWithErrors, getFlowMethodLinkSuccess, getFlowMethodLinkInvalidChallenge, getFlowMethodLinkChallengeDone } from './code/recovery'
import {
initBrowserFlow,
initApiFlow,
getFlow,
getFlowMethodLinkWithErrors,
getFlowMethodLinkSuccess,
getFlowMethodLinkInvalidChallenge,
getFlowMethodLinkChallengeDone
} from './code/recovery'
import RenderFlow from '@theme/Code/RenderFlow'

:::information
Expand Down Expand Up @@ -72,7 +80,7 @@ selfservice:
Currently, one recovery method is supported:
- The `link` method performs account recovery (also known as password reset) by
sending an email containing a recovery link to the user.
sending an email containing a recovery link to the user.

### Recovery `link` Method

Expand Down Expand Up @@ -118,8 +126,8 @@ This prevents account enumeration attacks as explained in this
[brilliant blog post by Troy Hunt](https://www.troyhunt.com/website-enumeration-insanity-how-our-personal-data-is-leaked/).

The emails are using templates that can be customised as explained in
[Customizing E-Mail Templates](../../concepts/email-sms#templates). The
template IDs are:
[Customizing E-Mail Templates](../../concepts/email-sms#templates). The template
IDs are:

- Unknown email address: `recovery_invalid`
- Known email address: `recovery_valid`
Expand All @@ -135,7 +143,8 @@ selfservice:
privileged_session_max_age: 15m
```

To specify that an identity's trait is a recovery email, use the following Identity JSON Schema:
To specify that an identity's trait is a recovery email, use the following
Identity JSON Schema:

```diff
{
Expand Down Expand Up @@ -170,8 +179,9 @@ To specify that an identity's trait is a recovery email, use the following Ident

## Initialize Recovery Flow

The first step is to initialize the Recovery Flow. This sets up Anti-CSRF tokens and more.
Each recovery flow has a `state` parameter which follows the state machine:
The first step is to initialize the Recovery Flow. This sets up Anti-CSRF tokens
and more. Each recovery flow has a `state` parameter which follows the state
machine:

<Mermaid
chart={`
Expand All @@ -197,21 +207,23 @@ where

### Recovery for Browser Clients

The Recovery Flow for browser clients relies on HTTP redirects between ORY Kratos, your Recovery UI, and the end-user's
browser:
The Recovery Flow for browser clients relies on HTTP redirects between ORY
Kratos, your Recovery UI, and the end-user's browser:

<SelfServiceBrowserFlow
flows={['recovery']}
success="Set session cookie and initialize Settings Flow"
interactions={['"Recover account"']}
/>

To initialize the Recovery Flow, point the Browser to the initialization endpoint:
To initialize the Recovery Flow, point the Browser to the initialization
endpoint:

<CodeTabs items={initBrowserFlow} />

The server responds with a HTTP 302 redirect to the Recovery UI, appending the `?flow=<flow-id>` query
parameter (see the curl example) to the URL configured here:
The server responds with a HTTP 302 redirect to the Recovery UI, appending the
`?flow=<flow-id>` query parameter (see the curl example) to the URL configured
here:

```yaml title="path/to/config/kratos.yml"
selfservice:
Expand All @@ -225,36 +237,43 @@ selfservice:

<ApiWarning />

The Recovery Flow for API clients does not use HTTP Redirects and can be summarized as follows:
The Recovery Flow for API clients does not use HTTP Redirects and can be
summarized as follows:

<SelfServiceApiFlow
flows={['recovery']}
success="Return session token"
interactions={['"Recover account"']}
/>

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))
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:

<CodeTabs items={initApiFlow} />

## Recovery Flow Payloads

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:
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:

<CodeTabs items={getFlow} />

### 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.
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:
When the `link` method is enabled, it will be part of the `methods` payload in
the Recovery Flow:

```shell script
$ curl -H "Accept: application/json" -s \
Expand All @@ -281,18 +300,17 @@ $ curl -H "Accept: application/json" -s \

## Recovery Flow Form Rendering

The Recovery User Interface is a route (page / site) in your
application (server, native app, single page app) that should render
a recovery form.
The Recovery User Interface is a route (page / site) in your application
(server, native app, single page app) that should render a recovery form.

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.

You will use the Recovery Flow JSON response to render the recovery form UI,
which could looks as follows depending on your
programming language and web framework:
which could looks as follows depending on your programming language and web
framework:

<RenderFlow flow="recovery" />

Expand All @@ -305,13 +323,14 @@ The form payloads are then submitted to ORY Kratos which follows up with:

### Recovery Link via Email

To send the recovery email, the end-user fills out the form. There might be validation
errors such as a malformed email:
To send the recovery email, the end-user fills out the form. There might be
validation errors such as a malformed email:

<CodeTabs items={getFlowMethodLinkWithErrors} />

When validation errors happen, browser clients receive a HTTP 302 Found redirect to the
Recovery Flow UI, containing the Recovery Flow ID which includes the error payloads.
When validation errors happen, browser clients receive a HTTP 302 Found redirect
to the Recovery Flow UI, containing the Recovery Flow ID which includes the
error payloads.

For API Clients, the server typically responds with HTTP 400 Bad Request and the
Recovery Flow in the response payload as JSON.
Expand All @@ -324,9 +343,8 @@ On successful submission, an email will be sent to the provided address:

## Unsuccessful Recovery

If the recovery challenge (e.g. the link in the recovery email)
is invalid or expired, the user will be HTTP 302 redirected to the
Recovery UI.
If the recovery challenge (e.g. the link in the recovery email) is invalid or
expired, the user will be HTTP 302 redirected to the Recovery UI.

:::note

Expand All @@ -344,8 +362,8 @@ Please keep in mind that this part of the flow always involves a Browser!

## Successful Recovery

Completing account recovery always results in a HTTP 302 redirect
with a ORY Kratos Login Session Cookie to the Settings UI with a
Settings Flow prompting the user to update their password or credentials:
Completing account recovery always results in a HTTP 302 redirect with a ORY
Kratos Login Session Cookie to the Settings UI with a Settings Flow prompting
the user to update their password or credentials:

<CodeTabs items={getFlowMethodLinkChallengeDone} />
4 changes: 2 additions & 2 deletions docs/docs/self-service/flows/code/login/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -77,13 +77,13 @@ export const getFlowMethodPasswordWithErrors = {
label: 'Wrong Credentials',
language: 'shell',
code: require('raw-loader!./samples/password.wrong.txt').default
},
}
}

export const getFlowMethodOidcWithErrors = {
missing: {
label: 'Missing ID Token',
language: 'shell',
code: require('raw-loader!./samples/oidc.missing.txt').default
},
}
}
2 changes: 1 addition & 1 deletion docs/docs/self-service/flows/code/recovery/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ export const initApiFlow = {
label: 'Go',
language: 'go',
code: require('raw-loader!./samples/api/init.go.txt').default
},
}
}

export const getFlowMethodLinkWithErrors = {
Expand Down
Loading

0 comments on commit c3b5ff5

Please sign in to comment.