feat: add docs on sms sending

docs/kratos/emails-sms/10_sending-sms.mdx

@@ -0,0 +1,127 @@
+---
+id: sending-sms
+title: Send SMS to your users
+sidebar_label: SMS delivery configuration
+---
+
+```mdx-code-block
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+import CodeBlock from "@theme/CodeBlock"
+```
+
+The Ory Network comes with an HTTP based SMS delivery option, that can be configured to point to any service that supports sending
+SMS via HTTP API, such as Twilio, Plivo, AWS SNS, or your own microservice.
+
+## Configuration
+
+The configuration can be done via the CLI only. Follow these steps:
+
+```mdx-code-block
+<Tabs groupId="console-or-cli">
+<TabItem value="cli" label="Ory CLI">
+```
+
+1. Download the Ory Identities config from your project and save it to a file:
+
+   ```shell
+   ## List all available projects
+   ory list projects
+
+   ## Get config
+   ory get identity-config {project-id} --format yaml > identity-config.yaml
+   ```
+
+2. Add the configuration for your custom SMTP server
+
+   ```yaml title="config.yml"
+   courier:
+     channels:
+       - id: sms
+         type: http
+         request_config:
+           url: https://api.twilio.com/2010-04-01/Accounts/AXXXXXXXXXXXXXX/Messages.json # Adjust your account ID
+           method: POST
+           body: base64://ZnVuY3Rpb24oY3R4KSB7ClRvOiBjdHguUmVjaXBpZW50LApCb2R5OiBjdHguQm9keSwKfQ== # see below
+           headers:
+             Content-Type: application/x-www-form-urlencoded # defaults to application/json
+           auth:
+             type: basic_auth # or api_key
+             config:
+               user: AXXXXXXX # adjust your credentials
+               password: XXXX # adjust your credentials
+   ```
+
+3. Update the Ory Identities configuration using the file you worked with:
+
+   ```shell
+   ory update identity-config {project-id} --file updated_config.yaml
+   ```
+
+### Body configuration
+
+The body of the above snippet decodes to the following Jsonnet template:
+
+```jsonnet
+function(ctx) {
+  To: ctx.Recipient,
+  Body: ctx.Body,
+}
+```
+
+All available fields on the `ctx` object are:
+
+- `Recipient`: The recipient's phone number
+- `Body`: The message body
+- `TemplateType`: The template type, e.g. `verification_code`
+- `TemplateData`: The template data, e.g. `{ "VerificationCode": "1234", Idenity: { ... } }`
+- `MessageType`: The message type, e.g. `sms`
+
+Read the [Jsonnet documentation](../../kratos/reference/jsonnet.mdx) to learn more about the Jsonnet templating language.
+
+```mdx-code-block
+</TabItem>
+</Tabs>
+```
+
+## Templates
+
+Currently, only the `verification_code` template supports an SMS variant. To configure it, use the CLI:
+
+```mdx-code-block
+<Tabs groupId="console-or-cli">
+<TabItem value="cli" label="Ory CLI">
+```
+
+1. Download the Ory Identities config from your project and save it to a file:
+
+   ```shell
+   ## List all available projects
+   ory list projects
+
+   ## Get config
+   ory get identity-config {project-id} --format yaml > identity-config.yaml
+   ```
+
+2. Add the configuration for your custom SMTP server
+
+   ```yaml title="config.yml"
+   courier:
+     templates:
+       verification_code:
+         valid:
+           sms:
+             body:
+               plaintext: "Your verification code is: {{ .VerificationCode }}"
+   ```
+
+3. Update the Ory Identities configuration using the file you worked with:
+
+   ```shell
+   ory update identity-config {project-id} --file updated_config.yaml
+   ```
+
+```mdx-code-block
+</TabItem>
+</Tabs>
+```

docs/kratos/mfa/30_sms.mdx

