Version: v0.5

Managing Users and Identities

This document walks you through the administrative identity management in ORY Kratos. You should already be familiar with the Identity Data Model before reading this guide.

Creating an Identity#

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

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:

$ curl --request POST -sL \
--header "Content-Type: application/json" \
--request POST \
--data '{
"schema_id": "default",
"traits": {
"email": "foo@ory.sh"
}
}' \
http://127.0.0.1:4434/identities
{
"id": "954f7f59-16a5-4152-8ce7-ad7c73bb124a",
"schema_id": "default",
"traits":{
"email": "foo@ory.sh"
}
}

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:

$ curl --request POST -sL \
--header "Content-Type: application/json" \
--request POST \
--data '{
"expires_in": "12h",
"identity_id": "954f7f59-16a5-4152-8ce7-ad7c73bb124a"
}' \
http://127.0.0.1:4434/recovery/link
{
"expires_at": "2020-07-27T10:47:45.806Z",
"recovery_link": "http://127.0.0.1:4433/self-service/browser/flows/recovery/link?request=8b6fd3e4-1de2-49bf-aa88-1a26634bf062\u0026token=b1tGmHf64cYDeHB9wKiuCF1FfycMJEyf"
}

Import a User Identity#

Importing a User Identity is possible using the Kratos CLI but still contains some limitations. More information can be found in the identities import command documentation.

Creating a Machine Identity#

This feature is not implemented yet.

Enable recovery flows#

To enable recovery flows, make the following adjustments to your ORY Kratos configuration:

path/to/config/kratos.yml
selfservice:
methods:
link:
enabled: true
flows:
recovery:
enabled: true

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

{
"$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
}
},
+ "recovery": {
+ "via": "email"
+ }
}
}
}
"additionalProperties": false
}
}
}

For more detailed information and general guidelines on these flows, take a look at the Account Recovery and Password Reset section.

Last updated on by TannerGabriel