There are two Registration 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 Registration Flow can be summarized as the following state machine:
Currently, two registration methods are supported:
passwordfor signing up with an email / username and password;
oidcfor signing up using a social sign in provider such as Google or Facebook (check out the set up guide).
Both are dis/enabled in the ORY Kratos config:
The first step is to initialize the Registration Flow. This allows pre-registration hooks to run, set up Anti-CSRF tokens, and more.
The Registration Flow for browser clients relies on HTTP redirects between ORY Kratos, your Registration 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 Registration Flow, point the Browser to the initialization endpoint:
- Raw HTTP
The server responds with a HTTP 302 redirect to the Registration 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 Registration 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 Registration Flow (REST API Reference) is usually only required for browser clients but also works for Registration Flows initialized by API clients. All you need is a valid Registration Flow ID:
- Raw HTTP
- Go SDK
Before you start
Please read the Username / Email & Password Credentials Documentation first.
password method is enabled, it will be part of the
in the Registration Flow. ORY Kratos uses the Identity JSON Schema defined in
identity.default_schema_url to generate a list of form fields and add it to
the Registration Flow. Assuming we are using the Identity JSON Schema from the
the response would look as such:
Before you start
Check out the Sign in with GitHub, Google, ... Guide and learn how to set up this method!
The Social Sign Up Method (
oidc) enables you to use
- ORY Hydra;
- and every other OpenID Connect Certified Provider
Social Sign Up is currently not possible for API Clients. It will be possible in a future version, which is partially tracked as kratos#273
If enabled, the method contains an
oidc key with the configured sign in
providers as submit fields:
The Registration User Interface is a route (page / site) in your application (server, native app, single page app) that should render a registration 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 Registration Flow JSON response to render the registration form UI, which could looks as follows depending on your programming language and web framework:
- Browser UI
- ExpressJS & Handlebars
- React Native
- Registration 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 Registration UI for Browser Clients.
application/jsonresponse for API Clients.
To complete the registration process, the end-user fills out the form which must
include a field marked as the identifier
ory.sh/kratos.credentials.password.identifier: true) in the Identity JSON
Schema, for example:
If the registration payload is invalid (e.g. the password does not match the password policy, the email is missing, ...), the password method includes the validation errors:
- Browser UI
- Missing Email
- Password Policy Violation
When validation errors happen, browser clients receive a HTTP 302 Found redirect to the Registration Flow UI, containing the Registration Flow ID which includes the error payloads.
For API Clients, the server typically responds with HTTP 400 Bad Request and the Registration Flow in the response payload as JSON.
oidc method requires the user to go through an OAuth 2.0 or
OpenID Connect flow which involves logging into the upstream identity provider
(e.g. Google) and giving consent.
If the user has already sign up with the given provider before, the user will simply be logged in and no new ORY Kratos Identity will be created.
A possible validation error is a missing ID Token:
- Missing ID Token
What may also happen is that the ORY Kratos Identity Schema JSON includes a field which is required but was not provided by the upstream identity provider (e.g. Google). In those cases, the end-user's browser is returned to the registration screen with the form validation errors.
Let's assume the ORY Kratos Identity Schema JSON requires a
which was not provided by the upstream identity provider. This can happen when the user refuses to accept a certain scope (e.g. "Allow ORY Kratos access to my website") or if the provider simply does not have this data (e.g. the upstream identity provider does not collect the user's website).
In that case the end-user ends up at the registration screen and is prompted to provide the missing or invalid fields:
- Browser UI
- Missing Website
Completing the registration behaves differently for Browser and API Clients. The Registration Flow does not issue a ORY Kratos Login Session automatically which prevents Account Enumeration Attacks. If these types of attacks are not your concern, you can add the session hook which will issue a session after successful registration:
It is very important to add the "session" hook to the after
hooks. Otherwise your users need to use the login flow again to be able to get a
session. Account Enumeration Attacks with OpenID Connect sign in flows are
typically not an issue if you follow the guidelines in the
Sign in with GitHub, Google, Facebook, LinkedIn, Microsoft ... Guide!
When the registration is completed successfully, ORY Kratos responds with a HTTP 302 Redirect to the configured redirect URL.
session after hook is enabled, a
Set-Cookie HTTP Header is set
alongside the HTTP 302 redirect which contains the ORY Kratos Login Session
Now, whenever the browser is making a request (with cookies) to the
http://127.0.0.1/sessions/whoami endpoint, the session will be returned:
For API Clients, ORY Kratos responds with a JSON payload which includes the signed up identity:
session after hook is enabled, the ORY Kratos Login Session and ORY
Kratos Login Session Token are included in the response:
ORY Kratos allows you to configure hooks that run before and after a Registration Flow. This may be helpful if you'd like to restrict registration to IPs coming from your internal network or other logic.
For more information about hooks please read the Hook Documentation.