Skip to content

Commit

Permalink
chore: format docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@zepatrik @aeneasr
zepatrik authored and aeneasr committed Aug 5, 2020
1 parent 7be1182 commit 9229c30
Show file tree
Hide file tree
Showing 13 changed files with 181 additions and 124 deletions.
1 change: 1 addition & 0 deletions Makefile
View file
Expand Up @@ -98,6 +98,7 @@ quickstart-dev:
.PHONY: format
format: .bin/goreturns
goreturns -w -local github.com/ory $$(listx .)
cd docs; npm run format
npm run format

# Runs tests in short mode, without database adapters
Expand Down
48 changes: 29 additions & 19 deletions docs/docs/admin/managing-users-identities.mdx
View file
Expand Up @@ -6,29 +6,35 @@ title: Managing Users and Identities
import Tabs from '@theme/Tabs'
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 guide.
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
guide.

## Creating an Identity

There are three principal flows supported for creating identities as an administrator:
There are three principal flows supported for creating identities as an
administrator:

1. Inviting users - e.g. inviting a new employee to your organization IT.
2. Importing existing users - e.g. when migrating from another system to ORY Kratos.
2. Importing existing users - e.g. when migrating from another system to ORY
Kratos.
3. Creating machine users - e.g. creating Service Accounts.

:::note

Similar to other guides, we assume that ORY Kratos runs on 127.0.0.1:4433 (public endpoint) and
127.0.0.1:4434 (admin endpoint) in this guide, which is the default when running the quickstart.
Similar to other guides, we assume that ORY Kratos runs on 127.0.0.1:4433
(public endpoint) and 127.0.0.1:4434 (admin endpoint) in this guide, which is
the default when running the quickstart.

:::

### Invite a User

The goal of this flow is to create an identity and provide the end-user with a way
of signing into the identity (account) and setting their password (or any other type of credential)
for future logins. To achieve this, first create the identity and set its traits and schema:
The goal of this flow is to create an identity and provide the end-user with a
way of signing into the identity (account) and setting their password (or any
other type of credential) for future logins. To achieve this, first create the
identity and set its traits and schema:

```shell script
$ curl --request POST -sL \
Expand All @@ -51,10 +57,12 @@ $ curl --request POST -sL \
}
```

Keep in mind that you can change the `schema_id` to reflect the schema you want to use for this user. Similarly,
the trait key/values depend on your schema as well. The command shown does not create a password for the identity
or any other type of credential. Instead, we will use another REST call to create a recovery link (here "invite link" is
probably more appropriate, but the flow uses an account recovery link).
Keep in mind that you can change the `schema_id` to reflect the schema you want
to use for this user. Similarly, the trait key/values depend on your schema as
well. The command shown does not create a password for the identity or any other
type of credential. Instead, we will use another REST call to create a recovery
link (here "invite link" is probably more appropriate, but the flow uses an
account recovery link).

To create the account recovery link, use:

