Skip to content

Commit f25269f

Browse files
hperlclaude
andcommitted
docs: keep MFA overview links inline
Same MDX block-JSX pitfall as the device authentication partials: a multi-line SameDeploymentLink inside a list item is parsed as block-level JSX and splits the bullet into separate paragraphs. Rewrite all seven affected links inline and format the file at the raised print width so prettier cannot reintroduce the shape. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent e4017db commit f25269f

2 files changed

Lines changed: 45 additions & 100 deletions

File tree

‎.prettierrc.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ module.exports = {
1313
"docs/**/*.md",
1414
"docs/**/*.mdx",
1515
"src/components/Shared/kratos/passwordless/deviceauthn/*.mdx",
16+
"src/components/Shared/kratos/01_mfa-overview.mdx",
1617
],
1718
options: {
1819
printWidth: 130,
Lines changed: 44 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,138 +1,89 @@
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

54
Nowadays, 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

3221
Ory 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

10263
Email 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

11570
Learn 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

12276
The 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

189139
Authentication methods are classified into factors:
190140

@@ -201,14 +151,8 @@ Authentication methods are classified into factors:
201151

202152
You 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

Comments
 (0)