docs(credentials): add AAL explanation

docs/docs/concepts/credentials.mdx

@@ -0,0 +1,182 @@
+---
+id: credentials
+title: Overview
+---
+
+Each identity has one or more credentials associated with it:
+
+```yaml
+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
+
+```yaml
+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:
+
+```yaml
+# 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:
+
+```yaml
+# 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](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-63b.pdf):
+
+> 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 (e.g. sending a login code to your email /
+   phone).
+3. an OpenID Connect ID token.
+
+It is recommended to reauthenticate the session every 30 days. You can configure
+this by setting the session age to 30 days.
+
+<Tabs
+  defaultValue="oss"
+  values={[
+    {label: 'Ory Cloud Platform', value: 'ocp'},
+    {label: 'Ory Kratos', value: 'oss'}
+  ]}>
+  <TabItem value="ocp">
+
+    This option is currently not configurable.
+
+  </TabItem>
+  <TabItem value="oss">
+
+    You can configure the session lifespan in the configuration:
+
+    ```yaml title="path/to/kratos/config.yml
+    session:
+      lifespan: 720h # 30 days
+    ```
+
+  </TabItem>
+</Tabs>
+
+### 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 is 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.
+
+<Tabs
+  defaultValue="oss"
+  values={[
+    {label: 'Ory Cloud Platform', value: 'ocp'},
+    {label: 'Ory Kratos', value: 'oss'}
+  ]}>
+  <TabItem value="ocp">
+
+    This option is currently not configurable.
+
+  </TabItem>
+  <TabItem value="oss">
+
+    You can configure the session lifespan in the configuration:
+
+    ```yaml title="path/to/kratos/config.yml
+    session:
+      lifespan: 12h
+    ```
+
+  </TabItem>
+</Tabs>
+
+### Authenticator Assurance Level 3 (AAL3)
+
+AAL3 can currently not be achieved using Ory Kratos. We plan to provide AAL3
+capabilities once WebAuth is implemented.