Please read the Self-Service Flows overview before continuing with this document.
There are two Login 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 Login Flow can be summarized as the following state machine:
Currently, two login methods are supported:
passwordfor signing in with an email / username and password;
oidcfor signing in 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 Login Flow. This allows pre-login hooks to run, set up Anti-CSRF tokens, and more.
The Login Flow for browser clients relies on HTTP redirects between ORY Kratos, your Login 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 Login Flow, point the Browser to the initialization endpoint:
- Raw HTTP
The server responds with a HTTP 302 redirect to the Login UI, appending the
?flow=<flow-id> query parameter (see the curl example) to the URL configured
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 Login 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 Login Flow (REST API Reference) is usually only required for browser clients but also works for Login Flows initialized by API clients. All you need is a valid 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 Login Flow:
Before you start
Check out the Sign in with GitHub, Google, ... Guide and learn how to set up this method!
The Social Sign In Method (
oidc) enables you to use
- ORY Hydra;
- and every other OpenID Connect Certified Provider
Social Sign In 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 Login User Interface is a route (page / site) in your application (server, native app, single page app) that should render a login 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 Login Flow JSON response to render the login form UI, which could looks as follows depending on your programming language and web framework:
- Browser UI
- ExpressJS & Handlebars
- React Native
- Login 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 Login UI for Browser Clients.
application/jsonresponse for API Clients.
To complete the login, the end-user fills out their identifier (username, email, phone number, ...) and the password. Possible validation errors include a missing identifier or password, or invalid credentials:
- Browser UI
- Missing Email
- Wrong Credentials
When validation errors happen, browser clients receive a HTTP 302 Found redirect to the Login Flow UI, containing the Login Flow ID which includes the error payloads.
For API Clients, the server typically responds with HTTP 400 Bad Request and the Login 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 never signed in with the given provider before, a new account will be created. It is also possible to link upstream identities (e.g. Google profile) with an existing ORY Kratos identity.
A possible validation error is a missing ID Token:
- Missing ID Token
Completing the login behaves differently for Browser and API Clients.
When the login is completed successfully, ORY Kratos responds with a HTTP 302
Redirect to the
configured redirect URL.
Alongside the HTTP 302 Redirect is a
Set-Cookie header which contains the ORY
Kratos Login Session Cookie:
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 identity which just authenticated, the session, and the ORY Kratos Session Token:
The ORY Kratos Session Token can be checked at the
In some cases it is required to refresh a login session. This is the case when
updating one's password. Refreshing a session updates the
Refreshing a session will not log the user out, unless another user signs in.
To refresh a session, append
/self-service/login/browserfor browser Clients (e.g.
/self-service/login/apifor API Clients (e.g.
ORY Kratos allows you to configure hooks that run before and after a Login Flow. This may be helpful if you'd like to restrict logins to IPs coming from your internal network or other logic.
For more information about hooks please read the Hook Documentation.