Please read the Self-Service Flows overview before continuing with this document.
Ory Kratos allows users to verify their out-of-band (email, telephone number, ...) communication channels. Verification can be initiated
- after registration or by performing a verification flow;
- manually by the user.
There are two Verification Flow types supported in Ory Kratos:
- Flows where the user sits in front of the Browser (e.g. website, single page app, ...)
- Flows where API interaction is required (e.g. mobile app, Smart TV, ...)
The Verification Flow can be summarized as the following state machine:
To enable verification flows, make the following adjustments to your Ory Kratos configuration:
Using this feature implements the so-called "account activation" with the difference that Ory Kratos does not provide a feature that prevents signing into accounts without verified addresses. The reason being that verification is proving that the user controls the given address, but it is not an authentication mechanism.
You may however choose to limit what an identity without verified addresses is able to do in your application logic or API Gateways.
Currently, Ory Kratos only supports one verification method:
linkmethod performs verification of email addresses.
link method is dis/enabled in the Ory Kratos config:
Enabling this method will send out verification emails on new sign ups and when a verified email address is updated.
Before sending out a verification E-Mail, Ory Kratos will check if the email address is already known. Depending on the result, one of the two flows will be executed:
- Unknown email address: An email is sent to the address informing the recipient that someone tried to verify this email address but that it is not known by the system:
- Known email address: An email which includes a verification link is sent to the address:
This prevents Account Enumeration Attacks as it is not possible for a threat agent to determine if an account exists or not based on the verification flow.
The emails are using templates that can be customised as explained in Customizing E-Mail Templates. The template IDs are:
- Unknown email address:
- Known email address:
You must define at least one Identity Traits field as a verification field. You can do so by defining the following section in your Identity JSON Schema:
You can also combine this with the password method login identifier (see example
above). That way, the field
The first step is to initialize the Verification Flow. This sets up Anti-CSRF
tokens and more. Each verification flow has a
state parameter which follows
the state machine:
choose_methodindicates that the user has not chosen a verification method yet. This is useful when
linkis not the only verification method active.
sent_emailimplies that the verification email has been sent out.
passed_challengeis set when the user has clicked the verification link and completed the account verification.
The Verification Flow for browser clients relies on HTTP redirects between Ory Kratos, your Verification UI, and the end-user's browser:
The Flow UI (your application!) is responsible for rendering the actual Login and Registration HTML Forms. You can of course implement one app for rendering all the Login, Registration, ... screens, and another app (think "Service Oriented Architecture", "Micro-Services" or "Service Mesh") is responsible for rendering your Dashboards, Management Screens, and so on.
To initialize the Verification Flow, point the Browser to the initialization endpoint:
- Raw HTTP
The server responds with a HTTP 302 redirect to the Verification UI, appending
?flow=<flow-id> query parameter (see the curl example) to the URL
Never use API flows to implement Browser applications!
Using API flows in Single-Page-Apps as well as server-side apps opens up several potential attack vectors, including Login and other CSRF attacks.
The Verification Flow for API clients does not use HTTP Redirects and can be summarized as follows:
To initialize the API flow, the client calls the API-flow initialization endpoint (REST API Reference) which returns a JSON response:
- Raw HTTP
Fetching the Verification Flow (REST API Reference) is usually only required for browser clients but also works for Verification Flows initialized by API clients. All you need is a valid flow ID:
- Raw HTTP
- Go SDK
link verification mode will always open a link in the browser, even if it
was initiated by an API client. This is because the user clicks the link in
his/her email client, which opens the browser.
link method is enabled, it will be part of the
methods payload in
the Verification Flow:
The Verification User Interface is a route (page / site) in your application (server, native app, single page app) that should render a verification form.
In stark contrast to other Identity Systems, Ory Kratos does not render this HTML. Instead, you need to implement the HTML code in your application (e.g. NodeJS + ExpressJS, Java, PHP, ReactJS, ...), which gives you extreme flexibility and customizability in your user interface flows and designs.
You will use the Verification Flow JSON response to render the verification form UI, which could looks as follows depending on your programming language and web framework:
- Browser UI
- ExpressJS & Handlebars
- React Native
- Verification View
- Generic Form View
- Example Input Form Element
The form payloads are then submitted to Ory Kratos which follows up with:
- An HTTP 302 Found redirect pointing to the Verification UI for Browser Clients.
application/jsonresponse for API Clients.
To send the verification email, the end-user fills out the form. There might be validation errors such as a malformed email:
- Browser UI
- Missing Email
When validation errors happen, browser clients receive a HTTP 302 Found redirect to the Verification Flow UI, containing the Verification Flow ID which includes the error payloads.
For API Clients, the server typically responds with HTTP 400 Bad Request and the Verification Flow in the response payload as JSON.
On successful submission, an email will be sent to the provided address:
- Browser UI
- Email Sent
If the verification challenge (e.g. the link in the verification email) is invalid or expired, the user will be HTTP 302 redirected to the Verification UI.
When an invalid or expired challenge is used, Ory Kratos initializes a new Account Verification flow automatically. This flow will always be a Browser-based flow because the challenge is completed by clicking a link!
The new Verification Flow includes an error message such as the following:
- Browser UI
- Invalid Challenge
Please keep in mind that this part of the flow always involves a Browser!
If the verification challenge is completed (e.g. the sent verification link was
clicked), the end-user's Browser is redirected to the Verification UI with a
Verification Flow that has now the
- Browser UI
- Success State
You may also configure a redirect URL instead which would send the end-user to that configured URL.