Expand Down Expand Up @@ -113,9 +121,10 @@ func main() {
}
```

The response contains a `recovery_link` value which is the link the user should use to set up his or her credentials
(e.g. connect to a Social Sign In Provider, set up a password, ...). The user has only a limited amount of time to do
so - the amount of time is specified in the ORY Kratos config:
The response contains a `recovery_link` value which is the link the user should
use to set up his or her credentials (e.g. connect to a Social Sign In Provider,
set up a password, ...). The user has only a limited amount of time to do so -
the amount of time is specified in the ORY Kratos config:

```yaml title="path/to/kratos/config.yml"
selfservice:
Expand All @@ -124,10 +133,11 @@ selfservice:
privileged_session_max_age: 30m
```

If the user fails to set up his / her credentials in time, another recovery link needs to be issued and the user
needs to re-do the flow.
If the user fails to set up his / her credentials in time, another recovery link
needs to be issued and the user needs to re-do the flow.

It is currently not possible to send the recovery link directly to a user's email, this feature is tracked as
It is currently not possible to send the recovery link directly to a user's
email, this feature is tracked as
[#595](https://github.com/ory/kratos/issues/595).

</TabItem>
Expand Down
27 changes: 11 additions & 16 deletions docs/docs/concepts/identity-data-model.md
View file
Expand Up @@ -11,11 +11,10 @@ programmatic identity such as an IoT device, application, or some other type of
:::info

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

The following examples use YAML for improved readability. However, the API
payload is usually in JSON format. An `identity` has the following properties:
Expand Down Expand Up @@ -70,20 +69,16 @@ Identities are

- `created` - via API or self-service registration);
- `updated` - via API or self-serfice settings, account recovery, ...;
- `disabled` - not yet implemented, see [#598](https://github.com/ory/kratos/issues/598);
- `deleted` - via API or with a self-service flow (not yet implemented see [#596](https://github.com/ory/kratos/issues/596)).
- `disabled` - not yet implemented, see
[#598](https://github.com/ory/kratos/issues/598);
- `deleted` - via API or with a self-service flow (not yet implemented see
[#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):
The identity state is therefore `active` or `disabled` (not yet implemented see
[#598](https://github.com/ory/kratos/issues/598):

<Mermaid
chart={`
stateDiagram-v2
[*] --> Active: create
Active --> Active: update
Active --> Disabled: disable
Disabled --> [*]: delete
Disabled --> Active: enable
`}
chart={`stateDiagram-v2 [*] --> Active: create Active --> Active: update Active --> Disabled: disable Disabled --> [*]: delete Disabled --> Active: enable`}
/>

## Identity Traits and JSON Schemas
Expand Down
61 changes: 33 additions & 28 deletions docs/docs/concepts/index.md
View file
Expand Up @@ -65,7 +65,8 @@ feature sets that include:

- theming to customize the user experience, and to constrain the anticipated
theming use case;
- HTML Template Engines specific to the language used, such as Java Server Pages or
- HTML Template Engines specific to the language used, such as Java Server Pages
or
[Apache FreeMarker™](https://www.keycloak.org/docs/latest/server_development/#html-templates);
- plugin loaders and APIs to add custom logic or even custom API endpoints,
specific to the language used by the project; and
Expand All @@ -92,8 +93,8 @@ great, and it covers a lot of ground, but it also comes with drawbacks:
data, sometimes even as plain key/value pairs;
- Complex build pipelines when using modern frontend frameworks like React or
Angular in the HTML Rendering engine;
- The user model stays the same, even when differentiating between customers
and employees in your system; and
- The user model stays the same, even when differentiating between customers and
employees in your system; and
- API consumption is usually an after-thought because most flows are built
around the user doing something in the browser. All of the above leads to
added complexity in application development and deployment due to session
Expand All @@ -106,7 +107,8 @@ In today's market, with many proprietary SAAS companies offering Identity as a
Service, it seems easy to make sign-on cumbersome for both developers and users.
Even with delegated third party login processes such as "Login with Google,"
where OAuth2 and OpenID Connect are often the primary protocols, the challenge
is making a secure and simple login without any extra overhead, for instance, with Oauth2 and OpenID.
is making a secure and simple login without any extra overhead, for instance,
with Oauth2 and OpenID.

ORY's focus is on simplicity, user experience, and above all, using the right
tools and technologies for the target application. Feedback from ORY's user
Expand All @@ -118,12 +120,13 @@ implementation scenario.

The main point is that OAuth2 and OpenID Connect protocols solve identity
federation. For instance, when the target application authenticates an identity
or authorizes access by using a system outside of the
application's control, for example within an enterprise, company domain or another third party service. These protocols don't solve processes like updating a
user's profile, adding a secondary recovery email, solving 2FA, storing and
managing sessions, or solving global logout. These processes are the developer's
responsibility and while the OAuth2 and OpenID Connect protocols offer a way
to securely solve identity federation over the browser, they do not solve:
or authorizes access by using a system outside of the application's control, for
example within an enterprise, company domain or another third party service.
These protocols don't solve processes like updating a user's profile, adding a
secondary recovery email, solving 2FA, storing and managing sessions, or solving
global logout. These processes are the developer's responsibility and while the
OAuth2 and OpenID Connect protocols offer a way to securely solve identity
federation over the browser, they do not solve:

- Storage and management of all these tokens. These would often end up in the
localStore making them vulnerable to XSS attacks. Or in a cookie issued by an
Expand All @@ -147,13 +150,14 @@ infrastructure, ORY Kratos embraced a polyglot design. In other words ORY Kratos
provides Software Development Kits (SDK) and libraries for the main programming
languages.

As software development teams grow, product requirements change. During a development lifecycle different parts, for instance humans, servers, and
code, need to scale to size. Over time, the original product splits into
smaller, more manageable chunks. The libraries chosen at the outset will need to
run on the newest version of the programming language. Sometimes even the
programming language or implementation framework are subject to change as a
whole. Still, the identity system is often so interlinked with all of the source
code, middlewares, annotations, shared state, etc., that it becomes an absolute
As software development teams grow, product requirements change. During a
development lifecycle different parts, for instance humans, servers, and code,
need to scale to size. Over time, the original product splits into smaller, more
manageable chunks. The libraries chosen at the outset will need to run on the
newest version of the programming language. Sometimes even the programming
language or implementation framework are subject to change as a whole. Still,
the identity system is often so interlinked with all of the source code,
middlewares, annotations, shared state, etc., that it becomes an absolute
nightmare to decouple.

### Roll your own
Expand All @@ -177,17 +181,18 @@ considerations and challenges in ORY's efforts:
friendliness;
- To prevent security threats for example
[account enumeration attacks](<https://wiki.owasp.org/index.php/Testing_for_User_Enumeration_and_Guessable_User_Account_(OWASP-AT-002)>);
- To implement two factor authentication (2FA). When the user
loses access to a registered and approved device, there should be a
fallback phone number for SMS or offline security codes;
- To implement two factor authentication (2FA). When the user loses access to a
registered and approved device, there should be a fallback phone number for
SMS or offline security codes;
- To understand and use all of the important rules such as activation, welcome,
etc., around sending emails that don't alert spam filters;
- To support a broad ecosystem of products and services. For example in the event
that a target application needs to notify Stripe when a new customer signs up.
- To support a broad ecosystem of products and services. For example in the
event that a target application needs to notify Stripe when a new customer
signs up.

The list above is purposely kept short. There are very many things to consider
when building Kratos in concert with the other products ORY Keto, ORY Hydra,
and ORY Oathkeeper. The list is really, really long.
when building Kratos in concert with the other products ORY Keto, ORY Hydra, and
ORY Oathkeeper. The list is really, really long.

## ORY Kratos

Expand Down Expand Up @@ -222,8 +227,8 @@ ORY's
document, explains the architectural beliefs and framework behind the ORY
Products in particular:

- Small runtime footprint with an about five (5) MB binary running on all operating
systems without any system, library, or VM dependencies;
- Small runtime footprint with an about five (5) MB binary running on all
operating systems without any system, library, or VM dependencies;
- Fully virtualised in a fifteen (15) MB Docker image;
- Easy to manage with exactly one binary for the server and the cli;
- Run-time orchestration using the latest Kubernetes providing fast and easy to
Expand Down Expand Up @@ -268,5 +273,5 @@ Open Source provides a base solution for many use cases. For example, ORY Kratos
integrates with ORY Oathkeeper, a Reverse Proxy solution. Defining Access Rules
is as easy as writing a few lines of JSON / JSON5 / YAML!

Please consult the [Quickstart documentation](../quickstart), for
further information.
Please consult the [Quickstart documentation](../quickstart), for further
information.
17 changes: 9 additions & 8 deletions docs/docs/concepts/terminology.mdx
View file
Expand Up @@ -3,24 +3,25 @@ id: terminology
title: Terminology
---

The purpose of this document is to define terminology used through this documentation.
The purpose of this document is to define terminology used through this
documentation.

## End-User

The person who actually uses a particular product that uses ORY Kratos.

## Identity

the "who" of a software system. It can be a customer, employee, user, contractor, or even a
programmatic identity such as an IoT device, application, or some other type of
"robot."
the "who" of a software system. It can be a customer, employee, user,
contractor, or even a programmatic identity such as an IoT device, application,
or some other type of "robot."

Common aliases are "user", "user account", "account", "subject".

## Self-Service

Interfaces and flows allowing customers to produce services
independent of involvement of direct service employee.
Interfaces and flows allowing customers to produce services independent of
involvement of direct service employee.

You perform self-service registration when signing up for a new Goole account, because no one (e.g. support)
else is involved in the process.
You perform self-service registration when signing up for a new Goole account,
because no one (e.g. support) else is involved in the process.
38 changes: 23 additions & 15 deletions docs/docs/guides/configuring-cookies.mdx
View file
Expand Up @@ -5,39 +5,46 @@ title: Configuring Cookies

When working with cookies, keep the following in mind:

1. HTTP Cookies **are not port specific**. If a cookie is set on `https://mydomain.com:1234` it is also valid for
`https://mydomain.com:4321` and `https://mydomain.com`.
1. HTTP Cookies **are not port specific**. If a cookie is set on
`https://mydomain.com:1234` it is also valid for `https://mydomain.com:4321`
and `https://mydomain.com`.
2. Unless `--dev` is set, ORY Kratos' cookies are only sent over HTTPS.
3. Cookies in ORY Kratos are always `httpOnly`.
4. It is possible to set a cookie for `mydomain.com` when the original request was made to `subdomain.mydomain.com`.
It is however not possible to set a cookie for `anotherdomain.com` when the original request was made to `mydomain.com`.
See also [this answer] on [SackOverflow](https://stackoverflow.com/questions/18492576/share-cookie-between-subdomain-and-domain).
4. It is possible to set a cookie for `mydomain.com` when the original request
was made to `subdomain.mydomain.com`. It is however not possible to set a
cookie for `anotherdomain.com` when the original request was made to
`mydomain.com`. See also [this answer] on
[SackOverflow](https://stackoverflow.com/questions/18492576/share-cookie-between-subdomain-and-domain).

:::note

ORY Kratos uses pass-by-value cookies whose values are encrypted using the `secrets.default` / `secrets.cookie` secrets.
If these secrets are changed without doing proper [secret / key rotation](secret-key-rotation), all cookies will be invalid
which will cause users to be signed out, and other side effects.
ORY Kratos uses pass-by-value cookies whose values are encrypted using the
`secrets.default` / `secrets.cookie` secrets. If these secrets are changed
without doing proper [secret / key rotation](secret-key-rotation), all cookies
will be invalid which will cause users to be signed out, and other side effects.

:::

## Session Cookies

CloudRun, Heroku, and other "serverless" solutions commonly expose services directly to the public,
and do not allow for fronting by a gateway or reverse proxy. In those cases, your application architecture
may separate services by subdomain (e.g. `service1.myproduct.com`, `service2.myproduct.com`,
CloudRun, Heroku, and other "serverless" solutions commonly expose services
directly to the public, and do not allow for fronting by a gateway or reverse
proxy. In those cases, your application architecture may separate services by
subdomain (e.g. `service1.myproduct.com`, `service2.myproduct.com`,
`service3.myproduct.com`, ...).

If that is the case you can change the session [cookie domain](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies)
and path using the following configuration keys in your ORY Kratos configuration:
If that is the case you can change the session
[cookie domain](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and
path using the following configuration keys in your ORY Kratos configuration:

```yaml title="path/to/kratos/config.yml
session:
cookie:
domain: myproduct.com
```

It is also possible to restrict the [cookie path](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies):
It is also possible to restrict the
[cookie path](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies):

:::note

Expand All @@ -51,7 +58,8 @@ session:
path: /some/sub-directory
```

You can also modify the new [HTTP Cookie SameSite Attribute](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite)
You can also modify the new
[HTTP Cookie SameSite Attribute](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite)
using:

```yaml title="path/to/kratos/config.yml
Expand Down

0 comments on commit 9229c30

Please sign in to comment.