1- Multi-factor authentication (MFA) provides an additional layer of security that
2- helps ensure that the accounts of your users can't be easily compromised by
3- malicious actors.
1+ Multi-factor authentication (MFA) provides an additional layer of security that helps ensure that the accounts of your users can't
2+ be easily compromised by malicious actors.
43
54Nowadays, many of the passwords in use can be easily compromised because:
65
76- They are re-used across multiple websites and applications.
87- They were leaked to the web and sold to malicious actors.
9- - They are considered "weak" because they are short, have obvious, derivable
10- patterns, or contain easy-to-guess character strings.
11-
12- By enabling two-factor authentication in your project, you introduce an
13- additional verification step that can protect user login or self-service
14- actions, such as updating account information or credentials, from malicious
15- actors. For example, you might decide to require a user to log in with two
16- factors right at the start of the session. Alternatively, you could allow the
17- user to start the session by logging in with the first factor and only require
18- the second factor at the point where the user is about to perform a
19- security-sensitive operation.
20-
21- - Read the
22- <SameDeploymentLink
23- to = " kratos/mfa/step-up-authentication"
24- oss = " network/kratos/mfa/step-up-authentication"
25- >
26- step-up authentication
27- </SameDeploymentLink >
28- guide to learn more about dynamic MFA.
8+ - They are considered "weak" because they are short, have obvious, derivable patterns, or contain easy-to-guess character strings.
9+
10+ By enabling two-factor authentication in your project, you introduce an additional verification step that can protect user login
11+ or self-service actions, such as updating account information or credentials, from malicious actors. For example, you might decide
12+ to require a user to log in with two factors right at the start of the session. Alternatively, you could allow the user to start
13+ the session by logging in with the first factor and only require the second factor at the point where the user is about to perform
14+ a security-sensitive operation.
15+
16+ - Read the <SameDeploymentLink to = " kratos/mfa/step-up-authentication" oss = " network/kratos/mfa/step-up-authentication" >step-up
17+ authentication</SameDeploymentLink > guide to learn more about dynamic MFA.
2918
3019## Available methods
3120
3221Ory offers multiple second-factor authentication methods:
3322
3423### Time-based one-time password (TOTP)
3524
36- Time-based one time passwords (TOTP) are a flexible 2FA authentication method
37- based on a shared secret, and can be used both with browser-based apps and
38- native apps.
25+ Time-based one time passwords (TOTP) are a flexible 2FA authentication method based on a shared secret, and can be used both with
26+ browser-based apps and native apps.
3927
40- - Read
41- <SameDeploymentLink to = " kratos/mfa/totp" oss = " network/kratos/mfa/totp" >
42- Time-based one-time passwords (TOTP)
43- </SameDeploymentLink >
44- to learn more.
28+ - Read <SameDeploymentLink to = " kratos/mfa/totp" oss = " network/kratos/mfa/totp" >time-based one-time passwords
29+ (TOTP)</SameDeploymentLink > to learn more.
4530
4631### WebAuthn
4732
48- This method uses the
49- [ Web Authentication API] ( https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API ) ,
50- also known as WebAuthn, which allows servers to register and authenticate users
51- using public-key cryptography.
33+ This method uses the [ Web Authentication API] ( https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API ) , also known
34+ as WebAuthn, which allows servers to register and authenticate users using public-key cryptography.
5235
53- - Read
54- <SameDeploymentLink
55- to = " kratos/mfa/webauthn-fido-yubikey"
56- oss = " network/kratos/mfa/webauthn-fido-yubikey"
57- >
58- WebAuthn and FIDO2 (YubiKey)
59- </SameDeploymentLink >
60- to learn more.
36+ - Read <SameDeploymentLink to = " kratos/mfa/webauthn-fido-yubikey" oss = " network/kratos/mfa/webauthn-fido-yubikey" >WebAuthn and FIDO2
37+ (YubiKey)</SameDeploymentLink > to learn more.
6138
6239### Lookup Secrets
6340
64- Lookup Secrets, also known as Backup Codes or Recovery Codes, are a 2FA
65- fail-safe mechanism, rather than a standalone two-factor authentication method.
66- They can be used to complete the second factor when users lose access to their
67- selected 2FA method.
41+ Lookup Secrets, also known as Backup Codes or Recovery Codes, are a 2FA fail-safe mechanism, rather than a standalone two-factor
42+ authentication method. They can be used to complete the second factor when users lose access to their selected 2FA method.
6843
69- - Read
70- <SameDeploymentLink
71- to = " kratos/mfa/lookup-secrets"
72- oss = " network/kratos/mfa/lookup-secrets"
73- >
74- Lookup Secrets (Recovery Codes)
75- </SameDeploymentLink >
76- to learn more.
44+ - Read <SameDeploymentLink to = " kratos/mfa/lookup-secrets" oss = " network/kratos/mfa/lookup-secrets" >Lookup Secrets (Recovery
45+ Codes)</SameDeploymentLink > to learn more.
7746
7847### SMS
7948
80- SMS for MFA sends a one-time password to the user's registered mobile phone
81- number via text message.
49+ SMS for MFA sends a one-time password to the user's registered mobile phone number via text message.
8250
83- - Read the
84- <SameDeploymentLink
85- to = " kratos/mfa/mfa-via-sms"
86- oss = " network/kratos/mfa/mfa-via-sms"
87- >
88- Code via SMS
89- </SameDeploymentLink >
51+ - Read the <SameDeploymentLink to = " kratos/mfa/mfa-via-sms" oss = " network/kratos/mfa/mfa-via-sms" >Code via SMS</SameDeploymentLink >
9052 documentation to learn more.
9153
9254### Device authentication
9355
94- Passwordless authentication where the private key is hardware-resident on the
95- user's device.
56+ Passwordless authentication where the private key is hardware-resident on the user's device.
9657
97- Read the <SameDeploymentLink to = " kratos/passwordless/deviceauthn" >Device
98- authentication</ SameDeploymentLink > documentation to learn more.
58+ Read the <SameDeploymentLink to = " kratos/passwordless/deviceauthn" >Device authentication</ SameDeploymentLink > documentation to
59+ learn more.
9960
10061### Email
10162
10263Email for MFA sends a one-time code to the user's registered email address.
10364
104- - Read the
105- <SameDeploymentLink
106- to = " kratos/mfa/mfa-via-sms"
107- oss = " network/kratos/mfa/mfa-via-sms"
108- >
109- Code via Email
110- </SameDeploymentLink >
111- documentation to learn more.
65+ - Read the <SameDeploymentLink to = " kratos/mfa/mfa-via-sms" oss = " network/kratos/mfa/mfa-via-sms" >Code via
66+ Email</SameDeploymentLink > documentation to learn more.
11267
11368## Terminology
11469
11570Learn more about the terms and concepts used when talking about 2FA in Ory.
11671
11772### Authentication Method Reference (AMR)
11873
119- The Authentication Method Reference (AMR) is an array of authentication methods
120- used over the lifetime of an Ory Session.
74+ The Authentication Method Reference (AMR) is an array of authentication methods used over the lifetime of an Ory Session.
12175
12276The following methods can be present in a session:
12377
12478- ` password ` - When the user authenticated with their password.
12579- ` code ` - When the user authenticated by code sent via email address.
126- - ` oidc ` - When the user authenticated by signing in with a social sign-in
127- provider.
128- - ` totp ` - When the user authenticated by entering a time-based one-time
129- password.
130- - ` webauthn ` - When the user authenticated through a WebAuthn channel, such as
131- OS-level biometric authentication or a hardware token.
80+ - ` oidc ` - When the user authenticated by signing in with a social sign-in provider.
81+ - ` totp ` - When the user authenticated by entering a time-based one-time password.
82+ - ` webauthn ` - When the user authenticated through a WebAuthn channel, such as OS-level biometric authentication or a hardware
83+ token.
13284- ` lookup_secret ` - When the user entered a valid one-time recovery code.
13385
134- This is how the information is presented in the Ory Session when you fetch the
135- session from the Ory Identities API:
86+ This is how the information is presented in the Ory Session when you fetch the session from the Ory Identities API:
13687
13788``` json5 title="Sample Ory Session JSON payload"
13889{
@@ -154,8 +105,8 @@ session from the Ory Identities API:
154105}
155106```
156107
157- If a user authenticates multiple times over the lifetime of the same session
158- with the same method, every successful attempt will be present in the session:
108+ If a user authenticates multiple times over the lifetime of the same session with the same method, every successful attempt will
109+ be present in the session:
159110
160111``` json5 title="Sample Ory Session JSON Payload"
161112{
@@ -183,8 +134,7 @@ with the same method, every successful attempt will be present in the session:
183134
184135### Authenticator Assurance Level (AAL)
185136
186- The Authenticator Assurance Level (AAL) indicates how many authentication
187- factors the identity has completed.
137+ The Authenticator Assurance Level (AAL) indicates how many authentication factors the identity has completed.
188138
189139Authentication methods are classified into factors:
190140
@@ -201,14 +151,8 @@ Authentication methods are classified into factors:
201151
202152You can use ` code ` as first or second factor but not both at the same time.
203153
204- - Enabling
205- <SameDeploymentLink
206- to = " kratos/passwordless/passkeys"
207- oss = " network/kratos/passwordless/passkeys"
208- >
209- passwordless authentication with WebAuthn or Passkeys
210- </SameDeploymentLink >
211- isn't considered a second authentication factor.
154+ - Enabling <SameDeploymentLink to = " kratos/passwordless/passkeys" oss = " network/kratos/passwordless/passkeys" >passwordless
155+ authentication with WebAuthn or Passkeys</SameDeploymentLink > isn't considered a second authentication factor.
212156
213157:::
214158
@@ -219,7 +163,7 @@ The AAL parameter can take one of two values:
219163
220164:::danger
221165
222- Completing two first authentication factors doesn't give the user ` aal2 ` . For
223- example, logging in with a ` password ` and ` oidc ` is still ` aal1 ` .
166+ Completing two first authentication factors doesn't give the user ` aal2 ` . For example, logging in with a ` password ` and ` oidc ` is
167+ still ` aal1 ` .
224168
225169:::
0 commit comments