feat: add docs on sms sending (#1625)

* feat: add docs on sms sending

* chore: u

* fix: text bugs

---------

Co-authored-by: Vincent Kraus <[email protected]>

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

@@ -0,0 +1,132 @@
+---
+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"
+```
+
+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
+
+SMS delivery can only be configured through the [Ory CLI](../../guides/cli/01_installation.mdx). Follow these steps:
+
+```mdx-code-block
+<Tabs groupId="console-or-cli">
+<TabItem value="cli" label="Ory CLI">
+```
+
+1. Download the [Ory Identities config](../../guides/cli/15_config-identity-service.mdx) 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://ZnVuY3Rpb24oY3R4KSB7CiAgVG86IGN0eC5yZWNpcGllbnQsCiAgQm9keTogY3R4LmJvZHksCn0= # 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,
+}
+```
+
+Fields available on the `ctx` object are:
+
+- `recipient`: The recipient's phone number
+- `body`: The message body
+- `template_type`: The template type, e.g. `verification_code`
+- `template_data`: The template data, e.g. `{ "VerificationCode": "1234", Idenity: { ... } }`
+- `message_type`: 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
+
+Only the `verification_code` and `login_code` templates support an SMS variant. Use the CLI to configure it:
+
+```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: "base64://WW91ciB2ZXJpZmljYXRpb24gY29kZSBpczoge3sgLlZlcmlmaWNhdGlvbkNvZGUgfX0="
+        login_code:
+          valid:
+            sms:
+              body:
+                plaintext: "base64://WW91ciBsb2dpbiBjb2RlIGlzOiB7eyAuTG9naW5Db2RlIH19"
+   ```
+
+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

@@ -1,10 +1,10 @@
 ---
 id: verify-email-account-activation
-title: Verify email addresses associated with users accounts
-sidebar_label: Email address verification
+title: Verify addresses associated with users accounts
+sidebar_label: Address verification
 ---
 
-# Email address verification
+# Address verification
 
 ```mdx-code-block
 import CodeTabs from "@theme/Code/CodeTabs"
@@ -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">
@@ -143,7 +151,7 @@ provides when registering their account. Other fields inside the `traits` sectio
 +            }
            }
          }
-       }
+       },
        "additionalProperties": false
      }
    }
@@ -274,7 +282,7 @@ For more information see the [hooks configuration](../../hooks/01_configure-hook
 ### Carry over verified status from Social Sign-In
 
 Some Social Sign-In providers like Google return the verified status of the email address. To carry over the verified status from
-the Social Sign-In provider, return `verified_addresses` in your Social Sign-In JsonNet snippet:
+the Social Sign-In provider, return `verified_addresses` in your Social Sign-In Jsonnet snippet:
 
 ```jsonnet
 local claims = {
@@ -329,6 +337,57 @@ email.
 
 If the verified address is not present in the identity's traits, the verified status is not carried over.
 
+## Phone number verification
+
+To send SMS messages, you need to have a trait in your identity schema that holds the phone number. The trait must be marked as a
+verifiable address via the `verification` extension. Here's an example of how to define such a trait in the identity schema:
+
+```json
+{
+  "$id": "https://schemas.ory.sh/presets/kratos/quickstart/phone-password/identity.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Person",
+  "type": "object",
+  "properties": {
+    "traits": {
+      "type": "object",
+      "properties": {
+        "email": {
+          "type": "string",
+          "title": "E-Mail",
+          "format": "email",
+          "ory.sh/kratos": {
+            "credentials": {
+              "password": {
+                "identifier": true
+              }
+            },
+            "verification": {
+              "via": "email"
+            }
+          }
+        },
+        "phone": {
+          "type": "string",
+          "title": "Phone number",
+          "format": "tel",
+          "ory.sh/kratos": {
+            // highlight-start
+            "verification": {
+              "via": "sms"
+            }
+            // highlight-end
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}
+```
+
+Make sure to configure an SMS channel in the Ory configuration. See the [SMS documentation](../../emails-sms/10_sending-sms.mdx).
+
 ## Choosing the right strategy
 
 Ory supports two strategies for verifying your user's addresses.

src/sidebar.js

@@ -160,7 +160,7 @@ module.exports = {
         },
         {
           type: "category",
-          label: "Sending emails",
+          label: "Sending emails & SMS",
           items: [
             {
               type: "autogenerated",