Skip to main content

Overview

Each identity has one or more credentials associated with it:

credentials:
  password:
    id: password
    identifiers:
      - john.doe@acme.com
      - johnd@ory.sh
    config:
      hashed_password: ...
  oidc:
    id: oidc
    identifiers:
      - google:j8kf7a3...
      - facebook:83475891...
    config:
      - provider: google
        identifier: j8kf7a3
      - provider: facebook
        identifier: 83475891

Ory Kratos supports several credential types:

  • password: The most common identifier (username, email, ...) + password credential.
  • oidc: The "Log in with Google/Facebook/GitHub/..." credential.
  • Other credentials - support other credential types (X509 Certificates, Biometrics, ...) at will be added a later stage.

Each credential - regardless of its type - has one or more identifiers attached to it. Each identifier is universally unique. Assuming we had one identity with credentials

credentials:
  password:
    id: password
    identifiers:
      - john.doe@acme.com

and tried to create (or update) another identity with the same identifier (john.doe@acme.com), the system would reject the request with a 409 Conflict state.

While credentials must be unique per type, there can be duplicates amongst multiple types:

# This is ok:
credentials:
  password:
    id: password
    identifiers:
      - john.doe@acme.com
  oidc:
    id: oidc
    identifiers:
      - john.doe@acme.com

The same would apply if those were two separate identities:

# Identity 1
credentials:
  password:
    id: password
    identifiers:
      - john.doe@acme.com
---
# Identity 2
credentials:
  oidc:
    id: oidc
    identifiers:
      - john.doe@acme.com

Authenticator Assurance Level (AAL) / Multi-Factor Authentication (MFA / 2FA)​

A detailed explanation of AAL can be found in the NIST Digital Identity Guidelines Section 4:

The strength of an authentication transaction is characterized by an ordinal measurement known as the AAL. Stronger authentication (a higher AAL) requires malicious actors to have better capabilities and expend greater resources in order to successfully subvert the authentication process. Authentication at higher AALs can effectively reduce the risk of attacks.

If an Ory Kratos Session meets AAL2, then it also meets AAL1. If it meets AAL3, it also meets AAL2 and AAL1.

Authenticator Assurance Level 1 (AAL1)​

AAL1 provides some assurance that the claimant controls an authenticator bound to the subscriber’s account. AAL1 requirements are met if the identity authenticates with

  1. an identifier and password.
  2. an out-of-band one time password (such as sending a login code to your email / phone).
  3. an OpenID Connect ID token.

It's recommended to reauthenticate the session every 30 days. You can configure this by setting the session age to 30 days.

This option is not configurable.
You can configure the session lifespan in the configuration:

```yaml title="path/to/kratos/config.yml
session:
  lifespan: 720h # 30 days
```

Authenticator Assurance Level 2 (AAL2)​

AAL2 can be achieved by combining two single-factor authenticators. AAL2 is met if the Ory Kratos Session already meets AAL1 and

  1. a TOTP (Google Authenticator) challenge was completed.

It's recommended to reauthenticate the session every 12 hours or after every 30 minutes of inactivity:

At AAL2, authentication of the subscriber SHALL be repeated at least once per 12 hours during an extended usage session, regardless of user activity. Reauthentication of the subscriber SHALL be repeated following any period of inactivity lasting 30 minutes or longer.

The 12 hours enforcement can be set on the session level. The inactive enforcment needs to be implemented in your application.

This option is not configurable.
You can configure the session lifespan in the configuration:

```yaml title="path/to/kratos/config.yml
session:
  lifespan: 12h
```

Authenticator Assurance Level 3 (AAL3)​

This feature will be implemented at a later stage. Please visit the roadmap for more information on upcoming features.