Managing Users and Identities

This document walks you through the administrative identity management in Ory Kratos. You should already be familiar with the Identity Schema 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). It's possible to generate a link for an account without a recovery address via the admin API, but if the recovery link expires the user won't be able to reinitiate the flow by himself as long as the recovery address has been added.

To create the account recovery link, use:

curl

$ 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": "https://playground.projects.oryapis.com/api/kratos/public/self-service/browser/flows/recovery/link?request=8b6fd3e4-1de2-49bf-aa88-1a26634bf062\u0026token=b1tGmHf64cYDeHB9wKiuCF1FfycMJEyf"
}

GoLang

package main

import (
    "fmt"
    "github.com/ory/kratos-client-go/client"
    "github.com/ory/kratos-client-go/client/admin"
    "github.com/ory/kratos-client-go/models"
)

func main() {
    c := client.New(nil, &client.TransportConfig{
        Host: "127.0.0.1:4434",
        BasePath: "/",
        Schemes: []string{"http"},
    })

    res, err := c.Admin.CreateRecoveryLink(admin.NewCreateRecoveryLinkParams().WithBody(admin.CreateRecoveryLinkBody{
        IdentityID: models.UUID("the-uuid"),
    }))
    if err != nil {
        // ...
    }

    fmt.Printf("Use link: %s", *res.Payload.RecoveryLink)
}

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:

path/to/kratos/config.yml

selfservice:
  flows:
    settings:
      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.

It is currently not possible to send the recovery link directly to a user's email, this feature is tracked as #595.

Import a User Identity

This feature is not implemented yet.

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

      config:
        # If the link should point to a domain (and path) that differs from the configured public base URL,
        # set this value to the base URL you want:
        base_url: https://my-example-domain.com

  flows:
    recovery:
      enabled: true

To specify that an identity's trait is a recovery email, use the following Identity 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.