password method is the most commonly used form of authentication, it
identifier (username, email, phone number, ...) and a
during registration and login.
Ory Kratos hashes the password after registration, password reset, and password change using:
- BCrypt (default).
Enabling this method is as easy as setting
in your Ory Kratos configuration.
You can configure the BCrypt hasher using the following options:
Due to the way BCrypt is implemented in Golang, passwords will be truncated after 72 characters before being hashed. This implies that all characters in the password after position 72 will be ignored!
Bcrypt algorithm can be configured only by the following
cost option (default
value is 12):
By default, Kratos uses BCrypt algorithm for password hashing. Use the following option to use the Argon2id algorithm:
To determine the ideal parameters, head over to the setup guide.
When a user signs up using this method, the Default Identity JSON Schema (set
identity.default_schema_url) is used:
If you don't know what that means, please read the Identity Data Model Chapter in the docs' concepts section.
For a complete reference, defaults, and description please check the Configuration Reference.
For a better understanding of security implications imposed by Argon2 Configuration, head over to Argon2 Security.
Before you start, you need to decide what data you want to collect from your users and why! It is hard to change this decision afterwards, so make sure you've taken everything into account!
When logging in, the user will use a login identifier and a password to sign up and in. The identifier can be
- a username - e.g. "john.doe" or "johndoe123" or "oryuser",
- an email address - e.g.
- a phone number - e.g.
All of these approaches have up- and downsides.
Using the email address as the login identifier is easy to remember, does not require additional fields (because the email address is already being collected), and is usually unique. It's usually unique because sometimes companies use a "shared" email account (e.g. firstname.lastname@example.org) to access services. In that case, multiple real identities are using the same email identifier to log in.
The email address however represents a unique identifier and personally
identifiable information (PII). An attacker could for example check if an email
email@example.com) is registered at a site (e.g. an adult
website) and use that information for blackmail (see
Account Enumeration Attacks).
The same considerations apply to using a phone number as the primary registration & login identifier.
Using a free text username reduces the privacy risk because it is much harder to make a connection between the username and a real world identity. It's still possible in cases where users choose a username such as "john.doe.from.newyork.1970", but finding the right username identifier is still difficult and there is plausible deniability because anyone could use that username.
A free text username however requires capturing additional fields (e.g. an email
address for password resets / account recovery) and is hard to remember. It is
often very difficult to find unique usernames as people tend to use a
combination of their names and initials (e.g.
john.doe) which has a high
chance of collision. Therefore, one ends up with usernames such as
It is important to understand that Ory Kratos lowercases all
identifiers and therefore E-Mail addresses. Characters
. which have
special meaning for some E-Mail Providers (e.g. GMail) are not normalized:
userNAMEis equal to
foo@BaR.comis equal to
firstname.lastname@example.org NOT equal to
email@example.com NOT equal to
You need to decide which route you want to take.
When processing an identity and its traits, the method will use JSON Schema to extract one or more identifiers.
To use the email address as the login identifier, define the following Identity JSON Schema:
You can allow users to sign up with multiple E-Mail Addresses and use any of those for log in:
To use a username as the login identifier, define the following Identity JSON Schema:
You may also mix usernames and passwords:
This will be addressed in a future release and is tracked as kratos#137.
Assuming your Identity JSON Schema is as follows:
And an identity registers with the following JSON payload (more on registration in Selfservice Registration):
password method would generate a credentials block as follows:
Because credential identifiers need to be unique, no other identity can be
created that has
firstname.lastname@example.org as their