Skip to main content

Email address verification

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.

The verification flow is supported in both browsers and API clients.

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.

Configuration​

To configure account verification, go to Authentication → Email Verification in the Ory Console.

Identity schema​

To make an address verifiable, it must be marked as such in the identity schema. In most cases this is the email address the user provides when registering their account. Other fields inside the traits section are supported as well.

identity-schema.json
 {
   "$id": "https://schemas.ory.sh/presets/kratos/quickstart/email-password/identity.schema.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Person",
   "type": "object",
   "properties": {
     "traits": {
       "type": "object",
       "properties": {
         "email": {
           "type": "string",
           "format": "email",
           "ory.sh/kratos": {
             "credentials": {
               "password": {
                 "identifier": true
               }
             },
+            "verification": {
+              "via": "email"
+            }
           }
         }
       }
       "additionalProperties": false
     }
   }
 }

Attempted verification notifications​

When this option is on and users attempt to initiate verification for unregistered addresses, the system sends an attempted verification notification to the email address that was used in the attempt. This prevents account enumeration attacks as explained in this blog post by Troy Hunt.

info

By default, this feature is disabled in newly created Ory Network projects.

Follow these steps to enable sending attempted verification notifications:

Go to Ory Console → Email Verification to enable and toggle Notify unknown recipients on.

Email templates​

Ory Identities comes with default email templates for verification flows.

You can quickly replace the defaults and customize the messages to match the look and feel of your solution. Read the custom email template documentation to learn more.

Allow login only with verified email​

To allow only the users with a verified email to sign in, follow these steps:

Go to Authentication → Email Verification in the Ory Console and enable Require Verified Address for Login.

Choosing the right strategy​

Ory supports two strategies for verifying your user's addresses.

When using one-time codes to verify a user's address, Ory Identities sends an email with a 6-digit code to the user. They must enter the code in a dedicated UI text field to verify their address.

The email also contains a link, that takes the user to the verification form with the code pre-filled in the appropriate form field. The only thing the user must do to verify their address is to submit the form.

If the user completes the verification after the link or code expired, they must provide the email address associated with their account to get a new verification email.

Comparison​

"One-time code" (code) is the default, preferred, and recommended method by Ory.

Ory supports "magic links", but considers this method a legacy solution. Currently, the method is supported but should be considered deprecated and is set to be removed in future releases.

Consider using the code method as it mitigates many of the drawbacks of "magic links":

  • Some email virus scanners open links in emails to scan them. This invalidates the link and may prevent users from completing the flow even if they have the access to the defined address.
  • Flows initialized by apps on mobile phones or smart devices don't work with links.
  • Depending on the device settings, clicking a link from an email can open a different browser than the one used to initialize the flow. This can confuse your users.
caution

When you change the strategy from link to code in an existing project, you might need to adjust your UI. Make sure the flow works correctly with your UI implementation after changing the strategy.

Showing the verification flow after settings or registration​

To show the verification flow directly after the user has registered, see the registration documentation.

For settings, see the settings documentation.

Code examples​

The user interface for account verification is a page in your solution that renders the actual form elements for the user.

In contrast to other identity systems, Ory Identities (Ory Kratos) doesn't render this HTML directly. Instead, you need to implement the HTML code in your solution, which gives you complete flexibility and customizability in your user interface flows and designs. This part of your application then directly interfaces with Ory Identities through the API.

The API responds with a JSON document describing the form elements to render and actions the form should take upon submission, cancellation, etc. The following shows examples for a few different languages and frameworks.

Email Verification HTML Form