An identity ("user", "user account", "account", "subject") is 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."
In ORY Kratos' terminology we call all of them "identities", and it is always
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:
created- via API or self-service registration);
updated- via API or self-serfice settings, account recovery, ...;
disabled- not yet implemented, see #598;
deleted- via API or with a self-service flow (not yet implemented see #596).
The identity state is therefore
disabled (not yet implemented see
Identity Traits and JSON Schemas
Traits are data associated with an identity. You have to define its schema according to your application's needs. They are also supposed to be modified by the identity itself e.g. as part of the registration or profile update process as well as anyone having access to ORY Krato's Admin API.
ORY Kratos uses JSON Schema to validate Identity Traits.
ORY Kratos defines JSON Schema extension "Vocabulary" that allows you to tell ORY Kratos that a specific trait adds some specific meaning to the standard JSON Schema (more on that later).
Each identity can, theoretically, have a different JSON Schema. This is useful in the following situations:
- there is more than one type of identity in the system for instance customers, support or staff;
- the system includes both users and robots sometimes also known as named service accounts;
- the system needs to ingest another company's identity model, and
- the system's identity model changes or grows over time and requires versioning.
The following example illustrates a usage scenario with three types of identities: Regular customers, grandfather accounts, and Service Accounts (e.g. Microsoft provides Service Accounts). There would be one JSON Schema per type of identity:
- Grandfather Accounts:
- Service Accounts:
ORY Kratos expects the JSON Schemas in its configuration file:
ORY Kratos validates the Identity Traits against the corresponding schema on all writing operations (create / update). The employed business logic must be able to distinguish these three types of identities. You might use a switch statement like in the following example:
JSON Schema Vocabulary Extensions
Because ORY Kratos does not know that a particular field has a system-relevant meaning you have to specify these in the schema. This includes for example:
- The email address for recovering a lost password
- The identifier for logging in with a password e.g. username or email
- The phone number for enabling SMS 2FA
ORY Kratos' JSON Schema Vocabulary Extension can be used within a property:
An overview of available configuration options follows in the next sections.
Identifier for Username and Password Flows
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:
Looking at the traits from above
and using a JSON Schema that uses the
In this example, ORY Kratos understands that traits✉️
the identity's identifier. The system expects
firstname.lastname@example.org plus a password to
Username and Password Credentials contains more information and examples.
There are currently no other extensions supported for Identity Traits. Further fields will be added in future releases!