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.
The following examples use YAML for improved readability. However, the API
payload is usually in JSON format. An
identity has the following properties:
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
email@example.com 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!