Account Recovery must be performed if access to an account needs to be recovered. Common use cases include:
- "Forgot password" flows
- "Lost MFA device" flows
To recover an account, two principal flows are supported:
- Browser-based (easy): This flow works for all applications running on top of a browser. Websites, single-page apps, Cordova/Ionic, and so on.
- API-based (advanced): This flow works for native applications like iOS (Swift), Android (Java), Microsoft (.NET), React Native, Electron, and others.
The flow described here is implemented by the link strategy.
Self-Service Account Recovery for Browser Applications
ORY Kratos supports browser applications that run on server-side (e.g. Java, NodeJS, PHP) as well as client-side (e.g. JQuery, ReactJS, AngularJS, ...).
Browser-based account recovery makes use of three core HTTP technologies:
- HTTP Redirects
- HTTP POST (
application/x-www-urlencoded) and RESTful GET requests.
- HTTP Cookies to prevent CSRF and Session Hijaking attack vectors.
The browser flow is the easiest and most secure to set up and integrated with. ORY Kratos takes care of all required session and CSRF cookies and ensures that all security requirements are fulfilled.
This flow is not suitable for scenarios where you use purely programmatic clients that do not work well with HTTP Cookies and HTTP Redirects.
The Account Recovery User Interface
The Account Recovery User Interface is a route (page / site) in your application that renders the account recovery User Interface / HTML Form.
Reference these UI endpoints your ORY Kratos config file:
You should also configure how long a session is privileged. The user will only be able to update his/her password (or any other credential) for the specified amount of time after completing the recovery flow.
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.
Each Recovery Strategy (Recovery Link, ...) is different, but they all boil down to the same abstract sequence:
The code example used here is universal and does not use an SDK because we want you to understand the fundamentals of how this flow works.
While this example assumes a Server-Side Application, a Client-Side (e.g. ReactJS) Application would work the same, but use ORY Kratos' Public API instead.
You will notice that this endpoint is very similar to the one documented for User Settings.
Implementing the view is simple as ORY Kratos provides you with all the information you need for rendering the forms. The following example illustrates a generic form generator (we use handlebars here) that works with ORY Kratos:
In your main "Recovery" view you would then consume this template for all the methods you want to support:
For details on payloads and potential HTML snippets consult the individual Self-Service Strategies for:
Server-Side Browser Applications
We recommend checking out the Quickstart Network Architecture for a high-level, exemplary, overview of the network. In summary:
- The SecureApp (your application) is exposed at http://127.0.0.1:4455 and
proxies requests matching path
./ory/kratos/public/*to ORY Krato's Public API Port.
- ORY Kratos exposes (for debugging only!!) the Public API at http://127.0.0.1:4433 and Admin API at http://127.0.0.1:4434.
- Within the "intranet" or "private network", ORY Kratos is exposed at http://kratos:4433 and http://kratos:4434. These URLs are be used by the SecureApp to communicate with ORY Kratos.
Keep in mind that his architecture is just one of many possible network architectures. It is however one of the simplest as well and it works locally. For production deployments you would probably use an Reverse Proxy such as Nginx, Kong, Envoy, ORY Oathkeeper, or others.
Account Recovery Process Sequence
The Account Recovery Flow is composed of several high-level steps summarized in this state diagram:
First, the flow is initiated by directing the user's browser to
This is called the "Account Recovery Init Endpoint".
Next, ORY Kratos does some internal processing (e.g. checks if a session cookie
is set, generates payloads for form fields, sets CSRF token, ...) and redirects
the user's browser to the Recovery UI URL which is defined using the
selfservice.flows.recovery.ui_url config or
SELFSERVICE_FLOWS_RECOVERY_UI_URL environment variable, which is set to the ui
endpoints - for example
The user's browser is thus redirected to
request query parameter
includes a unique ID which will be used to fetch contextual data for this
Your Server-Side Application makes a
GET request to
ORY Kratos responds with a JSON Payload that contains data (form fields, error
messages, ...) for all enabled Account Recovery Strategies:
Once the strategy is completed successfully (e.g. an email has been entered into the form and the user clicked submit), the user will be signed in and sent to the User Settings page with a privileged session, meaning that he/she is able to change the password in the next e.g. 15 minutes.
Client-Side Browser Applications
Because Client-Side Browser Applications do not have access to ORY Kratos' Admin
API, they must use the ORY Kratos Public API instead. The flow for a Client-Side
Browser Application is almost the exact same as the one for Server-Side
Applications, with the small difference that
would be called via AJAX instead of making a request to
To prevent brute force, guessing, session injection, and other attacks, it is
required that cookies are working for this endpoint. The cookie set in the
initial HTTP request made to
be set and available when calling this endpoint!
The initialization request
cannot be made via AJAX or API requests. You must open that URL in the
user's browser using e.g.
location.href or plain and simple old
Self-Service Account Recovery for API Clients
Will be addressed in a future release.