@@ -0,0 +1,79 @@
+---
+id: mfa-via-sms
+title: Code via SMS
+sidebar_label: SMS
+---
+
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import BrowserWindow from "@site/src/theme/BrowserWindow"
+```
+
+SMS can be used to deliver one time codes to users. Ory will deliver a 6-digit code to an SMS gateway of your choice, such as
+Twilio, Amazon SNS or your own application. These codes are valid for a short amount of time, usually 15 minutes or less. Once the
+user completes the challenge, by entering the code, the AAL of the session is upgraded to AAL2.
+
+:::note
+
+Ory currently only supports either MFA via SMS or passwordless login via Code, not both.
+
+:::
+
+```mdx-code-block
+<BrowserWindow url="https://playground.projects.oryapis.com/ui/login?aal=aal2&via=phone">
+
+![Recovery Codes generation in Ory Account Experience](../_static/mfa/11.png)
+
+</BrowserWindow>
+```
+
+## Configuration
+
+To enable MFA via SMS, you need to configure an SMS channel in the Ory configuration:
+
+```mdx-code-block
+<Tabs groupId="console-or-cli">
+<TabItem value="cli" label="Ory CLI" default>
+```
+
+1. Get the Ory Identities configuration from your project and save it to a file:
+
+   ```shell
+   ## List all available projects
+   ory list projects
+
+   ## Get config
+   ory get identity-config {project-id} --format yaml > identity-config.yaml
+   ```
+
+2. Find `code` in `selfservice.methods` and set `mfa_enabled` to `true`:
+
+   ```yaml title="identity-config.yaml"
+   code:
+     mfa_enabled: true
+   ```
+
+3. Update the Ory Identities configuration using the file you worked with:
+
+   ```shell
+   ory update identity-config {project-id} --file identity-config.yaml
+   ```
+
+```mdx-code-block
+  </TabItem>
+</Tabs>
+```
+
+## Integration
+
+To be able to send codes via SMS, you need to provide a custom SMS sender. Ory simply sends the code, the phone number and other
+metadata to a webhook of your choice. Please read the [SMS documentation](../emails-sms/10_sending-sms.mdx).
+
+To start a new MFA flow, for an already existing session, create a new login flow with the `aal` parameter set to `aal2`. You'll
+also need to specify which trait to use for delivering the code to the user. Make sure, this trait exists in the identity schema
+and set the `via` parameter to its identifier. For example, if you have a trait called `phone_number`, you'd set `via` to
+`phone_number`.
+
+Ory will return an error in the UI, if the trait does not exist in the identity's schema or the trait is empty in the current
+identity. So make sure this trait is required in your identity schema.

docs/kratos/self-service/flows/verify-email-account-activation.mdx

@@ -14,9 +14,9 @@ import TabItem from "@theme/TabItem"
 import RenderFlow from "@theme/Code/RenderFlow"
 ```
 
-Ory allows users to verify email addresses associated with their accounts. This is important to prove that the user has access to
-the address they used to create their account. If verification is enabled, Ory Identities starts the verification process
-automatically when users sign up. Users can also verify their addresses manually.
+Ory allows users to verify email addresses or phone numbers associated with their accounts. This is important to prove that the
+user has access to the address they used to create their account. If verification is enabled, Ory Identities starts the
+verification process automatically when users sign up. Users can also verify their addresses manually.
 
 The verification flow is supported in both browsers and API clients and can be summarized as the following state machine:
 
@@ -49,7 +49,8 @@ stateDiagram
 :::caution
 
 Completing account verification doesn't guarantee that the account is used by the person who performed the verification. We
-recommend implementing additional security mechanisms to ensure that verified accounts aren't taken over by malicious actors.
+recommend implementing additional security mechanisms to ensure that verified accounts aren't taken over by malicious actors, such
+as [TOTP](../../mfa/15_totp.mdx) or [FIDO2/WebAuthn](../../mfa/20_webauthn-fido-yubikey.mdx).
 
 :::
 
@@ -63,6 +64,13 @@ recommend implementing additional security mechanisms to ensure that verified ac
 To configure account verification, go to **Authentication** → **Email Verification** in the
 [Ory Console](https://console.ory.sh/projects/current/verification).
 
+:::caution
+
+For SMS verification to work, you'll also need to configure a `courier_channel` with the ID set to `sms` via the CLI. See the
+**Ory CLI** tab for more information.
+
+:::
+
 ```mdx-code-block
 </TabItem>
 <TabItem value="cli" label="Ory CLI">
@@ -139,7 +147,7 @@ provides when registering their account. Other fields inside the `traits` sectio
                }
              },
 +            "verification": {
-+              "via": "email"
++              "via": "email" # or sms if this is a phone number
 +            }
            }
          }